# OS_ReceiveMessage

## C Specification

      #include <nitro/os.h>

      BOOL OS_ReceiveMessage(
               OSMessageQueue*   mq ,
               OSMessage*        msg ,
               s32               flag );

## Description

Removes a message from the message queue

This function also makes it possible to execute any thread waiting to send a message to the queue. The transmission threads execute in order of priority.

If `OS_MESSAGE_BLOCK` is set up in `flag`, 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 the message queue
`msg` | Received message
`flag` | When `OS_MESSAGE_BLOCK` is set, the `OS_ReceiveMessage` function blocks empty queues. When `OS_MESSAGE_NOBLOCK` is set, the `OS_ReceiveMessage` function immediately returns whether or not the queue is empty.

## Return Values

`TRUE` is returned when the message is successfully removed. `FALSE` is returned when the queue is empty and `OS_MESSAGE_NOBLOCK` is specified.

## See Also

`OS_InitMessageQueue`, `OS_SendMessage`, `OS_JamMessage`

## Revision History

12/01/2003 Initial Version