PxMsgAwaitRel_EvWait()

Waits until a message is released or one of the given events is signaled.

APPLIES TO

1.0.0

SYNOPSIS
PxMsgEvent_t PxMsgAwaitRel_EvWait (PxMsg_t Msg, PxEvents_t events);
ARGUMENTS






Msg




Message object to await release


















events




Event mask to make the call return

















RETURN VALUES






    

  • 

    Event that made the function return
    

    • 







ERROR CODES















PXERR_MSG_ILLMSG




The passed message handle is invalid








PXERR_EVENT_ZERO




the given event mask is zero








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








PXERR_MSG_ABORTED




The service was aborted by an event while waiting for the message release









DESCRIPTION










The PxMsgAwaitRel_EvWait waits for the message Msg to be released or event from events to be signaled. 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 parameter events contains a bitmask of events awaited and should not be zero. Typically the event mask is a constant (V).
    

    • 

  • 

    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 returned value is a structure of type PxMsgEvent_t. The received events are stored in the events part, the message id is given in the msg part of the structure. This id may also be checked with the appropriate macros. If the message id is valid, the message may be released by PxMsgRelease.
    

    • 



















Best Practice






    

  • 

    PxMsgAwaitRel_EvWait may block, if the message is never released and no instance (task or handler) sends an event. If blocking calls are prohibited, PxMsgAwaitRel_NoWait should be used instead.
    

    • 






























SEE ALSO











USAGE








#include "pxdef.h"

#define MY_EVENT_MASK 0x1l

PxMsgEvent_t msgEvHnd = PxMsgAwaitRel_EvWait(Msg, MY_EVENT_MASK)

if (msgEvHnd.events & MY_EVENT_MASK) {
    // Handle events
}
else if (PxMsgIdIsValid(msgEvHnd.msg) && PxMsgIdError(msgEvHnd.msg) == PXERR_NOERROR) {
    // Handle message
}
else {
    // Handle error
}