Ucs_AmsRx_Msg_t* Ucs_AmsRx_PeekMsg

(

Ucs_Inst_t *

self

)

Retrieves a reference to the front-most message in the Rx queue.

The Application Message Service already provides a queue of completed Rx messages. Ucs_AmsRx_PeekMsg() always returns a reference to the front-most message in the Rx queue. The function call does not dequeue the message handle. Thus, multiple subsequent calls of Ucs_AmsRx_PeekMsg() will always return the same reference. After processing the front-most message, the application must call Ucs_AmsRx_ReleaseMsg().
Typically, an application will process the front-most Rx message and call Ucs_AmsRx_ReleaseMsg(), which dequeues and frees the Rx message. Hence, the application must not access this this reference anymore. The next call of Ucs_AmsRx_PeekMsg() returns a reference of the following Rx message, or NULL if no further message is available.
However, it is possible that an application cannot process an Rx message. In that case that application must not call Ucs_AmsRx_ReleaseMsg() so that the next call of Ucs_AmsRx_PeekMsg() returns again the reference to the un-processed message.

Parameters

self	The instance

Returns

Reference to the front-most message in the Rx queue or NULL if the Rx queue is empty.

Warning

It is important that the application takes care about the life time of the Rx message object. The returned reference is valid if the application performs the peek, processing and release operation in one go. A reference returned by Ucs_AmsRx_PeekMsg() might become invalid during a call of Ucs_Service(). The reason is that the UNICENS library might process an event which will flush the AMS Rx queue.