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 を使用する例については、「待機可能タイマー オブジェクトの使用」を参照してください。

要件

関連項目

CancelWaitableTimer

CreateWaitableTimer

OpenWaitableTimer

同期関数

TimerAPCProc

待機可能タイマー オブジェクト