OS_ReadMessage

Syntax

#include <nitro/os.h>

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

Arguments

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

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.

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 in flags, the thread that called this function will be suspended if the queue is empty. The thread resumes immediately when message(s) are sent to the queue. If there are other receiving threads with higher priority, those are executed first, so be aware of the fact that they may remove the messages. If the message queue is empty when this thread comes to be executed, it will suspend again until another message is sent to the queue.

If OS_MESSAGE_NOBLOCK is set in flags, control immediately returns to the calling thread. If the queue is not empty, TRUE is returned. If it is empty, FALSE is returned.

Revision History

2004/03/12 Initial version.