Fungsi PeekMessageA (winuser.h)

Artikel
03/13/2024

Mengirimkan pesan masuk yang tidak diantrekan, memeriksa antrean pesan utas untuk pesan yang diposting, dan mengambil pesan (jika ada).

Sintaks

BOOL PeekMessageA(
  [out]          LPMSG lpMsg,
  [in, optional] HWND  hWnd,
  [in]           UINT  wMsgFilterMin,
  [in]           UINT  wMsgFilterMax,
  [in]           UINT  wRemoveMsg
);

Parameter

[out] lpMsg

Jenis: LPMSG

Penunjuk ke struktur MSG yang menerima informasi pesan.

[in, optional] hWnd

Jenis: HWND

Handel ke jendela yang pesannya akan diambil. Jendela harus milik utas saat ini.

Jika hWnd adalah NULL, PeekMessage mengambil pesan untuk jendela apa pun yang termasuk dalam utas saat ini, dan pesan apa pun pada antrean pesan utas saat ini yang nilai hwnd-nyaadalah NULL (lihat struktur MSG ). Oleh karena itu, jika hWnd adalah NULL, pesan jendela dan pesan utas diproses.

Jika hWnd adalah -1, PeekMessage hanya mengambil pesan pada antrean pesan utas saat ini yang nilai hwnd-nyaadalah NULL, yaitu pesan utas seperti yang diposting oleh PostMessage (ketika parameter hWnd adalah NULL) atau PostThreadMessage.

[in] wMsgFilterMin

Jenis: UINT

Nilai pesan pertama dalam rentang pesan yang akan diperiksa. Gunakan WM_KEYFIRST (0x0100) untuk menentukan pesan keyboard pertama atau WM_MOUSEFIRST (0x0200) untuk menentukan pesan mouse pertama.

Jika wMsgFilterMin dan wMsgFilterMax keduanya nol, PeekMessage mengembalikan semua pesan yang tersedia (artinya, tidak ada pemfilteran rentang yang dilakukan).

[in] wMsgFilterMax

Jenis: UINT

Nilai pesan terakhir dalam rentang pesan yang akan diperiksa. Gunakan WM_KEYLAST untuk menentukan pesan keyboard terakhir atau WM_MOUSELAST untuk menentukan pesan mouse terakhir.

Jika wMsgFilterMin dan wMsgFilterMax keduanya nol, PeekMessage mengembalikan semua pesan yang tersedia (artinya, tidak ada pemfilteran rentang yang dilakukan).

[in] wRemoveMsg

Jenis: UINT

Menentukan bagaimana pesan akan ditangani. Parameter ini bisa menjadi satu atau beberapa nilai berikut.

Nilai	Makna
PM_NOREMOVE 0x0000	Pesan tidak dihapus dari antrean setelah diproses oleh PeekMessage.
PM_REMOVE 0x0001	Pesan dihapus dari antrean setelah diproses oleh PeekMessage.
PM_NOYIELD 0x0002	Mencegah sistem merilis utas apa pun yang menunggu penelepon menganggur (lihat WaitForInputIdle). Gabungkan nilai ini dengan PM_NOREMOVE atau PM_REMOVE.

Secara default, semua jenis pesan diproses. Untuk menentukan bahwa hanya pesan tertentu yang harus diproses, tentukan satu atau beberapa nilai berikut.

Nilai	Makna
PM_QS_INPUT (QS_INPUT << 16)	Memproses pesan mouse dan keyboard.
PM_QS_PAINT (QS_PAINT << 16)	Memproses pesan cat.
PM_QS_POSTMESSAGE ((QS_POSTMESSAGE \| QS_HOTKEY \| QS_TIMER) << 16)	Proses semua pesan yang diposting, termasuk timer dan hotkey.
PM_QS_SENDMESSAGE (QS_SENDMESSAGE << 16)	Proses semua pesan terkirim.

Mengembalikan nilai

Jenis: BOOL

Jika pesan tersedia, nilai yang dikembalikan bukan nol.

Jika tidak ada pesan yang tersedia, nilai yang dikembalikan adalah nol.

Keterangan

PeekMessage mengambil pesan yang terkait dengan jendela yang diidentifikasi oleh parameter hWnd atau salah satu turunannya seperti yang ditentukan oleh fungsi IsChild , dan dalam rentang nilai pesan yang diberikan oleh parameter wMsgFilterMin dan wMsgFilterMax . Perhatikan bahwa aplikasi hanya dapat menggunakan kata rendah dalam parameter wMsgFilterMin dan wMsgFilterMax ; kata tinggi disediakan untuk sistem.

Perhatikan bahwa PeekMessage selalu mengambil pesan WM_QUIT , apa pun nilai yang Anda tentukan untuk wMsgFilterMin dan wMsgFilterMax.

Selama panggilan ini, sistem mengirim (DispatchMessage) tertunda, pesan yang tidak diantrekan, yaitu, pesan yang dikirim ke jendela yang dimiliki oleh utas panggilan menggunakan fungsi SendMessage, SendMessageCallback, SendMessageTimeout, atau SendNotifyMessage . Kemudian pesan antrean pertama yang cocok dengan filter yang ditentukan diambil. Sistem juga dapat memproses peristiwa internal. Jika tidak ada filter yang ditentukan, pesan diproses dalam urutan berikut:

Pesan terkirim
Pesan yang diposting
Pesan input (perangkat keras) dan peristiwa internal sistem
Pesan terkirim (sekali lagi)
WM_PAINT pesan
WM_TIMER pesan

Untuk mengambil pesan input sebelum pesan yang diposting, gunakan parameter wMsgFilterMin dan wMsgFilterMax .

Fungsi PeekMessage biasanya tidak menghapus pesan WM_PAINT dari antrean. WM_PAINT pesan tetap dalam antrean hingga diproses. Namun, jika pesan WM_PAINT memiliki wilayah pembaruan NULL , PeekMessage menghapusnya dari antrean.

Jika jendela tingkat atas berhenti merespons pesan selama lebih dari beberapa detik, sistem menganggap jendela tidak merespons dan menggantinya dengan jendela hantu yang memiliki atribut urutan z, lokasi, ukuran, dan visual yang sama. Ini memungkinkan pengguna untuk memindahkannya, mengubah ukurannya, atau bahkan menutup aplikasi. Namun, ini adalah satu-satunya tindakan yang tersedia karena aplikasi sebenarnya tidak merespons. Ketika aplikasi sedang di-debug, sistem tidak menghasilkan jendela hantu.

Virtualisasi DPI

API ini tidak berpartisipasi dalam virtualisasi DPI. Output berada dalam mode jendela yang ditargetkan pesan. Utas panggilan tidak dipertimbangkan.

Contoh

Misalnya, lihat Memeriksa Antrean Pesan.

Catatan

Header winuser.h mendefinisikan PeekMessage sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	winuser.h (termasuk Windows.h)
Pustaka	User32.lib
DLL	User32.dll
Set API	ext-ms-win-ntuser-message-l1-1-0 (diperkenalkan dalam Windows 8)