SetCoalescableTimer 関数 (winuser.h)
指定されたタイムアウト値と合体許容遅延を持つタイマーを作成します。
構文
UINT_PTR SetCoalescableTimer(
[in, optional] HWND hWnd,
[in] UINT_PTR nIDEvent,
[in] UINT uElapse,
[in, optional] TIMERPROC lpTimerFunc,
[in] ULONG uToleranceDelay
);
パラメーター
[in, optional] hWnd
型: HWND
タイマーに関連付けるウィンドウへのハンドル。 このウィンドウは、呼び出し元のスレッドによって所有されている必要があります。 既存のタイマーの nIDEvent と共に hWnd の NULL 値が渡された場合、そのタイマーは、既存の NULL 以外の hWnd タイマーと同じ方法で置き換えられます。
[in] nIDEvent
種類: UINT_PTR
タイマー識別子。 hWnd パラメーターが NULL で、nIDEvent が既存のタイマーと一致しない場合、nIDEvent は無視され、新しいタイマー ID が生成されます。 hWnd パラメーターが NULL ではなく、hWnd で指定されたウィンドウに nIDEvent 値を持つタイマーが既に存在する場合、既存のタイマーは新しいタイマーに置き換えられます。 SetCoalescableTimer がタイマーを置き換えると、タイマーはリセットされます。 したがって、現在のタイムアウト値が経過するとメッセージが送信されますが、以前に設定されたタイムアウト値は無視されます。 呼び出しが既存のタイマーを置き換えることを意図していない場合、hWnd が NULL の場合、nIDEvent は 0 にする必要があります。
[in] uElapse
型: UINT
タイムアウト値 (ミリ秒)。
uElapse がUSER_TIMER_MINIMUM未満 (0x0000000A) の場合、タイムアウトは USER_TIMER_MINIMUM に設定されます。 uElapse が USER_TIMER_MAXIMUM (0x7FFFFFFF) より大きい場合、タイムアウトは USER_TIMER_MAXIMUM に設定されます。
uElapse と uToleranceDelay の合計がUSER_TIMER_MAXIMUMを超えると、ERROR_INVALID_PARAMETER例外が発生します。
[in, optional] lpTimerFunc
種類: TIMERPROC
タイムアウト値が経過したときに通知される関数へのポインター。 関数の詳細については、「 TimerProc」を参照してください。 lpTimerFunc が NULL の場合、システムはアプリケーション キューにWM_TIMERメッセージをポストします。 メッセージの MSG 構造体の hwnd メンバーには、hWnd パラメーターの値が含まれています。
[in] uToleranceDelay
種類: ULONG
次のいずれかの値を指定できます。
| 値 | 説明 |
|---|---|
|
システムの既定のタイマー合体を使用します。 |
|
タイマー合体を使用しません。 この値を使用すると、システムの既定のタイマー合体やアプリケーション互換性フラグに関係なく、作成されたタイマーは結合されません。
メモ タイマーに合体が不要であると確信できる場合を除き、この値を使用しないでください。
|
|
結合許容遅延をミリ秒単位で指定します。
アプリケーションでは、この値をシステムの既定値 (TIMERV_DEFAULT_COALESCING) または可能な最大値に設定する必要があります。 uElapse と uToleranceDelay の合計が USER_TIMER_MAXIMUM (0x7FFFFFFF) を超えると、ERROR_INVALID_PARAMETER例外が発生します。 詳細とベスト プラクティスについては、「 Windows タイマー結合 」を参照してください。 |
|
無効な値。 uToleranceDelay が無効な値に設定されている場合、関数は失敗し、0 を返します。 |
戻り値
種類: UINT_PTR
関数が成功し、 hWnd パラメーターが NULL の場合、戻り値は新しいタイマーを識別する整数です。 アプリケーションは、この値を KillTimer 関数に渡してタイマーを破棄できます。
関数が成功し、 hWnd パラメーターが NULL でない場合、戻り値は 0 以外の整数になります。 アプリケーションは、タイマーを破棄するために 、nIDEvent パラメーターの値を KillTimer 関数に渡すことができます。
関数がタイマーの作成に失敗した場合、戻り値は 0 です。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
アプリケーションは、ウィンドウ プロシージャに WM_TIMER case ステートメントを含めるか、タイマーの作成時に TimerProc コールバック関数を指定することで、WM_TIMERメッセージを処理できます。 TimerProc コールバック関数を指定すると、既定のウィンドウ プロシージャは、WM_TIMERを処理するときにコールバック関数を呼び出します。 したがって、WM_TIMERを処理する代わりに TimerProc を使用する場合でも、呼び出し元のスレッドでメッセージ をディスパッチする必要があります。
WM_TIMER メッセージの wParam パラメーターには、nIDEvent パラメーターの値が含まれています。
タイマー識別子 nIDEvent は、関連付けられているウィンドウに固有です。 別のウィンドウには、別のウィンドウが所有するタイマーと同じ識別子を持つ独自のタイマーを使用できます。 タイマーは異なります。
SetTimer では、 hWnd が NULL の場合にタイマー ID を再利用できます。
uToleranceDelay が 0 に設定されている場合、システムの既定のタイマー合体が使用され、SetCoalescableTimer は SetTimer と同じように動作します。
SetCoalescableTimer またはその他のタイマー関連関数を使用する前に、SetUserObjectInformationW 関数を使用してUOI_TIMERPROC_EXCEPTION_SUPPRESSION フラグを false に設定することをお勧めします。そうしないと、アプリケーションが予期しない動作をし、セキュリティ上の悪用に対して脆弱になる可能性があります。 詳細については、「 SetUserObjectInformationW」を参照してください。
要件
| サポートされている最小のクライアント | Windows 8 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2012 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winuser.h (Windows.h を含む) |
| Library | User32.lib |
| [DLL] | User32.dll |
| API セット | ext-ms-win-ntuser-window-l1-1-2 (Windows 10 バージョン 10.0.10240 で導入) |
関連項目
概念
リファレンス
サンプル
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示