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>OSSendMessage</TITLE>
9</HEAD>
10<BODY>
11<H1>OSSendMessage</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 OSSendMessage(
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">Message to send.</TD>
32    </TR>
33    <TR>
34<TD width="120" bgcolor="#ffffe8"><I><B><CODE>flags</CODE></B></I></TD>
35<TD width="520">When <code>OS_MESSAGE_BLOCK</code> is set, <code>OSSendMessage</code> blocks the full queue. When <code>OS_MESSAGE_NOBLOCK</code> is set, <code>OSSendMessage</code> returns whether or not the queue is full.</TD>
36    </TR>
37  </TBODY>
38</TABLE>
39<H2>Return Values</H2>
40<P><code>TRUE</code> is returned if the message is successfully sent.</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>Inserts a message at the end of the specified message queue. The function makes it possible for threads waiting in the message queue to execute. The receiving threads execute in order of priority.</P>
44<P>If <i><b><code>flags</code></b></i> is set to <code>OS_MESSAGE_BLOCK</code> and the queue is full, the calling thread will be paused.&nbsp;You can restart this thread by running a receiving thread and removing messages from the queue. Be aware that sending threads with a higher priority will execute first and may fill up the queue. In this case, this thread will temporarily pause again until the receiving thread makes an opening in the message queue.</P>
45<P>When <code>OS_MESSAGE_NOBLOCK</code> is set in <em><strong><code>flags</code></strong></em>, the called thread is returned immediately. When the queue is not full, <code>TRUE</code> is returned. If the queue is full, <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="OSReceiveMessage.html"><CODE>OSReceiveMessage</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>