PxMbxInstallHnd()

Install or remove a mailbox handler.

APPLIES TO

8.2.0

SYNOPSIS
PxError_t PxMbxInstallHnd (PxMbx_t mbx, PxMsg_t (*hnd) (PxMsg_t, PxMsgType_t, PxArg_t), PxMsgType_t mode, PxArg_t arg);
ARGUMENTS
mbx

Mailbox where to install the handler

hnd

Pointer to the handler

mode

Activating messages

arg

Argument (private data) for the handler

RETURN VALUES
  • PXROS error code

ERROR CODES

PXERR_ACCESS_RIGHT

The calling task has not the right to install handlers

PXERR_MBX_HNDINSTALLED

There is already a handler installed

PXERR_MBX_ILLMBX

mbx is not a valid mailbox

PXERR_MBX_ILLMODE

mode is not a known mode for a mailbox handler

DESCRIPTION

PxMbxInstallHnd installs or removes a mailbox handler. If hnd is zero, a possibly existing handler at the mailbox specified in mbx is removed. If hnd is nonzero, PxMbxInstallHnd installs the handler hnd at the mailbox mbx with private data arg. msgtype specifies the type of messages activating the handler. msgtype may be one of the following values:

  • PXMsgNormalMsg for normal messages

  • PXMsgPrioMsg for prioritized messages, or

  • PXMsgAnyMsg for both normal and prioritized messages.

When a message msg of type msgtype is sent to the mailbox, PXROS activates the mailbox handler assigned to the mailbox with the call:

hnd(&msg, msgtype, arg).

PXROS expects diagnostic information from the handler:

  • If the handler returns PxMsgId(id == _PXIllegalObjId, error == PXERR_NOERROR) PXROS assumes that the message has been completely processed by the handler. The application’s send call then returns successfully, and the message is not placed in the mailbox.

  • If the handler returns PxMsgId(id != _PXIllegalObjId, error == PXERR_NOERROR) PXROS places the message in the mailbox. The application’s send call returns successfully.

  • If the handler returns PxMsgId(id != _PXIllegalObjId, error != PXERR_NOERROR), PXROS assumes that the handler has refused the message by returning an error indicator. The application’s send call then fails by propagating the handler’s error code.

When the mailbox handler is called the message’s user is set to the installer task of the handler, so the mailbox handler may call all message-related functions that require a valid user.

IMPLEMENTATION GUIDELINES
Before call
  • Mbx must be a valid PXROS-HR mailbox object created with a PxMbxRequest call or the task’s private mailbox (V). The validity of Mbx may also be checked by the PxMbxIsValid macro (F).

  • hnd has to be a pointer to a valid function (V).

  • The PXROS-HR message type given in mode must be of type PxMsgType_t and may have one of the following values (V):

    • PXMsgAnyMsg

    • PXMsgNormalMsg

    • PXMsgPrioMsg

After call
  • The function returns PXERR_NOERROR if the mailbox handler has been installed. Any other return value describes an error, which has to be interpreted. (C)

Best Practice
  • PxMbxInstallHnd should only be called during initialization to ensure the availability of the mailbox handler.

SEE ALSO
USAGE
#include "pxdef.h"

PxError_t Err = PxMbxInstallHnd(mbx, MbxHnd, PXMsgAnyMsg, (PxArg_t) 0);

if (Err != PXERR_NOERROR) {
    // Report error
}