PxMsgSend_Prio()

Send prioritized message (task service).

APPLIES TO

8.2.0

SYNOPSIS

PxMsg_t PxMsgSend_Prio (PxMsg_t msg, PxMbx_t mbx);

ARGUMENTS

msg: The message handle to send

mbx: The mailbox handle

RETURN VALUES

Invalid message handle on success
Msg including PXROS error code on failure

ERROR CODES

PXERR_MBX_ILLMBX

The mailbox handle is invalid

PXERR_MSG_ILLMSG

The message handle is invalid

PXERR_MSG_ILLUSER

The sending task is not user of the message

PXERR_PROT_ILL_HANDLE

The associated protection handle is not valid

PXERR_REQUEST_INVALID_PARAMETER

Request with invalid parameter

PXERR_TASK_ILLTASK

The task is not a valid task object

DESCRIPTION

The PxMsgSend_Prio function sends the prioritized message msg into the mailbox mbxid. The prioritized message is put in front of all potentially waiting messages in mailbox mbxid. The calling task must be the user of msg. After the message is sent, it does not have a user (temporarily).

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 mbxid must be a valid mailbox object id. This id may be
- the calling task’s own mailbox (V)
- the return value of a PxTaskGetMbx() call (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
- PxMbxIdIsValid() must be true.
- PxMbxIdGet() must not be _PXIllegalObjId.
- PxMbxIdError() must be PXERR_NOERROR otherwise the returned error code has to be interpreted (C).
or with a call of PxMbxCheck() (C).

After call

On success PxMsgSend_Prio 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

No restrictions.

SEE ALSO

USAGE

#include "pxdef.h"

PxMsg_t Msg = PxMsgSend_Prio(msg, mbx);

if ((PxMsgIdError(Msg) != PXERR_NOERROR) || PxMsgIdIsValid(Msg)) {
    // Report error
}