# OS_SetVAlarm

## 構文

      #include <nitro/os.h>

      void OS_SetVAlarm(
                   OSVAlarm*       alarm,
                   s16             count,
                   s16             delay,
                   OSVAlarmHandler handler,
                   void*           arg );

## 引数

alarm | Vカウントアラームを設定するVカウントアラーム構造体へのポインタ
count | Vカウントアラームが発動する(handler が呼ばれる)Vカウント値
delay | 遅延を許可するVカウント数
handler | Vカウントアラームハンドラ
arg | Vカウントアラームハンドラが呼ばれるときの引数

## 返り値

なし。

## 説明

ワンショットのVカウントアラームを設定します。

Vカウントがcount で指定した値になったときにhandler が呼び出されます。handler は、

`typedef void (*OSVAlarmHandler)( void*);`

で定義された OSVAlarmHandler 型の関数です。handler は OS のVカウント割り込みのハンドラから呼び出されます。従って割り込みは禁止状態となっています。handler が呼び出されるとき、arg を引数に取ります。

他のカウントアラームや割り込み等で指定のVカウントちょうどに呼べない時に、どのぐらいの遅延を許可するかを delay で指定することが出来ます。例えば、count=100, delay=5 であれば、Vカウント=100 でハンドラを呼ぶことが出来なくても Vカウント=105 までに呼ぶことが可能なら呼び出します。 0　を指定すると指定のVカウントでしか呼び出されません。　OS_VALARM_DELAY_MAX ならば指定のVカウント以降、呼び出し可能になった時点で必ず呼び出されます。呼び出されなかったVアラームは次のフレームの指定Vカウントまで呼び出しを延期されます。詳細は `VAlarm の概要` の説明を参照して下さい。

すでにVカウントアラームがセットされているOSVAlarm構造体へのポインタを alarm に指定した場合、`OS_Panic()` で停止します。

下の例は、Vカウントアラームを設定し、次のVカウント=100の時に handle が呼び出され、"handler called. arg=0x12345678" と表示されます。

> (例)
> `#define COUNT 　100
> #define DELAY 　1100
> #define ARG　　　0x12345678
> OSVAlarm 　alarm;
> main()
> {
> ：
> OS_InitVAlarm();
> ：
> OS_CreateVAlarm( &alarm );
> OS_SetVAlarm( &alarm, COUNT, DELAY, handler, (void*)ARG );
> ：
> }
> void handler( void* arg )
> {
> OS_Printf( "handler called. arg=0x%x\n", arg );
> }`

注意： NITRO-SDK 2.0 RC1 以前はこの関数は4つの引数しか取らず、delay の指定を行なうことが出来ませんでした。内部的には delay=10 として扱っていましたが、これと互換性を保った関数として `OS_SetOneTimeVAlarm()` を用意していますので、必要ならばご利用ください。

## 参照

`OS_InitVAlarm, OS_CancelVAlarm, OS_SetPeriodicVAlarm, OS_SetVAlarmTag
OS_SetOneTimeVAlarm
`

## 履歴

2005/03/08 用語統一 [割込み] → [割り込み]
2004/10/22 引数に delay を追加。 また、詳細は `OS_InitVAlarm()` を参照と追記
2004/08/30 セットされているVアラーム構造体は使用できない記述を追加
2004/02/24 初版