Fungsi SetWaitableTimerEx (synchapi.h)

  • Artikel

Mengaktifkan timer yang dapat ditunggu yang ditentukan dan memberikan informasi konteks untuk timer. Ketika waktu jatuh tempo tiba, timer diberi sinyal dan utas yang mengatur timer memanggil rutinitas penyelesaian opsional.

Sintaks

BOOL SetWaitableTimerEx(
  [in] HANDLE              hTimer,
  [in] const LARGE_INTEGER *lpDueTime,
  [in] LONG                lPeriod,
  [in] PTIMERAPCROUTINE    pfnCompletionRoutine,
  [in] LPVOID              lpArgToCompletionRoutine,
  [in] PREASON_CONTEXT     WakeContext,
  [in] ULONG               TolerableDelay
);

Parameter

[in] hTimer

Handel ke objek timer. Fungsi CreateWaitableTimer atau OpenWaitableTimer mengembalikan handel ini.

Handel harus memiliki hak akses TIMER_MODIFY_STATE . Untuk informasi selengkapnya, lihat Keamanan Objek Sinkronisasi dan Hak Akses.

[in] lpDueTime

Waktu setelah itu status timer akan diatur ke sinyal, dalam 100 interval nanodetik. Gunakan format yang dijelaskan oleh struktur FILETIME . Nilai positif menunjukkan waktu absolut. Pastikan untuk menggunakan waktu absolut berbasis UTC, karena sistem menggunakan waktu berbasis UTC secara internal. Nilai negatif menunjukkan waktu relatif. Akurasi timer aktual tergantung pada kemampuan perangkat keras Anda. Untuk informasi selengkapnya tentang waktu berbasis UTC, lihat Waktu Sistem.

[in] lPeriod

Periode timer, dalam milidetik. Jika lPeriod adalah nol, timer disinyalir sekali. Jika lPeriod lebih besar dari nol, timer berkala. Timer berkala secara otomatis mengaktifkan kembali setiap kali periode berlalu, hingga timer dibatalkan menggunakan fungsi CancelWaitableTimer atau reset menggunakan SetWaitableTimerEx. Jika lPeriod kurang dari nol, fungsi gagal.

[in] pfnCompletionRoutine

Penunjuk ke rutinitas penyelesaian opsional. Rutinitas penyelesaian adalah fungsi jenis PTIMERAPCROUTINE yang ditentukan aplikasi untuk dijalankan ketika timer disinyalir. Untuk informasi selengkapnya tentang fungsi panggilan balik timer, lihat TimerAPCProc. Untuk informasi selengkapnya tentang APC dan utas kumpulan utas, lihat Keterangan.

[in] lpArgToCompletionRoutine

Pointer ke struktur yang diteruskan ke rutinitas penyelesaian.

[in] WakeContext

Arahkan ke struktur REASON_CONTEXT yang berisi informasi konteks untuk timer.

[in] TolerableDelay

Penundaan yang dapat ditoleransi untuk waktu kedaluwarsa, dalam milidetik.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

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

Keterangan

Fungsi SetWaitableTimerEx mirip dengan fungsi SetWaitableTimer , kecuali SetWaitableTimerEx dapat digunakan untuk menentukan string konteks dan penundaan yang dapat ditoleransi untuk kedaluwarsa timer.

Untuk mengkompilasi aplikasi yang menggunakan fungsi ini, tentukan _WIN32_WINNT sebagai 0x0601 atau yang lebih baru. Untuk informasi selengkapnya, lihat Menggunakan Header Windows.

Timer awalnya tidak aktif. Untuk mengaktifkan timer, panggil SetWaitableTimerEx. Jika timer sudah aktif saat Anda memanggil SetWaitableTimerEx, timer dihentikan, maka pengaktifan ulang. Menghentikan timer dengan cara ini tidak mengatur status timer ke sinyal, sehingga utas yang diblokir dalam operasi tunggu pada timer tetap diblokir. Namun, itu membatalkan rutinitas penyelesaian yang tertunda.

Ketika waktu jatuh tempo yang ditentukan tiba, timer menjadi tidak aktif, dan APC opsional diantrekan ke utas yang mengatur timer jika tidak ada APC yang luar biasa yang sudah diantrekan. Status timer diatur ke disinyalkan, timer diaktifkan kembali menggunakan periode yang ditentukan, dan utas yang mengatur timer memanggil rutinitas penyelesaian saat memasuki status tunggu yang dapat diperingatkan. Untuk informasi selengkapnya, lihat QueueUserAPC. Perhatikan bahwa APC tidak berfungsi serta mekanisme sinyal lainnya untuk utas kumpulan utas karena sistem mengontrol masa pakai utas kumpulan utas, sehingga dimungkinkan untuk utas dihentikan sebelum pemberitahuan dikirimkan. Alih-alih menggunakan parameter pfnCompletionRoutine atau mekanisme sinyal berbasis APC lainnya, gunakan objek yang dapat ditunggu seperti timer yang dibuat dengan CreateThreadpoolTimer. Untuk I/O, gunakan objek penyelesaian I/O yang dibuat dengan CreateThreadpoolIo atau struktur TUMPANG TINDIH berbasis hEvent di mana peristiwa dapat diteruskan ke fungsi SetThreadpoolWait.

Jika utas yang mengatur timer berakhir dan ada rutinitas penyelesaian terkait, timer dibatalkan. Namun, keadaan timer tetap tidak berubah. Jika tidak ada rutinitas penyelesaian, maka mengakhiri utas tidak berpengaruh pada timer.

Ketika timer reset manual diatur ke status yang disinyalir, timer tetap dalam status ini hingga SetWaitableTimerEx dipanggil untuk mengatur ulang timer. Akibatnya, timer reset manual berkala diatur ke status yang disinyalir ketika waktu jatuh tempo awal tiba dan tetap diberi sinyal sampai diatur ulang. Ketika timer sinkronisasi diatur ke status bersinyali, timer tetap dalam status ini sampai utas menyelesaikan operasi tunggu pada objek timer.

Jika waktu sistem disesuaikan, waktu jatuh tempo timer absolut yang luar biasa akan disesuaikan.

Jika utas yang disebut SetWaitableTimerEx keluar, timer dibatalkan. Ini menghentikan timer sebelum dapat diatur ke status sinyal dan membatalkan APC yang beredar; ini tidak mengubah status timer yang disinyalir.

Untuk menggunakan timer guna menjadwalkan peristiwa untuk jendela, gunakan fungsi SetTimer .

Persyaratan

   
Klien minimum yang didukung Windows 7 [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung Windows Server 2008 R2 [aplikasi desktop | Aplikasi UWP]
Target Platform Windows
Header synchapi.h (termasuk Windows.h)
Pustaka Kernel32.lib
DLL Kernel32.dll

Lihat juga

REASON_CONTEXT

SetWaitableTimer