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>OSJamMessage</TITLE>
9</HEAD>
10<BODY>
11<H1>OSJamMessage</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>BOOL OSJamMessage(
18OSMessageQueue*   mq,
19OSMessage         msg,
20s32             flags);</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><CODE><EM><CODE>msg</CODE></EM></CODE></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><CODE><EM><CODE>flags</CODE></EM></CODE></CODE></B></I></TD>
35<TD width="520">If set to <code>OS_MESSAGE_BLOCK</code>, the <code>OSJamMessage</code> function blocks on a full queue. If set to <code>OS_MESSAGE_NOBLOCK</code>, the <code>OSJamMessage</code> function returns immediately whether or not the queue is full.</TD>
36    </TR>
37  </TBODY>
38</TABLE>
39<H2>Return Values</H2>
40<P>Returns <code>TRUE</code> 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>The <code>OSJamMessage</code> and the <code>OSSendMessage</code> functions are similar except that the <code>OSJamMessage</code> inserts a message at the beginning of the specified message queue. Call this function when sending high priority messages.</P>
44<P>If <em><strong><code>flags</code></strong></em> is set to <code>OS_MESSAGE_BLOCK</code> and the queue is full, the thread that called this function is paused. 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 be paused again until the receiving thread makes an opening in the message queue.</P>
45<P>If <em><strong><code>flags</code></strong></em> is set to <code>OS_MESSAGE_NOBLOCK</code>, it returns to the calling thread immediately. When the queue isn't full, <code>TRUE</code> is returned. If the queue is full, <code>FALSE</code> is returned.</P>
46
47<H2>See Also</H2>
48<P><a href="../list.html#Thread" target="contents">Thread Functions</a>, <a href="../list.html#ThreadSynchronization" target="contents">Thread Synchronization Functions</a>, <a href="OSInitMessageQueue.html"><code>OSInitMessageQueue</code></a>, <a href="OSReceiveMessage.html"><code>OSReceiveMessage</code></a>, <a href="OSSendMessage.html"><code>OSSendMessage</code></a></P>
49<H2>Revision History</H2>
50<P>03/01/2006 Initial version.</p>
51</BODY>
52</HTML>