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.
self | The instance |
NULL
if the Rx queue is empty.