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
13<H2>Syntax</H2>
14<dl><dd><pre class="construction">
15#include &lt;revolution/os.h&gt;
16
17BOOL OSJamMessage(
18    OSMessageQueue* mq,
19    OSMessage       msg,
20    s32             flags);
21</pre></dd></dl>
22
23<H2>Arguments</H2>
24<TABLE class="arguments" border="1" >
25  <TBODY>
26    <TR>
27<TH><STRONG><EM><CODE>mq</CODE></EM></STRONG></TH>
28<TD>Pointer to message queue.</TD>
29    </TR>
30    <TR>
31<TH>msg</TH>
32<TD>Message to send.</TD>
33    </TR>
34    <TR>
35<TH>flags</TH>
36<TD>If set to <CODE>OS_MESSAGE_BLOCK</CODE>, the <CODE>OSJamMessage</CODE> function will block a full queue. If set to <CODE>OS_MESSAGE_NOBLOCK</CODE>, the <CODE>OSJamMessage</CODE> function will return immediately whether the queue is full or not.</TD>
37    </TR>
38  </TBODY>
39</TABLE>
40
41<H2>Return Values</H2>
42<P>Returns <CODE>TRUE</CODE> if the message was successfully sent.</P>
43<P>Returns <CODE>FALSE</CODE> if <CODE>OS_MESSAGE_NOBLOCK</CODE> was specified and the queue is full.</P>
44
45<H2>Description</H2>
46<P>The <CODE>OSJamMessage</CODE> function is similar to the <CODE>OSSendMessage</CODE> function except that it inserts a message at the beginning of the specified message queue. Call this function when sending high priority messages.</P>
47<P>If <CODE>OS_MESSAGE_BLOCK</CODE> is set in <SPAN class="argument">flags</SPAN> and the queue is full, the thread that called this function is temporarily stopped. 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>
48<P>When <CODE>OS_MESSAGE_NOBLOCK</CODE> is set in <SPAN class="argument">flags</SPAN>, immediately returns to the calling thread. When the queue is not full, <CODE>TRUE</CODE> is returned. If the queue is full, <CODE>FALSE</CODE> is returned.</P>
49
50<H2>See Also</H2>
51<P class="reference">
52<A href="../toc.html#Thread" target="contents">Thread Functions</A>,
53<A href="../toc.html#ThreadSynchronization" target="contents">Thread Synchronization Functions</A>,
54<A href="OSInitMessageQueue.html">OSInitMessageQueue</A>,
55<A href="OSReceiveMessage.html">OSReceiveMessage</A>,
56<A href="OSSendMessage.html">OSSendMessage</A>
57</P>
58
59<H2>Revision History</H2>
60<P>
612006/03/01 Initial version.<br>
62</p>
63
64<hr><p>CONFIDENTIAL</p></body>
65</HTML>