PxMsgSend_PrioHnd()

Send prioritized message (handler service).

APPLIES TO

8.2.0

SYNOPSIS
PxMsg_t PxMsgSend_PrioHnd (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_PrioHnd function sends the prioritized message msg into the mailbox mbxid. The prioritized message is put in front of all potentionally waiting messages in mailbox mbxid. The calling task must be the user of msg. The handler service requires that msg has a user. 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_PrioHnd 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
  • This function should be called from handlers only. (V)

  • As handlers are not allowed to request PXROS-HR objects, the message to be sent has to be requested by a PXROS-HR task and then passed to the handler.

SEE ALSO
USAGE
#include "pxdef.h"

PxMsg_t Msg = PxMsgSend_PrioHnd(HndArg->msg, HndArg->mbx);

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