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

関連項目

CloseThreadpoolTimer

CreateThreadpoolTimer

IsThreadpoolTimerSet

スレッド プール

WaitForThreadpoolTimerCallbacks