PxMsgSend_Hnd()

Send normal message (handler service).

APPLIES TO

8.2.0

SYNOPSIS
PxMsg_t PxMsgSend_Hnd (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_Hnd function sends the message msg into the 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_Hnd 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_Hnd(msg, mbx);

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