Fungsi SetCoalescableTimer (winuser.h)

Artikel
08/28/2023

Membuat timer dengan nilai batas waktu yang ditentukan dan menyatukan penundaan toleransi.

Sintaks

UINT_PTR SetCoalescableTimer(
  [in, optional] HWND      hWnd,
  [in]           UINT_PTR  nIDEvent,
  [in]           UINT      uElapse,
  [in, optional] TIMERPROC lpTimerFunc,
  [in]           ULONG     uToleranceDelay
);

Parameter

[in, optional] hWnd

Jenis: HWND

Handel ke jendela yang akan dikaitkan dengan timer. Jendela ini harus dimiliki oleh utas panggilan. Jika nilai NULL untuk hWnd diteruskan bersama dengan nIDEvent dari timer yang ada, timer tersebut akan diganti dengan cara yang sama seperti timer hWnd non-NULL yang ada.

[in] nIDEvent

Jenis: UINT_PTR

Pengidentifikasi timer. Jika parameter hWnd adalah NULL, dan nIDEvent tidak cocok dengan timer yang ada, maka nIDEvent diabaikan dan ID timer baru dihasilkan. Jika parameter hWnd bukan NULL dan jendela yang ditentukan oleh hWnd sudah memiliki timer dengan nilai nIDEvent, maka timer yang ada digantikan oleh timer baru. Saat SetCoalescableTimer menggantikan timer, timer diatur ulang. Oleh karena itu, pesan akan dikirim setelah nilai batas waktu saat ini berlalu, tetapi nilai batas waktu yang ditetapkan sebelumnya diabaikan. Jika panggilan tidak dimaksudkan untuk mengganti timer yang ada, nIDEvent harus 0 jika hWnd adalah NULL.

[in] uElapse

Jenis: UINT

Nilai waktu habis, dalam milidetik.

Jika uElapse kurang dari USER_TIMER_MINIMUM (0x0000000A), batas waktu diatur ke USER_TIMER_MINIMUM. Jika uElapse lebih besar dari USER_TIMER_MAXIMUM (0x7FFFFFFF), batas waktu diatur ke USER_TIMER_MAXIMUM.

Jika jumlah uElapse dan uToleranceDelay melebihi USER_TIMER_MAXIMUM, pengecualian ERROR_INVALID_PARAMETER terjadi.

[in, optional] lpTimerFunc

Jenis: TIMERPROC

Penunjuk ke fungsi yang akan diberi tahu saat nilai waktu habis berlalu. Untuk informasi selengkapnya tentang fungsi ini, lihat TimerProc. Jika lpTimerFunc adalah NULL, sistem memposting pesan WM_TIMER ke antrean aplikasi. Anggota hwnd dari struktur MSG pesan berisi nilai parameter hWnd .

[in] uToleranceDelay

Jenis: ULONG

Jenis dapat berupa salah satu dari nilai berikut:

Nilai	Makna
TIMERV_DEFAULT_COALESCING 0x00000000	Menggunakan sistem default timer coalescing.
TIMERV_NO_COALESCING 0xFFFFFFFF	Tidak menggunakan timer coalescing. Ketika nilai ini digunakan, timer yang dibuat tidak digabungkan, apa pun yang digunakan oleh timer default sistem atau bendera kompatibilitas aplikasi. Catatan Jangan gunakan nilai ini kecuali Anda yakin bahwa timer tidak memerlukan coalescing.
0x1 - 0x7FFFFFF5	Menentukan penundaan toleransi coalescing, dalam milidetik. Aplikasi harus mengatur nilai ini ke default sistem (TIMERV_DEFAULT_COALESCING) atau nilai terbesar yang mungkin. Jika jumlah uElapse dan uToleranceDelay melebihi USER_TIMER_MAXIMUM (0x7FFFFFFF), pengecualian ERROR_INVALID_PARAMETER terjadi. Lihat Windows Timer Coalescing untuk detail selengkapnya dan praktik terbaik.
Nilai lainnya	Nilai yang tidak valid. Jika uToleranceDelay diatur ke nilai yang tidak valid, fungsi gagal dan mengembalikan nol.

Mengembalikan nilai

Jenis: UINT_PTR

Jika fungsi berhasil dan parameter hWnd adalah NULL, nilai yang dikembalikan adalah bilangan bulat yang mengidentifikasi timer baru. Aplikasi dapat meneruskan nilai ini ke fungsi KillTimer untuk menghancurkan timer.

Jika fungsi berhasil dan parameter hWnd bukan NULL, maka nilai yang dikembalikan adalah bilangan bulat bukan nol. Aplikasi dapat meneruskan nilai parameter nIDEvent ke fungsi KillTimer untuk menghancurkan timer.

Jika fungsi gagal membuat timer, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Aplikasi dapat memproses WM_TIMER pesan dengan menyertakan pernyataan kasus WM_TIMER dalam prosedur jendela atau dengan menentukan fungsi panggilan balik TimerProc saat membuat timer. Saat Anda menentukan fungsi panggilan balik TimerProc , prosedur jendela default memanggil fungsi panggilan balik saat memproses WM_TIMER. Oleh karena itu, Anda perlu mengirimkan pesan di utas panggilan, bahkan ketika Anda menggunakan TimerProc alih-alih memproses WM_TIMER.

Parameter wParam dari pesan WM_TIMER berisi nilai parameter nIDEvent .

Pengidentifikasi timer, nIDEvent, khusus untuk jendela terkait. Jendela lain dapat memiliki timer sendiri yang memiliki pengidentifikasi yang sama dengan timer yang dimiliki oleh jendela lain. Timernya berbeda.

SetTimer dapat menggunakan kembali ID timer dalam kasus di mana hWnd adalah NULL.

Ketika uToleranceDelay diatur ke 0, coalescing timer default sistem digunakan dan SetCoalescableTimer berperilaku sama dengan SetTimer.

Sebelum menggunakan SetCoalescableTimer atau fungsi terkait timer lainnya, disarankan untuk mengatur bendera UOI_TIMERPROC_EXCEPTION_SUPPRESSION ke false melalui fungsi SetUserObjectInformationW , jika tidak, aplikasi dapat berperilaku tidak terduga dan dapat rentan terhadap eksploitasi keamanan. Untuk informasi selengkapnya, lihat SetUserObjectInformationW.

Persyaratan


Klien minimum yang didukung	Windows 8 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2012 [hanya aplikasi desktop]
Target Platform	Windows
Header	winuser.h (sertakan Windows.h)
Pustaka	User32.lib
DLL	User32.dll
Set API	ext-ms-win-ntuser-window-l1-1-2 (diperkenalkan dalam Windows 10, versi 10.0.10240)