Fungsi SetWaitableTimer (synchapi.h)
Mengaktifkan timer yang dapat ditunggu yang ditentukan. Ketika waktu jatuh tempo tiba, timer diberi sinyal dan utas yang mengatur timer memanggil rutinitas penyelesaian opsional.
Sintaks
BOOL SetWaitableTimer(
[in] HANDLE hTimer,
[in] const LARGE_INTEGER *lpDueTime,
[in] LONG lPeriod,
[in, optional] PTIMERAPCROUTINE pfnCompletionRoutine,
[in, optional] LPVOID lpArgToCompletionRoutine,
[in] BOOL fResume
);
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 status timer 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 disinyalkan 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 SetWaitableTimer. Jika lPeriod kurang dari nol, fungsi gagal.
[in, optional] pfnCompletionRoutine
Penunjuk ke rutinitas penyelesaian opsional. Rutinitas penyelesaian adalah fungsi jenis PTIMERAPCROUTINE yang ditentukan aplikasi yang akan dijalankan saat timer diberi sinyal. Untuk informasi selengkapnya tentang fungsi panggilan balik timer, lihat TimerAPCProc. Untuk informasi selengkapnya tentang APC dan utas kumpulan utas, lihat Keterangan.
[in, optional] lpArgToCompletionRoutine
Penunjuk ke struktur yang diteruskan ke rutinitas penyelesaian.
[in] fResume
Jika parameter ini TRUE, memulihkan sistem dalam mode konservasi daya yang ditangguhkan saat status timer diatur ke sinyal. Jika tidak, sistem tidak dipulihkan. Jika sistem tidak mendukung pemulihan, panggilan berhasil, tetapi GetLastError mengembalikan ERROR_NOT_SUPPORTED.
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
Timer awalnya tidak aktif. Untuk mengaktifkan timer, panggil SetWaitableTimer. Jika timer sudah aktif saat Anda memanggil SetWaitableTimer, timer dihentikan, maka timer diaktifkan kembali. 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 diingat. 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 bagi utas untuk 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 tempat 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 pengaturan ulang manual diatur ke status sinyal, timer tetap dalam status ini hingga SetWaitableTimer dipanggil untuk mengatur ulang timer. Akibatnya, timer pengaturan ulang manual berkala diatur ke status yang disinyalkan ketika waktu jatuh tempo awal tiba dan tetap diberi sinyal sampai diatur ulang. Ketika timer sinkronisasi diatur ke status yang disinyalir, 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.
Untuk mengkompilasi aplikasi yang menggunakan fungsi ini, tentukan _WIN32_WINNT sebagai 0x0400 atau yang lebih baru. Untuk informasi selengkapnya, lihat Menggunakan Header Windows.
Untuk menggunakan timer guna menjadwalkan peristiwa untuk jendela, gunakan fungsi SetTimer .
API yang menangani timer menggunakan berbagai jam perangkat keras yang berbeda. Jam ini mungkin memiliki resolusi yang sangat berbeda dari yang Anda harapkan: beberapa mungkin diukur dalam milidetik (bagi mereka yang menggunakan chip timer berbasis RTC), dengan yang diukur dalam nanodetik (untuk yang menggunakan penghitung ACPI atau TSC). Anda dapat mengubah resolusi API Anda dengan panggilan ke fungsi timeBeginPeriod dan timeEndPeriod . Seberapa tepat Anda dapat mengubah resolusi tergantung pada jam perangkat keras mana yang digunakan API tertentu. Untuk informasi selengkapnya, periksa dokumentasi perangkat keras Anda.
Contoh
Untuk contoh yang menggunakan SetWaitableTimer, lihat Menggunakan Objek Timer yang Dapat Ditunggu.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows XP [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2003 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | synchapi.h (termasuk Windows.h pada Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Pustaka | Kernel32.lib |
| DLL | Kernel32.dll |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk