SetWaitableTimer

指定した待機可能タイマをアクティブ化する。到来時刻になるとタイマがシグナル状態となり、タイマを設定したスレッドが省略可能な完了ルーチンを呼ぶ。

SetWaitableTimer hTimer, lpDueTime, lPeriod, pfnCompletionRoutine, lpArgToCompletionRoutine, fResume

hTimer : [intptr] タイマオブジェクトのハンドル。CreateWaitableTimer または OpenWaitableTimer が返す。
lpDueTime : [var] タイマがシグナル状態になるまでの時間（100 ナノ秒単位）。FILETIME 構造体の形式を使う。正の値は絶対時間を、負の値は相対時間を示す。絶対時間は UTC ベースで指定すること。実際のタイマ精度はハードウェア性能に依存する。UTC ベースの時刻については System Time を参照。
lPeriod : [int] タイマの周期（ミリ秒単位）。0 の場合タイマは一度だけシグナル状態になる。0 より大きい場合は周期タイマとなり、CancelWaitableTimer または再度の SetWaitableTimer まで周期ごとに自動再起動する。負の値を指定すると関数は失敗する。
pfnCompletionRoutine : [int] 省略可能な完了ルーチンへのポインタ。完了ルーチンはタイマがシグナル状態になったときに実行される PTIMERAPCROUTINE 型のアプリケーション定義関数。詳細は TimerAPCProc を参照。APC とスレッドプールスレッドについては備考を参照。
lpArgToCompletionRoutine : [intptr] 完了ルーチンに渡す構造体へのポインタ。
fResume : [int] TRUE の場合、タイマがシグナル状態に設定されたとき、サスペンド省電力モードにあったシステムを復帰させる。FALSE の場合は復帰させない。システムが復帰をサポートしない場合、呼び出しは成功するが GetLastError は ERROR_NOT_SUPPORTED を返す。

(プラグイン / モジュール : kernel32.dll)

解説

指定した待機可能タイマをアクティブ化する。到来時刻になるとタイマがシグナル状態となり、タイマを設定したスレッドが省略可能な完了ルーチンを呼ぶ。

[戻り値]
関数が成功した場合、戻り値は 0 以外である。関数が失敗した場合、戻り値は 0 となる。拡張エラー情報を取得するには
GetLastError を呼ぶ。

[備考]
タイマは初期状態では非アクティブである。アクティブ化するには SetWaitableTimer を呼ぶ。SetWaitableTimer
呼び出し時にタイマが既にアクティブだった場合、タイマは停止後に再アクティブ化される。この方法での停止はタイマ状態をシグナル状態にしないため、タイマ上で待機ブロックされているスレッドはブロックされたままとなる。ただし保留中の完了ルーチンはキャンセルされる。指定到来時刻になると、タイマは非アクティブになり、省略可能な
APC
がタイマを設定したスレッドのキューに入れられる。タイマ状態はシグナル状態となり、指定周期で再アクティブ化される。タイマを設定したスレッドが警告可能待機状態に入ると完了ルーチンが呼ばれる。タイマがスレッドの警告可能待機状態より先に設定されると
APC はキャンセルされる。詳細は QueueUserAPC
を参照。スレッドプールスレッドではシステムがそのスレッドの寿命を制御するため、APC
は他のシグナリング機構ほど確実に動作しない。pfnCompletionRoutine や別の APC
ベースのシグナリング機構を使う代わりに、CreateThreadpoolTimer
で作成したタイマなどの待機可能オブジェクトを使う。I/O には CreateThreadpoolIo で作成した I/O
完了オブジェクトや、SetThreadpoolWait に渡せる hEvent ベースの OVERLAPPED
構造体を使う。タイマを設定したスレッドが終了し、関連する完了ルーチンがある場合、タイマはキャンセルされる。ただしタイマ状態は変更されない。完了ルーチンがない場合、スレッド終了はタイマに影響しない。手動リセットタイマがシグナル状態になると、SetWaitableTimer
が再度呼ばれてリセットされるまでこの状態を維持する。よって周期手動リセットタイマは初回の到来時刻でシグナル状態になり、リセットされるまでシグナル状態を維持する。同期タイマがシグナル状態になると、スレッドが待機操作を完了するまでこの状態を維持する。システム時刻が調整されると、保留中の絶対タイマの到来時刻も調整される。本関数を使うアプリケーションをコンパイルするには
_WIN32_WINNT を 0x0400 以上に定義する。詳細は Using the Windows Headers
を参照。ウィンドウのイベントスケジュールには SetTimer を使う。タイマを扱う API
は様々なハードウェアクロックを使用する。これらのクロックの分解能は期待と大きく異なることがある。timeBeginPeriod /
timeEndPeriod の呼び出しで API の分解能を変更できる。

情報