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="Microsoft FrontPage 5.0">
6<META http-equiv="Content-Style-Type" content="text/css">
7<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css">
8<TITLE>OSReceiveMessage</TITLE>
9</HEAD>
10<BODY>
11<H1>OSReceiveMessage</H1>
12<H2>C Specification</H2>
13<DL>
14  <DD>
15  <PRE><CODE>#include &lt;revolution/os.h&gt;</CODE></PRE>
16  <DD>
17  <PRE><CODE>BOOL OSReceiveMessage(
18    OSMessageQueue* mq,
19    OSMessage*      msg,
20    s32             flags);</CODE></PRE>
21</DL>
22<H2>Arguments</H2>
23<TABLE border="1" cellpadding="3" cellspacing="0.1">
24  <TBODY>
25    <TR>
26<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>mq</CODE></EM></STRONG></CODE></B></I></TD>
27<TD width="520">Pointer to message queue.</TD>
28    </TR>
29    <TR>
30<TD width="120" bgcolor="#ffffe8"><I><B><CODE>msg</CODE></B></I></TD>
31<TD width="520">Pointer to the message being received.</TD>
32    </TR>
33    <TR>
34<TD width="120" bgcolor="#ffffe8"><I><B><CODE>flags</CODE></B></I></TD>
35<TD width="520">If <CODE>OS_MESSAGE_BLOCK</CODE> is set up, <CODE>OSReceiveMessage</CODE> blocks empty queues. When <CODE>OS_MESSAGE_NOBLOCK</CODE> is set, the <CODE>OSJamMessage</CODE> function immediately returns whether or not the queue is empty. </TD>
36    </TR>
37  </TBODY>
38</TABLE>
39<H2>Return Values</H2>
40<P>Returns <code>TRUE</code> if the message was removed without any problems. </P>
41<P>Returns <code>FALSE</code> if <code>OS_MESSAGE_NOBLOCK</code> was specified and the queue is full.</P>
42<H2>Description</H2>
43<P>Extracts messages from the message queue. With this function, you can execute any waiting threads to send a message to the queue. The sending threads execute in order of priority.</P>
44<P>If <code>OS_MESSAGE_BLOCK</code> is set up in <em><strong><code>flags</code></strong></em>, 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. Other receiving threads with a higher priority are executed first so be aware of when messages are removed. If the message queue is empty when this thread is executed, it will pause again until another message is sent to the queue.</P>
45<P>If <code>OS_MESSAGE_NOBLOCK</code> is set up in <em><strong><code>flags</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>
46<P>This function may put the current thread to sleep. For precautions when calling similar functions, refer to <A href="../Interrupt/intro.html">Interrupts and Callback Functions</A>.</P>
47
48<H2>See Also</H2>
49<P><A href="../toc.html#Thread" target="contents">Thread Functions</A>, <A href="../toc.html#ThreadSynchronization" target="contents">Thread Synchronization Functions</A>,<BR> <A href="OSInitMessageQueue.html"><CODE>OSInitMessageQueue</CODE></A>, <A href="OSJamMessage.html"><CODE>OSJamMessage</CODE></A>, <A href="OSSendMessage.html"><CODE>OSSendMessage</CODE></A>, <A href="../Interrupt/intro.html">Interrupts and Callback Functions</A></P>
50<H2>Revision History</H2>
51<p>
522007/09/25 Added information on the sleeping status of threads.<br>2006/03/01 Initial version. <br>
53</p>
54<hr><p>CONFIDENTIAL</p></body>
55</HTML>