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

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

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

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

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

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

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

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

要件

   
サポートされている最小のクライアント Windows 7 [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー Windows Server 2008 R2 [デスクトップ アプリ |UWP アプリ]
対象プラットフォーム Windows
ヘッダー synchapi.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

REASON_CONTEXT

SetWaitableTimer