SetThreadpoolTimer 関数 (threadpoolapiset.h)

  • [アーティクル]

タイマー オブジェクトを設定し、前のタイマー (ある場合) を置き換えます。 ワーカー スレッドは、指定されたタイムアウトの有効期限が切れた後、タイマー オブジェクトのコールバックを呼び出します。

構文

void SetThreadpoolTimer(
  [in, out]      PTP_TIMER pti,
  [in, optional] PFILETIME pftDueTime,
  [in]           DWORD     msPeriod,
  [in]           DWORD     msWindowLength
);

パラメーター

[in, out] pti

設定するタイマー オブジェクトを定義する TP_TIMER 構造体へのポインター。 CreateThreadpoolTimer 関数は、このポインターを返します。

[in, optional] pftDueTime

タイマーの有効期限が切れる絶対時間または相対時間を指定する FILETIME 構造体へのポインター。 正またはゼロの場合は、1601 年 1 月 1 日 (UTC) 以降の絶対時間を 100 ナノ秒単位で示します。 負の場合は、現在の時刻を基準にして待機する時間を示します。 時刻の値の詳細については、「 ファイル時刻」を参照してください。

このパラメーターが NULL の場合、タイマー オブジェクトは新しいコールバックをキューに入れなくなります (ただし、既にキューに登録されているコールバックは引き続き発生します)。

pftDueTime パラメーターが NULL 以外の場合、タイマーが設定されます。

[in] msPeriod

タイマー期間 (ミリ秒単位)。 このパラメーターが 0 の場合、タイマーは 1 回通知されます。 このパラメーターが 0 より大きい場合、タイマーは定期的です。 定期的なタイマーは、タイマーが取り消されるまで、期間が経過するたびに自動的に再アクティブ化されます。

[in] msWindowLength

タイマー コールバックを呼び出す前にシステムが遅延できる最大時間。 このパラメーターが 0 に設定されていない場合、システムは呼び出しをバッチ処理して電力を節約できます。

戻り値

なし

解説

タイマーを設定すると、前のタイマー (ある場合) が取り消されます。

場合によっては、アプリケーションがスレッド プール タイマーを閉じると、コールバック関数が実行されることがあります。 この動作を防ぐために、アプリケーションは CloseThreadpoolTimer で説明されている手順に従う必要があります。

pftDueTime で指定された期限が相対的な場合、システムがスリープまたは休止状態で費やす時間は、タイマーの有効期限にカウントされません。 タイマーは、システムがウェイク状態で費やした累積経過時間が、タイマーの相対的な期限または期間と等しい場合に通知されます。 pftDueTime で指定された期限が絶対である場合、システムがスリープまたは休止状態で費やす時間は、タイマーの有効期限にカウントされます。 システムのスリープ中にタイマーの有効期限が切れると、システムがスリープ解除されると、タイマーがすぐに通知されます。

pftDueTime で指定された期限が 0 の場合、タイマーはすぐに期限切れになります。

この関数を使用するアプリケーションをコンパイルするには、_WIN32_WINNTを 0x0600 以上として定義します。

例

例については、「 スレッド プール関数の使用」を参照してください。

要件

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

関連項目

CloseThreadpoolTimer

CreateThreadpoolTimer

IsThreadpoolTimerSet

スレッド プール

WaitForThreadpoolTimerCallbacks