CreateTimerQueueTimer 関数 (threadpoollegacyapiset.h)

タイマー キュー タイマーを作成します。 このタイマーは、指定した期限の後、指定した期間ごとに期限切れになります。 タイマーの有効期限が切れると、コールバック関数が呼び出されます。

構文

BOOL CreateTimerQueueTimer(
  [out]          PHANDLE             phNewTimer,
  [in, optional] HANDLE              TimerQueue,
  [in]           WAITORTIMERCALLBACK Callback,
  [in, optional] PVOID               Parameter,
  [in]           DWORD               DueTime,
  [in]           DWORD               Period,
  [in]           ULONG               Flags
);

パラメーター

[out] phNewTimer

戻り時にタイマー キュー タイマーへのハンドルを受け取るバッファーへのポインター。 このハンドルの有効期限が切れて不要になったら、 DeleteTimerQueueTimer を呼び出して解放します。

[in, optional] TimerQueue

タイマー キューへのハンドル。 このハンドルは、 CreateTimerQueue 関数によって返されます。

このパラメーターが NULL の場合、タイマーは既定のタイマー キューに関連付けられます。

[in] Callback

タイマーの有効期限が切れたときに実行される WAITORTIMERCALLBACK 型のアプリケーション定義関数へのポインター。 詳細については、「 WaitOrTimerCallback」を参照してください。

[in, optional] Parameter

コールバック関数に渡される 1 つのパラメーター値。

[in] DueTime

タイマーが初めて通知されるまでに経過する必要がある現在の時刻に対する時間 (ミリ秒単位)。

[in] Period

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

[in] Flags

このパラメーターには、WinNT.h の次の値の 1 つ以上を指定できます。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

DueTime パラメーターと Period パラメーターの両方が 0 以外の場合、タイマーは最初に期限に通知され、次に定期的に通知されます。 コールバックは、前のコールバックの実行が完了したかどうかにかかわらず、期間が経過するたびに呼び出されます。 コールバック関数はスレッド プールにキューに入れられます。 これらのスレッドはスケジュールの遅延の影響を受けるので、タイミングは、アプリケーションまたはシステムで発生している他の状況によって異なる場合があります。

システムがスリープまたは休止状態で過ごす時間は、タイマーの有効期限にカウントされません。 タイマーは、システムがウェイク状態で費やした累積経過時間が、タイマーの期限または期間と一致すると通知されます。

Windows Server 2003 および Windows XP: システムがスリープまたは休止状態で費やす時間は、タイマーの有効期限に向かってカウントされます。 システムのスリープ中にタイマーの有効期限が切れると、システムがスリープ解除されると、タイマーがすぐに通知されます。

タイマーを取り消すには、 DeleteTimerQueueTimer 関数を 呼び出します。 タイマー キュー内のすべてのタイマーを取り消すには、 DeleteTimerQueueEx 関数を呼び出します。

既定では、スレッド プールのスレッド数は最大 500 です。 この制限を引き上げるには、WinNT.h で定義 されているWT_SET_MAX_THREADPOOL_THREAD マクロを使用します。

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)<<16)

Flags パラメーターを指定する場合は、このマクロを使用します。 マクロ パラメーターは、目的のフラグと新しい制限 (最大 (2<<16)-1 スレッド) です。 ただし、アプリケーションでは、ワーカー スレッドの数を少なくすることで、パフォーマンスを向上させることができます。

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

例

CreateTimerQueueTimer を使用する例については、「タイマー キューの使用」を参照してください。

要件

関連項目

CreateTimerQueue

DeleteTimerQueueEx

DeleteTimerQueueTimer

同期関数

スレッド プール

タイマー キュー