SetThreadpoolTimerEx 関数 (threadpoolapiset.h)
タイマー オブジェクトを設定し、前のタイマー (ある場合) を置き換えます。 ワーカー スレッドは、指定されたタイムアウトの有効期限が切れた後、タイマー オブジェクトのコールバックを呼び出します。
構文
BOOL SetThreadpoolTimerEx(
[in, out] PTP_TIMER pti,
[in, optional] PFILETIME pftDueTime,
[in] DWORD msPeriod,
[in, optional] DWORD msWindowLength
);
パラメーター
[in, out] pti
設定するタイマー オブジェクトを定義する TP_TIMER 構造体へのポインター。 CreateThreadpoolTimer 関数は、このポインターを返します。
[in, optional] pftDueTime
タイマーの有効期限が切れる絶対時間または相対時間を指定する FILETIME 構造体へのポインター。 このパラメーターが正の値を指している場合は、1601 年 1 月 1 日 (UTC) 以降の絶対時間を 100 ナノ秒単位で示します。 このパラメーターが負の値を指している場合は、現在の時刻に対する待機時間を示します。 このパラメーターが 0 を指している場合、タイマーはすぐに期限切れになります。 時刻の値の詳細については、「 ファイル時刻」を参照してください。
このパラメーターが NULL の場合、タイマー オブジェクトは新しいコールバックのキューに入れなくなります (ただし、既にキューに登録されているコールバックは引き続き発生します)。
pftDueTime パラメーターが NULL 以外の場合、タイマーが設定されます。
[in] msPeriod
タイマー期間 (ミリ秒単位)。 このパラメーターが 0 の場合、タイマーは 1 回通知されます。 このパラメーターが 0 より大きい場合、タイマーは定期的です。 定期的なタイマーは、タイマーが取り消されるまで、期間が経過するたびに自動的に再アクティブ化されます。
[in, optional] msWindowLength
タイマー コールバックを呼び出す前にシステムが遅延できる最大時間。 このパラメーターが設定されている場合、システムは呼び出しをバッチ処理して電力を節約できます。
戻り値
タイマーが以前に設定され、取り消された場合は TRUE を返します。 それ以外の場合は、FALSE を返します。
タイマーの以前の状態が "set" で、関数が FALSE を返す場合、コールバックが進行中であるか、もう少しで開始されます。 詳細については、解説を参照してください。
注釈
タイマーを設定すると、前のタイマーが取り消されます (ある場合)。
場合によっては、アプリケーションがスレッドプール タイマーを閉じると、コールバック関数が実行されることがあります。 この動作を防ぐために、アプリケーションは CloseThreadpoolTimer で説明されている手順に従う必要があります。
pftDueTime で指定された期限が相対的な場合、システムがスリープまたは休止状態に費やす時間は、タイマーの有効期限にカウントされません。 タイマーは、システムがウェイク状態で費やした経過時間の累積量が、タイマーの相対的な期限または期間と等しい場合に通知されます。 pftDueTime で指定された期限が絶対である場合、システムがスリープまたは休止状態に費やす時間は、タイマーの有効期限にカウントされます。 システムのスリープ中にタイマーの有効期限が切れると、システムがスリープ解除されるとすぐにタイマーが通知されます。
この関数を使用するアプリケーションをコンパイルするには、_WIN32_WINNTを 0x0600 以上として定義します。
例
例については、「 スレッド プール関数の使用」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8 [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2012 [デスクトップ アプリ |UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | threadpoolapiset.h |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |