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_WaitEvent</TITLE> 8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css"> 9</HEAD> 10<BODY> 11<H1 align="left">OS_WaitEvent* <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 <nitro/os.h></CODE></PRE> 16 <PRE><CODE>u32 OS_WaitEvent( OSEvent* event, 17 u32 pattern, 18 OSEventMode mode ); 19 20u32 OS_WaitEventEx( OSEvent* event, 21 u32 pattern, 22 OSEventMode mode, 23 u32 clearBit ); 24 25(Inline functions) 26static inline 27u32 OS_WaitEvent_And( OSEvent* event, 28 u32 pattern ); 29 30static inline 31u32 OS_WaitEvent_Or( OSEvent* event, 32 u32 pattern ); 33 34static inline 35u32 OS_WaitEventEx_And( OSEvent* event, 36 u32 pattern, 37 u32 clearBit ); 38 39static inline 40u32 OS_WaitEventEx_Or( OSEvent* event, 41 u32 pattern, 42 u32 clearBit ); 43 </CODE></PRE> 44</DL> 45<H2>Arguments</H2> 46<TABLE border="1" width="100%"> 47 <TBODY> 48 <TR> 49<TD width="13%"><CODE>event</CODE></TD> 50<TD width="87%">Pointer to an event structure.</TD> 51 </TR> 52 <TR> 53<TD><CODE>pattern</CODE></TD> 54<TD>Event flag bit pattern. Pattern for moving from the <I>waiting for event</I> state to the <I>runnable</I> state.</TD> 55 </TR> 56 <TR> 57<TD><CODE>mode</CODE></TD> 58<TD>Matching mode. Event flag bit pattern's conditions for conformance.</TD> 59 </TR> 60 <TR> 61<TD><CODE>clearBit</CODE></TD> 62<TD>Bits to clear from the event flag after the conditions are fulfilled.</TD> 63 </TR> 64 </TBODY> 65</TABLE> 66<H2>Return Values</H2> 67<P>Returns the value of the event flag when the conditions have been fulfilled and the waiting has finished.<BR>If <CODE>clearBit</CODE> is specified, the function will return the value before the bits were cleared.</P> 68<H2>Description</H2> 69<P>Waits for an event.<BR>To begin waiting, you can make a thread transition itself to the waiting state using the <A href="../thread/OS_SleepThread.html"><CODE>OS_SleepThread</CODE></A> function.</P> 70<P>The <CODE>event</CODE> argument is a pointer to an event structure and must have been initialized in advance using the <A href="OS_InitEvent.html"><CODE>OS_InitEvent</CODE></A> function.</P> 71<P>There is a <CODE>u32</CODE>-type event flag within <CODE>event</CODE>, and waiting for an event will end when that value is a certain bit pattern. That bit pattern is specified using <CODE>pattern</CODE> and <CODE>mode</CODE>. Waiting will end when the flag bits indicated by <CODE>pattern</CODE> match the conditions expressed in <CODE>mode</CODE>. The meaning of <CODE>mode</CODE> is shown in the following table. (If <CODE>pattern</CODE> contains only a single bit set to 1, there is no difference between them.)<BR> 72</P> 73<TABLE border="1"> 74 <TBODY> 75 <TR> 76<TH>Value of <CODE>mode</CODE> in the <CODE>OSEvent</CODE> Structure</TH> 77<TH>Completion Conditions</TH> 78 </TR> 79 <TR> 80<TD><CODE>OS_EVENT_MODE_AND</CODE></TD> 81<TD>Stop waiting when all bits become 1</TD> 82 </TR> 83 <TR> 84<TD><CODE>OS_EVENT_MODE_OR</CODE></TD> 85<TD>Stop waiting when any bits become 1</TD> 86 </TR> 87 </TBODY> 88</TABLE> 89<P><BR> If the conditions have already been fulfilled, control will leave the function immediately without switching threads.</P> 90<P>When the event flag member of <CODE>event</CODE> fulfills the conditions and control leaves the function, <CODE>OS_WaitEventEx()</CODE> will clear the bits indicated by <CODE>clearBit</CODE>. The bits will still be cleared even if the conditions are already fulfilled when the function is called, because <CODE>clearBit</CODE> is enabled. If the <CODE>OS_WaitEvent</CODE> function is used, they will not be cleared .</P> 91<P>The function's return value will be the value of the event flag when the conditions are fulfilled. However, with the <CODE>OS_WaitEventEx</CODE> function, the function will return the value before the bits are cleared.</P> 92<P><B>y</B></P> 93<P><CODE>OS_WaitEvent<FONT color="#ff0000">_And</FONT>( event, pattern )</CODE> is the same as <CODE>OS_WaitEvent( event, pattern, <FONT color="#ff0000">OS_EVENT_MODE_AND</FONT> )</CODE>.</P> 94<P><CODE>OS_WaitEvent<FONT color="#ff0000">_Or</FONT>( event, pattern )</CODE> is the same as <CODE>OS_WaitEvent( event, pattern, <FONT color="#ff0000">OS_EVENT_MODE_OR</FONT> )</CODE>.</P> 95<P><CODE>OS_WaitEventEx<FONT color="#ff0000">_And</FONT>( event, pattern, clearBit )</CODE> is the same as <CODE>OS_WaitEventEx( event, pattern, <FONT color="#ff0000">OS_EVENT_MODE_AND</FONT>, clearBit )</CODE>.</P> 96<P><CODE>OS_WaitEventEx<FONT color="#ff0000">_Or</FONT>( event, pattern, clearBit )</CODE> is the same as <CODE>OS_WaitEventEx( event, pattern, <FONT color="#ff0000">OS_EVENT_MODE_OR</FONT>, clearBit )</CODE>.</P> 97<H2>See Also</H2> 98<P><A href="OS_InitEvent.html"><CODE>OS_InitEvent</CODE></A><BR> <A href="OS_SignalEvent.html"><CODE>OS_SignalEvent</CODE></A><BR> <A href="OS_ClearEvent.html"><CODE>OS_Clear*Event</CODE></A><BR> <A href="OS_PollEvent.html"><CODE>OS_PollEvent*</CODE></A><BR> <A href="about_Event.html">OS Overview (Events)</A></P> 99<H2>Revision History</H2> 100<P>2007/12/04 Initial version.</P> 101<hr><p>CONFIDENTIAL</p></body> 102</HTML>
