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_ReadMessage</TITLE>
8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css">
9</HEAD>
10<BODY>
11<H1 align="left">OS_ReadMessage <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_ReadMessage(
17     OSMessageQueue*   mq,
18     OSMessage*        msg,
19     s32             flags);
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%">Viewed message</TD>
32    </TR>
33    <TR>
34      <TD><EM><STRONG>flags</STRONG></EM></TD>
35      <TD>If <CODE>OS_MESSAGE_BLOCK</CODE> is set up, <CODE>OS_ReceiveMessage</CODE> blocks empty queues. If <CODE>OS_MESSAGE_NOBLOCK</CODE> is set up, <CODE>OS_ReceiveMessage</CODE> returns immediately 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>Copies the starting message of the message queue The status of the message queue does not change. This function differs from <code><a href="OS_ReceiveMessage.html">OS_ReceiveMessage()</a></code> in that a wait status thread is not activated to send a message to this queue. In a manner of speaking, <CODE>OS_ReadMessage()</CODE> is a function for looking at the starting message of the message queue.</P>
47
48<P>If <code>OS_MESSAGE_BLOCK</code> is set in <em><strong><code>flags</code></strong></em>, 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.</P>
49
50<P>If <code>OS_MESSAGE_NOBLOCK</code> is set in <em><strong><code>flags</code></strong></em>, control immediately returns to the calling thread. If the queue is not empty, <code>TRUE</code> is returned. If it is empty, <code>FALSE</code> is returned.</P>
51
52
53<H2>See Also</H2>
54<P><code><a href="OS_InitMessageQueue.html">OS_InitMessageQueue</a></code>, <code><a href="OS_SendMessage.html">OS_SendMessage</a></code>, <code><a href="OS_ReceiveMessage.html">OS_ReceiveMessage</a></code></P>
55
56<H2>Revision History</H2>
57<P>2004/03/12 Initial version.</P>
58<hr><p>CONFIDENTIAL</p></body>
59</HTML>