PxMsgRelease_Hnd()

Release a message object (handler service).

APPLIES TO

8.2.0

SYNOPSIS
PxMsg_t PxMsgRelease_Hnd (PxMsg_t Msg);
ARGUMENTS






Msg




Message object to be released

















ERROR CODES















PXERR_MSG_ILLMSG




The passed message handle is invalid








PXERR_MSG_ILLUSER




The calling task is not the user of the message








PXERR_MBX_ILLMBX




The passed message’s release mailbox handle is invalid








PXERR_MSGREL_NOT_INITED




The message release server is not yet initialized








PXERR_PROT_ILL_HANDLE




The associated protection handle is not valid








PXERR_REQUEST_INVALID_PARAMETER




Request with invalid parameter









DESCRIPTION










The PxMsgRelease_Hnd function releases the message Msg. All necessary cleanup operations are performed. For a envelope messages the release service checks if a task is waiting for the message being released. If so, the task is readied.






















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).
      

      • 

    

    

    • 



















After call






    

  • 

    PxMsgRelease_Hnd returns the message object to the object pool it has been taken from. On success PxMsgRelease_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






    

  • 

    After PxMsgRelease_Hnd, the given message object Msg is no longer valid and may never be used as message object!
    

    • 

  • 

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

    • 






























SEE ALSO











USAGE








#include "pxdef.h"

PxMsg_t Msg = PxMsgRelease_Hnd(Msg);

if (PxMsgIdIsValid(Msg)) {
    // Report error
}