SetWaitableTimer 関数 (synchapi.h)

[アーティクル]
11/18/2024

指定された待機可能タイマーをアクティブにします。期限が到着すると、タイマーが通知され、タイマーを設定したスレッドが省略可能な完了ルーチンを呼び出します。

構文

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 ベースの時刻の詳細については、「システム時刻をする」を参照してください。

Windows XP、Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008、Windows Server 2008 R2: 相対時間が指定されている場合、タイマーには低電力状態で費やされた時間が含まれます。たとえば、タイマーは、コンピューターがスリープ状態の間もカウントダウンを続けます。

Windows 8 以降、Windows Server 2012 以降: 相対時間が指定されている場合、タイマーには低電力状態で費やされた時間は含まれません。たとえば、タイマーは、コンピューターがスリープ状態の間、カウントダウンを続行しません。

[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 関数に渡すことができる、OVERLAPPED 構造体に基づく hEventを使用します。

タイマーを設定したスレッドが終了し、関連する完了ルーチンがある場合、タイマーは取り消されます。ただし、タイマーの状態は変更されません。完了ルーチンがない場合、スレッドを終了してもタイマーには影響しません。

手動リセットタイマーがシグナル状態に設定されている場合、タイマーをリセットするために SetWaitableTimer 呼び出されるまで、この状態のままになります。その結果、定期的な手動リセットタイマーは、最初の期限が到着したときに通知された状態に設定され、リセットされるまで通知されたままになります。同期タイマーがシグナル状態に設定されると、スレッドがタイマーオブジェクトの待機操作を完了するまで、この状態のままになります。

システム時間を調整すると、未処理の絶対タイマーの期限が調整されます。

この関数を使用するアプリケーションをコンパイルするには、_WIN32_WINNT を 0x0400 以降として定義します。詳細については、「Windows ヘッダーの使用」を参照してください。

タイマーを使用してウィンドウのイベントをスケジュールするには、SetTimer 関数を使用します。

タイマーを処理する API では、さまざまなハードウェアクロックが使用されます。これらのクロックの解像度は、予想と大きく異なる場合があります。一部の解像度は、ナノ秒単位 (ACPI または TSC カウンターを使用する場合) にミリ秒単位で測定できます (RTC ベースのタイマーチップを使用する場合)。 timeBeginPeriod を呼び出し、timeEndPeriod 関数をすることで、API の解決を変更できます。解像度をどの程度正確に変更できるかは、特定の API で使用されるハードウェアクロックによって異なります。詳細については、ハードウェアのドキュメントを参照してください。

例

SetWaitableTimer使用する例については、「待機可能タイマーオブジェクトを使用する」を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows XP [デスクトップアプリ \|UWP アプリ]
サポートされる最小サーバー	Windows Server 2003 [デスクトップアプリ \|UWP アプリ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	synchapi.h (Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2 の Windows.h を含む)
ライブラリ	Kernel32.lib
DLL	Kernel32.dll

次の方法で共有

SetWaitableTimer 関数 (synchapi.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース