PxMsgAwaitRel()

Waits until a message is released.

APPLIES TO

8.2.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
}