PxMsgSend_Hnd()

Send normal message (handler service).

APPLIES TO

1.0.0

SYNOPSIS
PxMsg_t PxMsgSend_Hnd (PxMsg_t msg, PxMbx_t mbx);
ARGUMENTS






msg




The message handle to send


















mbx




The mailbox handle

















RETURN VALUES






    

  • 

    Invalid message handle on success
    

    • 

  • 

    Msg including PXROS error code on failure
    

    • 







ERROR CODES















PXERR_MBX_ILLMBX




The mailbox handle is invalid








PXERR_MSG_ILLMSG




The message handle is invalid








PXERR_MSG_ILLUSER




The sending task is not user of the message








PXERR_PROT_ILL_HANDLE




The associated protection handle is not valid








PXERR_REQUEST_INVALID_PARAMETER




Request with invalid parameter








PXERR_ILL_NULLPOINTER_PARAMETER




Illegal null pointer parameter in the call








PXERR_PROT_ILL_SIZE




The size of the protection region is not valid








PXERR_PROT_ILL_ALIGN




Alignment of protection region is not valid








PXERR_TASK_ILLTASK




The task is not a valid task object









DESCRIPTION










The PxMsgSend_Hnd function sends the message msg into the mailbox mbxid. The calling task must be the user of msg. The handler service requires that msg has a user. After the message is sent, it does not have a user (temporarily).






















IMPLEMENTATION GUIDELINES
















Before call






    

  • 

    Msg must be a valid message object, requested via PxMsgRequest…​ or PxMsgEnvelop…​ or received by a PxMsgReceive…​ call (V). This id may be checked with one of the following macros:
    

    

      

    • 

      PxMsgIdIsValid() must be true.
      

      • 

    • 

      PxMsgIdGet() must not be _PXIllegalObjId.
      

      • 

    • 

      PxMsgIdError() must be PXERR_NOERROR otherwise the returned error code has to be interpreted (C).
      

      • 

    

    

    • 

  • 

    The parameter mbxid must be a valid mailbox object id. This id may be
    

    

      

    • 

      the calling task’s own mailbox (V)
      

      • 

    • 

      the return value of a PxTaskGetMbx() call (V)
      

      • 

    • 

      the result of a nameserver query (V)
      

      • 

    • 

      part of a message sent by another task (V)
      

      • 

    

    

    • 

  • 

    The mailbox may be checked with the macros
    

    

      

    • 

      PxMbxIdIsValid() must be true.
      

      • 

    • 

      PxMbxIdGet() must not be _PXIllegalObjId.
      

      • 

    • 

      PxMbxIdError() must be PXERR_NOERROR otherwise the returned error code has to be interpreted (C).
      

      • 

    

    

    • 

  • 

    or with a call of PxMbxCheck() (C).
    

    • 



















After call






    

  • 

    On success PxMsgSend_Hnd returns the invalidated message object. This may be checked with one of the following macros:
    

    

      

    • 

      PxMsgIdIsValid() must be false.
      

      • 

    • 

      PxMsgIdGet() must be _PXIllegalObjId.
      

      • 

    • 

      PxMsgIdError() must be PXERR_NOERROR otherwise the returned error code has to be interpreted (C).
      

      • 

    

    

    • 



















Best Practice






    

  • 

    This function should be called from handlers only. (V)
    

    • 

  • 

    As handlers are not allowed to request PXROS-HR objects, the message to be sent has to be requested by a PXROS-HR task and then passed to the handler.
    

    • 






























SEE ALSO











USAGE








#include "pxdef.h"

PxMsg_t Msg = PxMsgSend_Hnd(msg, mbx);

if ((PxMsgIdError(Msg) != PXERR_NOERROR) || PxMsgIdIsValid(Msg)) {
    // Report error
}