SetWaitableTimer 関数 (synchapi.h)
指定した待機可能タイマーをアクティブにします。 期限が到着すると、タイマーが通知され、タイマーを設定したスレッドがオプションの完了ルーチンを呼び出します。
構文
BOOL SetWaitableTimer(
[in] HANDLE hTimer,
[in] const LARGE_INTEGER *lpDueTime,
[in] LONG lPeriod,
[in, optional] PTIMERAPCROUTINE pfnCompletionRoutine,
[in, optional] LPVOID lpArgToCompletionRoutine,
[in] BOOL fResume
);
パラメーター
[in] hTimer
タイマー オブジェクトへのハンドル。 CreateWaitableTimer または OpenWaitableTimer 関数は、このハンドルを返します。
ハンドルには 、TIMER_MODIFY_STATE アクセス権が必要です。 詳細については、「 同期オブジェクトのセキュリティとアクセス権」を参照してください。
[in] lpDueTime
100 ナノ秒間隔で、タイマーの状態がシグナルに設定されるまでの時間。 FILETIME 構造体で記述されている形式を使用します。 正の値は絶対時間を示します。 システムは内部的に UTC ベースの時刻を使用するため、UTC ベースの絶対時刻を使用してください。 負の値は相対時間を示します。 実際のタイマー精度は、ハードウェアの機能によって異なります。 UTC ベースの時刻の詳細については、「 システム時刻」を参照してください。
[in] lPeriod
タイマーの期間 (ミリ秒単位)。 lPeriod が 0 の場合、タイマーは 1 回通知されます。 lPeriod が 0 より大きい場合、タイマーは定期的です。 定期的なタイマーは、 CancelWaitableTimer 関数を使用してタイマーが取り消されるか、 SetWaitableTimer を使用してリセットされるまで、期間が経過するたびに自動的に再アクティブ化されます。 lPeriod が 0 未満の場合、関数は失敗します。
[in, optional] pfnCompletionRoutine
省略可能な完了ルーチンへのポインター。 完了ルーチンは、タイマーが通知されたときに実行される PTIMERAPCROUTINE 型のアプリケーション定義関数です。 タイマー コールバック関数の詳細については、「 TimerAPCProc」を参照してください。 APC とスレッド プール スレッドの詳細については、「解説」を参照してください。
[in, optional] lpArgToCompletionRoutine
完了ルーチンに渡される構造体へのポインター。
[in] fResume
このパラメーターが TRUE の場合は、タイマー状態がシグナル状態に設定されている場合に、システムを一時停止電力節約モードで復元します。 それ以外の場合、システムは復元されません。 システムが復元をサポートしていない場合、呼び出しは成功しますが、GetLastError はERROR_NOT_SUPPORTEDを返します。
戻り値
関数が成功すると、戻り値は 0 以外になります。
関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
タイマーは最初は非アクティブです。 タイマーをアクティブにするには、 SetWaitableTimer を呼び出します。 SetWaitableTimer を呼び出すときにタイマーが既にアクティブになっている場合、タイマーは停止され、再アクティブ化されます。 この方法でタイマーを停止しても、タイマー状態はシグナル状態に設定されないため、タイマーの待機操作でブロックされたスレッドはブロックされたままです。 ただし、保留中の完了ルーチンはすべて取り消されます。
指定された期限が到着すると、タイマーは非アクティブになり、未処理の APC が既にキューに登録されていない場合、タイマーを設定するスレッドにオプションの APC がキューに入れられます。 タイマーの状態はシグナルに設定され、タイマーは指定された期間を使用して再アクティブ化され、タイマーを設定したスレッドは、警告可能な待機状態になると完了ルーチンを呼び出します。 詳細については、「 QueueUserAPC」を参照してください。 システムがスレッド プール スレッドの有効期間を制御するため、通知が配信される前にスレッドを終了できるため、APC はスレッド プール スレッドの他のシグナリング メカニズムと同様に機能しないことに注意してください。 pfnCompletionRoutine パラメーターまたは別の APC ベースのシグナリング メカニズムを使用する代わりに、CreateThreadpoolTimer で作成されたタイマーなどの待機可能オブジェクトを使用します。 I/O の場合は、CreateThreadpoolIo で作成された I/O 完了オブジェクト、またはイベントを SetThreadpoolWait 関数に渡すことができる hEvent ベースの OVERLAPPED 構造体を使用します。
タイマーを設定したスレッドが終了し、関連付けられた完了ルーチンがある場合、タイマーは取り消されます。 ただし、タイマーの状態は変更されません。 完了ルーチンがない場合、スレッドを終了してもタイマーには影響しません。
手動リセット タイマーがシグナル状態に設定されている場合、タイマーをリセットするために SetWaitableTimer が呼び出されるまで、この状態のままになります。 その結果、定期的な手動リセット タイマーは、最初の期限が到着したときにシグナル状態に設定され、リセットされるまで通知されたままになります。 同期タイマーがシグナル状態に設定されている場合、スレッドがタイマー オブジェクトの待機操作を完了するまで、同期タイマーはこの状態のままになります。
システム時間を調整すると、未処理の絶対タイマーの期限が調整されます。
この関数を使用するアプリケーションをコンパイルするには、 0x0400 以降として_WIN32_WINNTを定義します。 詳細については、「 Windows ヘッダーの使用」を参照してください。
タイマーを使用してウィンドウのイベントをスケジュールするには、 SetTimer 関数を使用します。
タイマーを扱う API では、さまざまなハードウェア クロックが使用されます。 これらのクロックの解像度は、予想とは大きく異なる場合があります。一部は、ナノ秒単位 (ACPI または TSC カウンターを使用する場合) に対してミリ秒単位 (RTC ベースのタイマー チップを使用する場合) で測定できます。 timeBeginPeriod 関数と timeEndPeriod 関数の呼び出しを使用して、API の解決を変更できます。 解像度をどの程度正確に変更できるかは、特定の API で使用されるハードウェア クロックによって異なります。 詳細については、ハードウェアのドキュメントをチェックしてください。
例
SetWaitableTimer を使用する例については、「待機可能タイマー オブジェクトの使用」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | synchapi.h (Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2 の Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |