OS_ReadMessage


C Specification

#include <nitro/os.h>

BOOL OS_ReadMessage(
         OSMessageQueue*   mq , 
         OSMessage*        msg , 
         s32               flags );

Description

Copies the starting message of the message queue

The status of the message queue does not change. This function differs from OS_ReceiveMessage() in that a wait status thread is not activated to send a message to this queue. In a manner of speaking, OS_ReadMessage() is a function for looking at the starting message of the message queue.

If OS_MESSAGE_BLOCK is set up in flags, the thread that called this function will be paused if the queue is empty. The thread resumes once the message is sent to the queue. If another receiving thread with a higher priority is present, those threads are executed first so be aware of the point at which messages are removed. If the message queue is empty when this thread is executed, it will be paused again until another message is sent to the queue.

If OS_MESSAGE_NOBLOCK is set up in flags, the process immediately returns to the thread that was called. If the queue is not empty, TRUE is returned. If it is empty, FALSE is returned.

Arguments

mq   Pointer to message queue
msg   Viewed message
flags   If OS_MESSAGE_BLOCK is set up, OS_ReadMessage blocks empty queues. If OS_MESSAGE_NOBLOCK is set up, OS_ReceiveMessage returns immediately whether the queue is empty or not.

Return Values

Returns TRUE if the message was removed without any problems. If OS_MESSAGE_NOBLOCK was specified and the queue was empty, FALSE is returned.

See Also

OS_InitMessageQueue, OS_SendMessage, OS_ReceiveMessage

Revision History

03/12/2004 Initial Version