次の方法で共有

SetWaitableTimerEx 関数 (synchapi.h)

  • [アーティクル]

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

構文

BOOL SetWaitableTimerEx(
  [in] HANDLE              hTimer,
  [in] const LARGE_INTEGER *lpDueTime,
  [in] LONG                lPeriod,
  [in] PTIMERAPCROUTINE    pfnCompletionRoutine,
  [in] LPVOID              lpArgToCompletionRoutine,
  [in] PREASON_CONTEXT     WakeContext,
  [in] ULONG               TolerableDelay
);

パラメーター

[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 関数を使用してタイマーが取り消されるか、SetWaitableTimerExを使用してリセットされるまで、期間が経過するたびに自動的に再アクティブ化 。 lPeriod が 0 未満の場合、関数は失敗します。

[in] pfnCompletionRoutine

省略可能な完了ルーチンへのポインター。 完了ルーチンは、タイマーが通知されたときに実行される PTIMERAPCROUTINE 型のアプリケーション定義関数です。 タイマー コールバック関数の詳細については、「TimerAPCProcを参照してください。 APC とスレッド プール スレッドの詳細については、「解説」を参照してください。

[in] lpArgToCompletionRoutine

完了ルーチンに渡される構造体へのポインター。

[in] WakeContext

タイマーのコンテキスト情報を含む REASON_CONTEXT 構造体へのポインター。

[in] TolerableDelay

有効期限の許容される遅延 (ミリ秒単位)。

戻り値

関数が成功した場合、戻り値は 0 以外です。

関数が失敗した場合、戻り値は 0 です。 拡張エラー情報を取得するには、GetLastError呼び出します。

備考

SetWaitableTimerEx 関数は、setWaitableTimer 関数 に似ていますが、SetWaitableTimerEx 使用して、コンテキスト文字列とタイマーの有効期限の許容可能な遅延を指定できます。

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

タイマーは最初は非アクティブです。 タイマーをアクティブにするには、SetWaitableTimerEx呼び出します。 SetWaitableTimerEx呼び出したときにタイマーが既にアクティブになっている場合、タイマーは停止され、再アクティブ化されます。 この方法でタイマーを停止してもタイマー状態はシグナル状態に設定されないため、タイマーの待機操作でブロックされたスレッドはブロックされたままです。 ただし、保留中の完了ルーチンはすべて取り消されます。

指定された期限が到着すると、タイマーは非アクティブになり、未処理の APC が既にキューに登録されていない場合は、タイマーを設定するスレッドにオプションの APC がキューに入れられます。 タイマーの状態はシグナル状態に設定され、タイマーは指定された期間を使用して再アクティブ化され、タイマーを設定したスレッドは警告可能な待機状態になると完了ルーチンを呼び出します。 詳細については、QueueUserAPCを参照してください。 システムがスレッド プール スレッドの有効期間を制御するため、通知が配信される前にスレッドが終了する可能性があるため、APC はスレッド プール スレッドの他のシグナリング メカニズムと同様に機能しないことに注意してください。 pfnCompletionRoutine パラメーターまたは別の APC ベースのシグナリング メカニズムを使用する代わりに、CreateThreadpoolTimerで作成されたタイマーなどの待機可能なオブジェクトを使用します。 I/O の場合は、CreateThreadpoolIo 使用して作成された I/O 完了オブジェクト、またはイベントを SetThreadpoolWait 関数に渡すことができる、OVERLAPPED 構造体に基づく hEventを使用します。

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

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

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

SetWaitableTimerEx 呼び出したスレッドが終了すると、タイマーは取り消されます。 これにより、タイマーがシグナル状態に設定される前にタイマーが停止し、未処理の APCs が取り消されます。タイマーのシグナル状態は変更されません。

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

必要条件

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

関連項目

REASON_CONTEXT

SetWaitableTimer の