PxMsgSend_PrioHnd()

Send prioritized message (handler service).

APPLIES TO

1.0.0

SYNOPSIS
PxMsg_t PxMsgSend_PrioHnd (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_PrioHnd function sends the prioritized message msg into the mailbox mbxid. The prioritized message is put in front of all potentionally waiting messages in 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_PrioHnd 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_PrioHnd(HndArg->msg, HndArg->mbx);

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