PxMsgReceive()

Receive a message from a mailbox.

APPLIES TO

1.0.0

SYNOPSIS

PxMsg_t PxMsgReceive (PxMbx_t mbxid);

ARGUMENTS

mbxid: The mailbox handle

RETURN VALUES

The received message handle

ERROR CODES

PXERR_MBX_ILLMBX

The passed mailbox handle is invalid

PXERR_MSG_NOMSG

No message available

PXERR_MSG_ILLMSG

The passed message handle is invalid

PXERR_MSG_ILLUSER

The calling task is not the user of the message

PXERR_EVENT_ZERO

The given event mask is zero

DESCRIPTION

PxMsgReceive receives a message object from mailbox mbxid and returns the received message handle. The task becomes the user of the received message. If there is no message in the mailbox mbxid, the PxMsgReceive waits until a message arrives.

IMPLEMENTATION GUIDELINES

Before call

The parameter mbxid must be a valid mailbox object id. This id may be
- the calling task’s own mailbox (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
- PxMsgIdIsValid() must be true.
- PxMsgIdGet() must not be _PXIllegalObjId.
- PxMsgIdError() must be PXERR_NOERROR otherwise the returned error code has to be interpreted (C).
or with a call of PxMbxCheck() (C).
The mailbox mbx must be created on the same core as the caller runs on. The creator core id can be read with the macro PxMbxCoreId and the own core id with PxGetCoreId (C).

After call

The returned value is the id of type PxMsg_t. 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).

Best Practice

PxMsgReceive may block, if no message is available at the mailbox. If blocking calls are prohibited, PxMsgReceive_NoWait should be used instead.

SEE ALSO

USAGE

#include "pxdef.h"

PxMsg_t Msg = PxMsgReceive(mbxid);

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