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_SetVAlarm</TITLE> 8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css"> 9</HEAD> 10<BODY> 11<H1 align="left">OS_SetVAlarm <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>void OS_SetVAlarm( 17 OSVAlarm* alarm , 18 s16 count , 19 s16 delay , 20 OSVAlarmHandler handler , 21 void* arg ); 22 </CODE></PRE> 23</DL> 24<H2>Arguments</H2> 25<TABLE border="1" width="100%"> 26 <TBODY> 27 <TR> 28 <TD width="13%"><EM><STRONG>alarm</STRONG></EM></TD> 29 <TD width="87%">Pointer to the V-Count alarm structure for setting V-Count alarm</TD> 30 </TR> 31 <TR> 32 <TD width="13%"><EM><STRONG>count</STRONG></EM></TD> 33 <TD width="87%">The V-Count value at which the V-Count alarm is actuated (the handler is called)</TD> 34 </TR> 35 <TR> 36 <TD><EM><STRONG>delay</STRONG></EM></TD> 37 <TD>The maximum permissible number of V-Counts for delay.</TD> 38 </TR> 39 <TR> 40 <TD><EM><STRONG>handler</STRONG></EM></TD> 41 <TD>The V-Count alarm handler</TD> 42 </TR> 43 <TR> 44 <TD><EM><STRONG>arg</STRONG></EM></TD> 45 <TD>The argument when calling the V-Count alarm handler</TD> 46 </TR> 47 </TBODY> 48</TABLE> 49<H2>Return Values</H2> 50<P>None.</P> 51<H2>Description</H2> 52<P>Sets up a one-time V-Count alarm</P> 53<P><code>handler</code> is called when the V-Count reaches the value specified by <code>count</code>. The V-Count alarm handler <code>handler</code> is an <code>OSVAlarmHandler</code> function defined by the following:</P> 54<P> <CODE>typedef void (*OSVAlarmHandler)( void*);</CODE></P> 55<P> <B><I>handler</I></B> is called from the OS V-Count interrupt handler. Therefore, interrupts are prohibited. When the <em><strong><code>handler</code></strong></em> is called, it takes <code><strong><em>arg</em></strong></code> as an argument.</P> 56<P>It is possible to specify the amount of permissible delay with <B><I>delay</I></B> when the handler cannot be called on the specified V-Count because of another count alarm or interrupt. For example, at count=100 and delay=5, V-Count is called if it is possible to call it by count 105, even if it was not possible to call it by count 100. When you specify <code>0</code>, the alarm is called only at the specified V-Count. If <code>OS_VALARM_DELAY_MAX</code>, it is always called when a call is possible for the specified V-Count and subsequent V-Counts. The V alarm that was not called will be postponed until the specified V-Count in the next frame. For details, see the description in <a href="about_VAlarm.html">VAlarm Overview</a>.</P> 57<P>If <code>alarm</code> is specified for the pointer to the <code>OSAlarm</code> structure in which the V-Count has been set, it stops with <a href="../debug/OS_Panic.html"><code>OS_Panic()</code></a>.</P> 58<P>The following example sets the V-Count alarm, calls <code>handle</code> when the next V-Count = 100, and displays "<code>handler called. arg=0x12345678</code>". </P> 59 60<BLOCKQUOTE>Example: <BR> 61<PRE>#define COUNT 100 62#define DELAY 1100 63#define ARG 0x12345678 64OSVAlarm alarm; 65 66main() 67{ 68 : 69 OS_InitVAlarm(); 70 : 71 OS_CreateVAlarm( &alarm ); 72 OS_SetVAlarm( &alarm , COUNT , handler , (void*)ARG ); 73 : 74} 75 76void handler( void* arg ) 77{ 78 OS_Printf( "handler called. arg=0x%x\n", arg ); 79}</PRE></BLOCKQUOTE> 80 81<P>Note: </strong></font> Prior to NITRO-SDK 2.0 RC1, this function took only four arguments and you could not specify the delay. Internally, it was treated as delay=10. But the <a href="OS_SetOneTimeVAlarm.html"><code>OS_SetOneTimeVAlarm()</code></a> function was added for your use if you prefer the old format over this new one.</P> 82<H2>See Also</H2> 83<P><CODE><A href="OS_InitVAlarm.html">OS_InitVAlarm</A>, <A href="OS_CancelVAlarm.html">OS_CancelVAlarm</A>, 84 <A href="OS_SetPeriodicVAlarm.html">OS_SetPeriodicVAlarm</A>, <A href="OS_SetVAlarmTag.html">OS_SetVAlarmTag</A><BR> 85 <A href="OS_SetOneTimeVAlarm.html">OS_SetOneTimeVAlarm</A><BR></CODE></P> 86<H2>Revision History</H2> 87<P> 882005/03/08 Standardized the Japanese word for "interrupt"<br /> 2004/10/22 Added delay to the arguments. 2004/08/30 Added description that the V alarm structure that has been set is not usable <BR>2004/02/24 Initial version</P> 89<hr><p>CONFIDENTIAL</p></body> 90</HTML>
