1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<HTML>
3<HEAD>
4<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
5<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.0.0 for Windows">
6<META http-equiv="Content-Style-Type" content="text/css">
7<TITLE>OS_ReceiveMessage</TITLE>
8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css">
9</HEAD>
10<BODY>
11<H1 align="left">OS_ReceiveMessage <IMG src="../../image/NTR.gif" align="middle"><IMG src="../../image/TWL.gif" align="middle"></H1>
12<H2>Syntax</H2>
13<DL>
14  <DD>
15  <PRE><CODE>#include &lt;nitro/os.h&gt;</CODE></PRE>
16  <PRE><CODE>BOOL OS_ReceiveMessage(
17     OSMessageQueue*   mq,
18     OSMessage*        msg,
19     s32               flag );
20  </CODE></PRE>
21</DL>
22<H2>Arguments</H2>
23<TABLE border="1" width="100%">
24  <TBODY>
25    <TR>
26      <TD width="13%"><EM><STRONG>mq</STRONG></EM></TD>
27      <TD width="87%">Pointer to the message queue</TD>
28    </TR>
29    <TR>
30      <TD width="13%"><EM><STRONG>msg</STRONG></EM></TD>
31      <TD width="87%">Received message</TD>
32    </TR>
33    <TR>
34      <TD><EM><STRONG>flag</STRONG></EM></TD>
35      <TD>When <CODE>OS_MESSAGE_BLOCK</CODE> is set, the <CODE>OS_ReceiveMessage</CODE> function blocks empty queues. When <CODE>OS_MESSAGE_NOBLOCK</CODE> is set, the <CODE>OS_ReceiveMessage</CODE> function immediately returns whether or not the queue is empty.</TD>
36    </TR>
37  </TBODY>
38</TABLE>
39
40<H2>Return Values</H2>
41<P>
42Returns <code>TRUE</code> if the message was removed without any problems. If <code>OS_MESSAGE_NOBLOCK</code> was specified and the queue was empty, FALSE is returned.
43</P>
44
45<H2>Description</H2>
46<P>Removes a message from the message queue Also puts all threads waiting to send a message to this queue into executable state. The sending threads are executed in order of priority.</P>
47
48<P>If <code>OS_MESSAGE_BLOCK</code> is set up in <em><strong><code>flag</code></strong></em>, the thread that called this function will be paused 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.</P>
49
50<P>If <code>OS_MESSAGE_NOBLOCK</code> is set up in <em><strong><code>flag</code></strong></em>, the process immediately returns to the thread that was called. If the queue is not empty, <code>TRUE</code> is returned. If it is empty, <code>FALSE</code> is returned.</P>
51
52<H2>See Also</H2>
53<P><CODE><A href="OS_InitMessageQueue.html">OS_InitMessageQueue</A>, <A href="OS_SendMessage.html">OS_SendMessage</A>, <A href="OS_JamMessage.html">OS_JamMessage</A>, <A href="OS_ReadMessage.html">OS_ReadMessage</A><BR></CODE></P>
54
55<H2>Revision History</H2>
56<P>2004/03/12 Added <CODE>OS_ReadMessage</CODE> to <B>See Also</B>. <BR>2003/12/01 Initial version.</P>
57<hr><p>CONFIDENTIAL</p></body>
58</HTML>