PxMsgAwaitRel()

Waits until a message is released.

APPLIES TO

1.0.0

SYNOPSIS
PxMsg_t PxMsgAwaitRel (PxMsg_t Msg);
ARGUMENTS






Msg




Message object to await release

















RETURN VALUES






    

  • 

    Msg on success
    

    • 

  • 

    Invalid message handle on failure
    

    • 







ERROR CODES















PXERR_MSG_ABORTED




The service was aborted by an event








PXERR_MSG_ILLMSG




The passed message handle is invalid








PXERR_MSG_ILLOWNER




The calling task is not the owner of the message








PXERR_MSG_NOT_IMPLEMENTED




The message has not been set to wait for its release









DESCRIPTION










The PxMsgAwaitRel waits for the message Msg to be released. The message Msg must be created by PxMsgEnvelop or set to AwaitRelease. The calling task must be the owner of the message whose release is being awaited. The owner is always the task that created the message.






















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 calling task must be the message’s creator (V), and if the message is created with PxMsgRequest…​, the message must be prepared by calling PxMsgSetToAwaitRel (V).
    

    • 



















After call






    

  • 

    The return value of PxMsgAwaitRel contains the id of the original message. This may also be checked with the appropriate macros. If the message id is valid, the message may be released by PxMsgRelease.
    

    • 



















Best Practice






    

  • 

    PxMsgAwaitRel may block, if the message is never released. If blocking calls are prohibited, PxMsgAwaitRel_NoWait should be used instead.
    

    • 






























SEE ALSO











USAGE








#include "pxdef.h"

PxMsg_t RetMsg = PxMsgAwaitRel(Msg)

if (PxMsgIdIsValid (RetMsg)) {
    // Handle message
}
else {
    // Report error
}