PxMsgEnvelop_EvWait()

Envelops a data area in a newly created message object while waiting for events.

APPLIES TO

1.0.0

SYNOPSIS
PxMsgEvent_t PxMsgEnvelop_EvWait (PxMsgData_t data_area, PxSize_t msgsize, PxOpool_t opoolid, PxEvents_t events);
ARGUMENTS






data_area




The data area to be enveloped


















msgsize




The data area’s size


















opoolid




Object pool where to take the message object from


















events




Eventmask that makes the call return

















RETURN VALUES






    

  • 

    The received message handle, or the events, that caused the function to return
    

    • 







ERROR CODES















PXERR_OPOOL_ILLOPOOL




The passed object pool handle is invalid








PXERR_OBJ_NOOBJ




No free object is available








PXERR_OBJ_ABORTED




The request was aborted by an event








PXERR_OBJ_ILLOBJ




The passed object handle is not valid








PXERR_GLOBAL_ILLEGAL_CORE




The requested object pool is not on the same core








PXERR_EVENT_ZERO




The given event mask is 0 for awaiting events








PXERR_PROT_PERMISSION




The data area is not writable for the calling task








PXERR_MSG_ILL_ALIGN




Illegal aligned data pointer








PXERR_MSG_ILLMSG




Illegal aligned data pointer








PXERR_MSG_ILL_SIZE




Illegal data size








PXERR_INTERNAL_INCONSISTENCY




Inconsistency of internal structures









DESCRIPTION










The PxMsgEnvelop_EvWait function envelops a data area specified by arguments data_area (start address) and msgsize (size in bytes) in a new message object taken from object pool opool. The message object handle is returned. If there is no free object available, the PxMsgEnvelop_EvWait waits until a free object is available or until an event from mask of events is signaled.














In contrast to normal message object, The newly created envelope message object has implicitly set the await release flag. It is possible to wait for the message object release with function PxMsgAwaitRel or PxMsgAwaitRel_EvWait or check the release state by function PxMsgAwaitRel_NoWait.














The task that called PxMsgEnvelop_EvWait becomes the (permanent) owner and the (temporary) user of the created message. The task’s access rights to the data area is marked in the message object and can be read by calling PxMsgGetProtection. The owner may restrict the access right by calling PxMsgSetProtection.






















IMPLEMENTATION GUIDELINES
















Before call






    

  • 

    data_area must be a pointer to a valid data area.
    

    • 

  • 

    msgsize must be a plausible value given as a constant (V) or a variable (C).
    

    • 

  • 

    opoolid must be a valid PXROS-HR object pool and the calling task must have the access right to take objects from this object pool (V). The validity of opoolid may also be checked by the PxOpoolIsValid macro (F). The object pool must be created on the same core as the caller runs on. The creator core id can be read with the macro PxOpoolCoreId and the own core id with PxGetCoreId (C). Typically the task’s default object pool PXOpoolTaskdefault is used for this purpose.
    

    • 

  • 

    The parameter events contains a bitmask of events awaited and should not be zero. Typically the event mask is a constant (V).
    

    • 



















After call






    

  • 

    The returned value is a structure of type PxMsgEvent_t. The received events are stored in the events part, the message id is given in the msg part of the structure. 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






    

  • 

    If the message requested with PxMsgEnvelop_EvWait is sent to another task, the data_area must not be accessed by the requesting task until the recipient releases the message. PxMsgAwaitRel may be used to await the message’s release.PxMsgEnvelop_EvWait may block, if no PXROS-HR object is available and no instance (task or handler) sends an event. If blocking calls are prohibited, PxMsgEnvelop_NoWait should be used instead or the call should be monitored by the PXROS-HR PxTo mechanism.
    

    • 






























SEE ALSO











USAGE








#include "pxdef.h"

char Buf[BUFFER_SIZE] PXMEM_ALIGNED; /* The buffer is aligned to 8 bytes */
#define MY_EVENT_MASK 0x1l

PxMsgEvent_t msgEvHnd = PxMsgEnvelop_EvWait(Buf, 64, opoolid, MY_EVENT_MASK)

if (msgEvHnd.events & MY_EVENT_MASK) {
    // Handle events
}
else  if (PxMsgIdIsValid (msgEvHnd.msg)) {
    // Handle returned message
}
else {
    // Handle error
}