Fungsi MsgWaitForMultipleObjectsEx (winuser.h)
Menunggu hingga satu atau semua objek yang ditentukan dalam status sinyal, panggilan prosedur rutin atau asinkron (APC) penyelesaian I/O diantrekan ke utas, atau interval waktu habis berlalu. Array objek dapat mencakup objek peristiwa input, yang Anda tentukan menggunakan parameter dwWakeMask
Sintaksis
DWORD MsgWaitForMultipleObjectsEx(
[in] DWORD nCount,
[in] const HANDLE *pHandles,
[in] DWORD dwMilliseconds,
[in] DWORD dwWakeMask,
[in] DWORD dwFlags
);
Parameter
[in] nCount
Jumlah handel objek dalam array yang ditujukkan oleh pHandles. Jumlah maksimum handel objek MAXIMUM_WAIT_OBJECTS dikurangi satu. Jika parameter ini memiliki nilai nol, maka fungsi hanya menunggu peristiwa input.
[in] pHandles
Array handel objek. Untuk daftar tipe objek yang handelnya dapat Anda tentukan, lihat bagian Keterangan nanti dalam topik ini. Array dapat berisi handel ke beberapa jenis objek. Ini mungkin tidak berisi beberapa salinan handel yang sama.
Jika salah satu handel ini ditutup saat penantian masih tertunda, perilaku fungsi tidak terdefinisi.
Handel harus memiliki akses SYNCHRONIZE yang tepat. Untuk informasi selengkapnya, lihat Hak Akses Standar.
[in] dwMilliseconds
Interval waktu habis, dalam milidetik. Jika nilai bukan nol ditentukan, fungsi menunggu hingga objek yang ditentukan diberi sinyal, rutinitas penyelesaian I/O atau APC diantrekan, atau interval berlalu. Jika dwMilliseconds nol, fungsi tidak memasukkan status tunggu jika kriteria tidak terpenuhi; selalu kembali segera. Jika dwMillisecondsINFINITE, fungsi hanya akan kembali ketika objek yang ditentukan diberi sinyal atau rutinitas penyelesaian I/O atau APC diantrekan.
[in] dwWakeMask
Jenis input tempat handel objek peristiwa input akan ditambahkan ke array handel objek. Parameter ini dapat berupa kombinasi nilai apa pun yang tercantum dalam benderaGetQueueStatus parameter.
[in] dwFlags
Jenis tunggu. Parameter ini bisa berupa satu atau beberapa nilai berikut.
Nilai | Arti |
---|---|
|
Fungsi mengembalikan ketika salah satu objek diberi sinyal. Nilai pengembalian menunjukkan objek yang statusnya menyebabkan fungsi dikembalikan. |
|
Fungsi ini juga mengembalikan jika APC telah diantrekan ke utas dengan QueueUserAPC saat utas dalam status menunggu. |
|
Fungsi mengembalikan jika input ada untuk antrean, bahkan jika input telah terlihat (tetapi tidak dihapus) menggunakan panggilan ke fungsi lain, seperti PeekMessage. |
|
Fungsi mengembalikan ketika semua objek dalam array |
Mengembalikan nilai
Jika fungsi berhasil, nilai pengembalian menunjukkan peristiwa yang menyebabkan fungsi dikembalikan. Ini bisa menjadi salah satu nilai berikut. (Perhatikan bahwa WAIT_OBJECT_0 didefinisikan sebagai 0 dan WAIT_ABANDONED_0 didefinisikan sebagai 0x00000080L.)
Mengembalikan kode/nilai | Deskripsi |
---|---|
|
Jika bendera MWMO_WAITALL digunakan, nilai pengembalian dalam rentang yang ditentukan menunjukkan bahwa status semua objek yang ditentukan diberi sinyal. Jika tidak, nilai yang dikembalikan dikurangi WAIT_OBJECT_0 menunjukkan pHandles indeks array objek yang menyebabkan fungsi kembali. |
|
Input baru dari jenis yang ditentukan dalam parameter Nilai ini juga dikembalikan setelah terjadinya peristiwa sistem yang memerlukan tindakan utas, seperti aktivasi latar depan. Oleh karena itu, MsgWaitForMultipleObjectsEx dapat kembali meskipun tidak ada input yang sesuai yang tersedia dan bahkan jika dwWakeMask diatur ke 0. Jika ini terjadi, panggil GetMessage atau PeekMessage untuk memproses peristiwa sistem sebelum mencoba panggilan ke MsgWaitForMultipleObjectsEx lagi. |
|
Jika bendera MWMO_WAITALL digunakan, nilai pengembalian dalam rentang yang ditentukan menunjukkan bahwa status semua objek yang ditentukan diberi sinyal dan setidaknya salah satu objek adalah objek mutex yang ditinggalkan. Jika tidak, nilai pengembalian dikurangi WAIT_ABANDONED_0 menunjukkan pHandles indeks array objek mutex yang ditinggalkan yang menyebabkan fungsi kembali. Kepemilikan objek mutex diberikan ke utas panggilan, dan mutex diatur ke nonsignaled.
Jika mutex melindungi informasi status persisten, Anda harus memeriksanya untuk konsistensi. |
|
Penantian diakhir oleh satu atau beberapa mode pengguna panggilan prosedur asinkron (APC) yang diantrekan ke utas. |
|
Interval waktu habis berlalu, tetapi kondisi yang ditentukan oleh parameter dwFlags dan dwWakeMask tidak terpenuhi. |
|
Fungsi telah gagal. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError. |
Komentar
Fungsi MsgWaitForMultipleObjectsEx
Ketika dwFlags adalah nol, fungsi ini memeriksa handel dalam array secara berurutan dimulai dengan indeks 0, hingga salah satu objek diberi sinyal. Jika beberapa objek menjadi sinyal, fungsi mengembalikan indeks handel pertama dalam array yang objeknya diberi sinyal.
MsgWaitForMultipleObjectsEx tidak kembali jika ada input yang belum dibaca dari jenis yang ditentukan dalam antrean pesan setelah utas memanggil fungsi untuk memeriksa antrean, kecuali Anda menggunakan bendera MWMO_INPUTAVAILABLE. Ini karena fungsi seperti PeekMessage, GetMessage, GetQueueStatus, dan WaitMessage memeriksa antrean lalu mengubah informasi status untuk antrean sehingga input tidak lagi dianggap baru. Panggilan berikutnya ke MsgWaitForMultipleObjectsEx tidak akan kembali sampai input baru dari jenis yang ditentukan tiba, kecuali Anda menggunakan bendera MWMO_INPUTAVAILABLE. Jika bendera ini tidak digunakan, input belum dibaca yang ada (diterima sebelum terakhir kali utas memeriksa antrean) diabaikan.
Fungsi memodifikasi status beberapa jenis objek sinkronisasi. Modifikasi hanya terjadi untuk objek atau objek yang status sinyalnya menyebabkan fungsi kembali. Misalnya, sistem mengurangi jumlah objek semaphore satu per satu. Untuk informasi selengkapnya, lihat dokumentasi untuk objek sinkronisasi individual.
Fungsi MsgWaitForMultipleObjectsEx
- Mengubah pemberitahuan
- Input konsol
- Peristiwa
- Pemberitahuan sumber daya memori
- Mutex
- Proses
- Semaphore
- Benang
- Timer yang dapat ditunda
Persyaratan
Syarat | Nilai |
---|---|
klien minimum yang didukung | Windows XP [hanya aplikasi desktop] |
server minimum yang didukung |
Windows Server 2003 [hanya aplikasi desktop] |
Platform Target |
Windows |
Header |
winuser.h (termasuk Windows.h) |
Pustaka |
User32.lib |
DLL |
User32.dll |
Lihat juga
Fungsi Sinkronisasi
Fungsi Tunggu