Fungsi GetMessageW (winuser.h)

Artikel
03/09/2024

Mengambil pesan dari antrean pesan utas panggilan. Fungsi mengirimkan pesan terkirim masuk hingga pesan yang diposting tersedia untuk diambil.

Tidak seperti GetMessage, fungsi PeekMessage tidak menunggu pesan diposting sebelum kembali.

Sintaks

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

Parameter

[out] lpMsg

Jenis: LPMSG

Penunjuk ke struktur MSG yang menerima informasi pesan dari antrean pesan utas.

[in, optional] hWnd

Jenis: HWND

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

Jika hWndADALAH NULL, GetMessage 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 NULL, pesan jendela dan pesan utas diproses.

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

[in] wMsgFilterMin

Jenis: UINT

Nilai bilangan bulat dari nilai pesan terendah yang akan diambil. Gunakan WM_KEYFIRST (0x0100) untuk menentukan pesan keyboard pertama atau WM_MOUSEFIRST (0x0200) untuk menentukan pesan mouse pertama.

Gunakan WM_INPUT di sini dan di wMsgFilterMax untuk menentukan hanya pesan WM_INPUT .

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

[in] wMsgFilterMax

Jenis: UINT

Nilai bilangan bulat dari nilai pesan tertinggi yang akan diambil. Gunakan WM_KEYLAST untuk menentukan pesan keyboard terakhir atau WM_MOUSELAST untuk menentukan pesan mouse terakhir.

Gunakan WM_INPUT di sini dan di wMsgFilterMin untuk menentukan hanya pesan WM_INPUT .

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

Nilai kembali

Jenis: BOOL

Jika fungsi mengambil pesan selain WM_QUIT, nilai yang dikembalikan bukan nol.

Jika fungsi mengambil pesan WM_QUIT , nilai yang dikembalikan adalah nol.

Jika ada kesalahan, nilai yang dikembalikan adalah -1. Misalnya, fungsi gagal jika hWnd adalah handel jendela yang tidak valid atau lpMsg adalah penunjuk yang tidak valid. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Karena nilai yang dikembalikan dapat berupa bukan nol, nol, atau -1, hindari kode seperti ini:

while (GetMessage( lpMsg, hWnd, 0, 0)) ...

Kemungkinan nilai pengembalian -1 dalam kasus bahwa hWnd adalah parameter yang tidak valid (seperti mengacu pada jendela yang telah dihancurkan) berarti bahwa kode tersebut dapat menyebabkan kesalahan aplikasi yang fatal. Sebagai gantinya, gunakan kode seperti ini:

BOOL bRet;

while( (bRet = GetMessage( &msg, hWnd, 0, 0 )) != 0)
{ 
    if (bRet == -1)
    {
        // handle the error and possibly exit
    }
    else
    {
        TranslateMessage(&msg); 
        DispatchMessage(&msg); 
    }
}

Keterangan

Aplikasi biasanya menggunakan nilai pengembalian untuk menentukan apakah akan mengakhiri perulangan pesan utama dan keluar dari program.

Fungsi GetMessage 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 GetMessage selalu mengambil pesan WM_QUIT , apa pun nilai yang Anda tentukan untuk wMsgFilterMin dan wMsgFilterMax.

Selama panggilan ini, sistem mengirimkan pesan yang tertunda dan 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 .

GetMessage tidak menghapus pesan WM_PAINT dari antrean. Pesan tetap dalam antrean hingga diproses.

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 dalam mode debugger, 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 Membuat Perulangan Pesan.

Catatan

Header winuser.h mendefinisikan GetMessage 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)