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 つ以上を指定できます。

値 意味
WT_EXECUTEDEFAULT
0x00000000
 既定では、コールバック関数は I/O 以外のワーカー スレッドにキューに入れられます。
WT_EXECUTEINTIMERTHREAD
0x00000020
 コールバック関数は、タイマー スレッド自体によって呼び出されます。 このフラグは、短いタスクにのみ使用する必要があります。または、他のタイマー操作に影響を与える可能性があります。

コールバック関数は APC としてキューに登録されます。 アラート可能な待機操作は実行しないでください。
WT_EXECUTEINIOTHREAD
0x00000001
 このフラグは使用されません。

Windows Server 2003 および Windows XP: コールバック関数は、I/O ワーカー スレッドにキューに登録されます。 このフラグは、警告可能な状態で待機するスレッドで関数を実行する必要がある場合に使用する必要があります。

I/O ワーカー スレッドは、Windows Vista および Windows Server 2008 以降で削除されました。
WT_EXECUTEINPERSISTENTTHREAD
0x00000080
 コールバック関数は、終了しないスレッドにキューに入れられます。 毎回同じスレッドが使用されるとは限りません。 このフラグは、短いタスクにのみ使用する必要があります。または、他のタイマー操作に影響を与える可能性があります。

スレッドが APC を使用する関数を呼び出す場合は、このフラグを設定する必要があります。 詳細については、「 非同期プロシージャ呼び出し」を参照してください。

現在、ワーカー スレッドは本当に永続的ではありませんが、保留中の I/O 要求がある場合、ワーカー スレッドは終了しません。
WT_EXECUTELONGFUNCTION
0x00000010
 コールバック関数は、長い待機を実行できます。 このフラグは、システムが新しいスレッドを作成する必要があるかどうかを判断するのに役立ちます。
WT_EXECUTEONLYONCE
0x00000008
 タイマーは 1 回だけシグナル状態に設定されます。 このフラグが設定されている場合、 Period パラメーターは 0 である必要があります。
WT_TRANSFER_IMPERSONATION
0x00000100
 コールバック関数は、プロセスまたは偽装トークンのどちらであっても、現在のアクセス トークンを使用します。 このフラグが指定されていない場合、コールバック関数はプロセス トークンでのみ実行されます。

Windows XP: このフラグは、SP2 および Windows Server 2003 の Windows XP までサポートされていません。

戻り値

関数が成功すると、戻り値は 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 を使用する例については、「タイマー キューの使用」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー threadpoollegacyapiset.h
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

CreateTimerQueue

DeleteTimerQueueEx

DeleteTimerQueueTimer

同期関数

スレッド プール

タイマー キュー