PxMsgSetProtection()

Set protection mode of a message.

APPLIES TO

8.2.0

SYNOPSIS
PxError_t PxMsgSetProtection (PxMsg_t msgid, PxProtectType_t protection);
ARGUMENTS
msgid

Message object for which the protection mode is changed

protection

New protection mode for the message data

RETURN VALUES
  • PXROS error code

ERROR CODES

PXERR_MSG_ILLMSG

The passed message handle is invalid

PXERR_MSG_ILLUSER

The calling task is not the user of the message

PXERR_PROT_PERMISSION

The calling task has no permission to change the protection

PXERR_MSG_ILLOWNER

The calling task is not the owner of the message

PXERR_PROT_ILL_HANDLE

Invalid pair number is given

PXERR_REQUEST_INVALID_PARAMETER

Request with invalid parameter

DESCRIPTION

PxMsgSetProtection sets the protection mode for the data area of a given message object msgid. The task has to be the owner (creator) of the message msgid! The following values are possible:

  • NoAccessProtection, the caller has no access to the messages data area

  • ReadProtection, the caller has read only access to the messages data area

  • WriteProtection, the caller has write only access to the messages data area

  • WRProtection, the caller has read and write access to the messages data area

The protection mode can only be changed if the caller has the appropriate permission. For example, the caller cannot set WriteProtection if it has no write access to the data area.

IMPLEMENTATION GUIDELINES
Before call
  • msgid 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).

  • protection must be of type PxProtectType_t and may have one of the following values (V):

    • NoAccessProtection neither read nor write access

    • ReadProtection read access

    • WriteProtection write access

    • WRProtection read and write access

After call
  • The function returns PXERR_NOERROR if the message’s protection mode is changed. Any other return value describes an error, which has to be interpreted (C).

Best Practice
  • No restrictions.

SEE ALSO
USAGE
#include "pxdef.h"

PxError_t Err = PxMsgSetProtection(msgid, ReadPermission);

if (Err != PXERR_NOERROR) {
    // Report error
}