Fungsi SetWaitableTimerEx (synchapi.h)

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

Sintaksis

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 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.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 dan Windows Server 2008 R2: Jika waktu relatif ditentukan, timer mencakup waktu yang dihabiskan dalam status berdaya rendah. Misalnya, timer terus menghitung mundur saat komputer sedang tidur.

Windows 8 dan yang lebih baru, Windows Server 2012 dan yang lebih baru: Jika waktu relatif ditentukan, timer tidak menyertakan waktu yang dihabiskan dalam status berdaya rendah. Misalnya, timer tidak melanjutkan penghitungan mundur saat komputer sedang tidur.

[in] lPeriod

Periode timer, dalam milidetik. Jika lPeriod nol, timer akan diberi sinyal 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 yang ditentukan aplikasi PTIMERAPCROUTINE untuk dijalankan ketika timer diberi sinyal. Untuk informasi selengkapnya tentang fungsi panggilan balik timer, lihat TimerAPCProc. Untuk informasi selengkapnya tentang APC dan utas kumpulan utas, lihat Komentar.

[in] lpArgToCompletionRoutine

Penunjuk ke struktur yang diteruskan ke rutinitas penyelesaian.

[in] WakeContext

Penunjuk ke struktur REASON_CONTEXT yang berisi informasi konteks untuk timer.

[in] TolerableDelay

Penundaan yang dapat ditoleransi untuk waktu kedaluwarsa, dalam milidetik.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

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

Komentar

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 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 belum diantrekan. Status timer diatur ke sinyal, timer diaktifkan kembali menggunakan periode yang ditentukan, dan utas yang mengatur timer memanggil rutinitas penyelesaian ketika 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 mungkin 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 hEventstruktur TUMPANG TINDIH 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 hingga diatur ulang. Ketika timer sinkronisasi diatur ke status yang disinyalir, timer tetap dalam status ini hingga utas menyelesaikan operasi tunggu pada objek timer.

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

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

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

Persyaratan

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

Lihat juga

REASON_CONTEXT

SetWaitableTimer