SetCoalescableTimer 関数 (winuser.h)

[アーティクル]
08/28/2023

指定されたタイムアウト値と合体許容遅延を持つタイマーを作成します。

構文

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 0x00000000	システムの既定のタイマー合体を使用します。
TIMERV_NO_COALESCING 0xFFFFFFFF	タイマー合体を使用しません。この値を使用すると、システムの既定のタイマー合体やアプリケーション互換性フラグに関係なく、作成されたタイマーは結合されません。メモタイマーに合体が不要であると確信できる場合を除き、この値を使用しないでください。
0x1 - 0x7FFFFFF5	結合許容遅延をミリ秒単位で指定します。アプリケーションでは、この値をシステムの既定値 (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 で導入)

次の方法で共有

SetCoalescableTimer 関数 (winuser.h)

構文

パラメーター

戻り値

解説

要件

関連項目

フィードバック

その他のリソース