PxMbxInstallHnd()

Install or remove a mailbox handler.

APPLIES TO

1.0.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
}