Fungsi SetWindowsHookExA (winuser.h)

Artikel
01/27/2024

Menginstal prosedur kait yang ditentukan aplikasi ke dalam rantai kait. Anda akan menginstal prosedur kait untuk memantau sistem untuk jenis peristiwa tertentu. Peristiwa ini dikaitkan dengan utas tertentu atau dengan semua utas di desktop yang sama dengan utas panggilan.

Sintaks

HHOOK SetWindowsHookExA(
  [in] int       idHook,
  [in] HOOKPROC  lpfn,
  [in] HINSTANCE hmod,
  [in] DWORD     dwThreadId
);

Parameter

[in] idHook

Jenis: int

Jenis prosedur kait yang akan diinstal. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
WH_CALLWNDPROC 4	Menginstal prosedur kait yang memantau pesan sebelum sistem mengirimkannya ke prosedur jendela tujuan. Untuk informasi selengkapnya, lihat prosedur hook CallWndProc .
WH_CALLWNDPROCRET 12	Menginstal prosedur kait yang memantau pesan setelah diproses oleh prosedur jendela tujuan. Untuk informasi selengkapnya, lihat prosedur hook [fungsi panggilan balik HOOKPROC](nc-winuser-hookproc.md).
WH_CBT 5	Menginstal prosedur kait yang menerima pemberitahuan yang berguna untuk aplikasi CBT. Untuk informasi selengkapnya, lihat prosedur hook CBTProc .
WH_DEBUG 9	Menginstal prosedur kait yang berguna untuk men-debug prosedur kait lainnya. Untuk informasi selengkapnya, lihat prosedur hook DebugProc .
WH_FOREGROUNDIDLE 11	Menginstal prosedur kait yang akan dipanggil ketika utas latar depan aplikasi akan menjadi menganggur. Kait ini berguna untuk melakukan tugas berprioritas rendah selama waktu diam. Untuk informasi selengkapnya, lihat prosedur hook ForegroundIdleProc .
WH_GETMESSAGE 3	Menginstal prosedur hook yang memantau pesan yang diposting ke antrean pesan. Untuk informasi selengkapnya, lihat prosedur hook GetMsgProc .
WH_JOURNALPLAYBACK 1	Peringatan Windows 11 dan yang lebih baru: API kait jurnal tidak didukung. Sebaiknya gunakan API TextInput SendInput sebagai gantinya. Menginstal prosedur hook yang memposting pesan yang sebelumnya direkam oleh prosedur hook WH_JOURNALRECORD . Untuk informasi selengkapnya, lihat prosedur hook JournalPlaybackProc .
WH_JOURNALRECORD 0	Peringatan Windows 11 dan yang lebih baru: API kait jurnal tidak didukung. Sebaiknya gunakan API TextInput SendInput sebagai gantinya. Menginstal prosedur kait yang merekam pesan input yang diposting ke antrean pesan sistem. Kait ini berguna untuk merekam makro. Untuk informasi selengkapnya, lihat prosedur hook JournalRecordProc .
WH_KEYBOARD 2	Menginstal prosedur kait yang memantau pesan penekanan tombol. Untuk informasi selengkapnya, lihat prosedur hook KeyboardProc .
WH_KEYBOARD_LL 13	Menginstal prosedur kait yang memantau peristiwa input keyboard tingkat rendah. Untuk informasi selengkapnya, lihat prosedur hook [LowLevelKeyboardProc](/windows/win32/winmsg/lowlevelkeyboardproc).
WH_MOUSE 7	Menginstal prosedur kait yang memantau pesan mouse. Untuk informasi selengkapnya, lihat prosedur hook MouseProc .
WH_MOUSE_LL 14	Menginstal prosedur kait yang memantau peristiwa input mouse tingkat rendah. Untuk informasi selengkapnya, lihat prosedur hook LowLevelMouseProc .
WH_MSGFILTER -1	Menginstal prosedur hook yang memantau pesan yang dihasilkan sebagai hasil dari peristiwa input dalam kotak dialog, kotak pesan, menu, atau bilah gulir. Untuk informasi selengkapnya, lihat prosedur hook MessageProc .
WH_SHELL 10	Menginstal prosedur kait yang menerima pemberitahuan yang berguna untuk aplikasi shell. Untuk informasi selengkapnya, lihat prosedur hook ShellProc .
WH_SYSMSGFILTER 6	Menginstal prosedur hook yang memantau pesan yang dihasilkan sebagai hasil dari peristiwa input dalam kotak dialog, kotak pesan, menu, atau bilah gulir. Prosedur kait memantau pesan-pesan ini untuk semua aplikasi di desktop yang sama dengan utas panggilan. Untuk informasi selengkapnya, lihat prosedur hook SysMsgProc .

[in] lpfn

Jenis: HOOKPROC

Penunjuk ke prosedur kait. Jika parameter dwThreadId adalah nol atau menentukan pengidentifikasi utas yang dibuat oleh proses yang berbeda, parameter lpfn harus menunjuk ke prosedur hook di DLL. Jika tidak, lpfn dapat menunjuk ke prosedur kait dalam kode yang terkait dengan proses saat ini.

[in] hmod

Jenis: HINSTANCE

Handel ke DLL yang berisi prosedur kait yang diarahkan oleh parameter lpfn . Parameter hMod harus diatur ke NULL jika parameter dwThreadId menentukan utas yang dibuat oleh proses saat ini dan jika prosedur kait berada dalam kode yang terkait dengan proses saat ini.

[in] dwThreadId

Jenis: DWORD

Pengidentifikasi utas yang prosedur kaitnya akan dikaitkan. Untuk aplikasi desktop, jika parameter ini nol, prosedur kait dikaitkan dengan semua utas yang ada yang berjalan di desktop yang sama dengan utas panggilan. Untuk aplikasi Bursa Windows, lihat bagian Keterangan.

Mengembalikan nilai

Jenis: HHOOK

Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke prosedur kait.

Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

SetWindowsHookEx dapat digunakan untuk menyuntikkan DLL ke proses lain. DLL 32-bit tidak dapat disuntikkan ke dalam proses 64-bit, dan DLL 64-bit tidak dapat disuntikkan ke dalam proses 32-bit. Jika aplikasi memerlukan penggunaan kait dalam proses lain, diperlukan aplikasi 32-bit memanggil SetWindowsHookEx untuk menyuntikkan DLL 32-bit ke dalam proses 32-bit, dan aplikasi 64-bit memanggil SetWindowsHookEx untuk menyuntikkan DLL 64-bit ke dalam proses 64-bit. DLL 32-bit dan 64-bit harus memiliki nama yang berbeda.

Karena kait berjalan dalam konteks aplikasi, kait harus cocok dengan "bitness" aplikasi. Jika aplikasi 32-bit menginstal kait global pada Windows 64-bit, kait 32-bit disuntikkan ke dalam setiap proses 32-bit (batas keamanan biasa berlaku). Dalam proses 64-bit, utas masih ditandai sebagai "kait." Namun, karena aplikasi 32-bit harus menjalankan kode kait, sistem menjalankan kait dalam konteks aplikasi pengait; khususnya, pada utas yang disebut SetWindowsHookEx. Ini berarti bahwa aplikasi hooking harus terus memompa pesan atau mungkin memblokir fungsi normal proses 64-bit.

Jika aplikasi 64-bit menginstal kait global pada Windows 64-bit, kait 64-bit disuntikkan ke dalam setiap proses 64-bit, sementara semua proses 32-bit menggunakan panggilan balik ke aplikasi pengait.

Untuk menghubungkan semua aplikasi di desktop penginstalan Windows 64-bit, instal kait global 32-bit dan kait global 64-bit, masing-masing dari proses yang sesuai, dan pastikan untuk terus memompa pesan di aplikasi pengait untuk menghindari pemblokiran fungsi normal. Jika Anda sudah memiliki aplikasi kait global 32-bit dan tidak perlu berjalan dalam konteks setiap aplikasi, Anda mungkin tidak perlu membuat versi 64-bit.

Kesalahan dapat terjadi jika parameter hMod adalah NULL dan parameter dwThreadId adalah nol atau menentukan pengidentifikasi utas yang dibuat oleh proses lain.

Memanggil fungsi CallNextHookEx untuk merantai ke prosedur kait berikutnya bersifat opsional, tetapi sangat disarankan; jika tidak, aplikasi lain yang telah menginstal kait tidak akan menerima pemberitahuan kait dan mungkin bertingkah salah sebagai akibatnya. Anda harus memanggil CallNextHookEx kecuali Anda benar-benar perlu mencegah pemberitahuan dilihat oleh aplikasi lain.

Sebelum mengakhiri, aplikasi harus memanggil fungsi fungsi UnhookWindowsHookEx untuk membebaskan sumber daya sistem yang terkait dengan hook.

Cakupan kait tergantung pada jenis kait. Beberapa kait hanya dapat diatur dengan cakupan global; yang lain juga dapat diatur hanya untuk utas tertentu, seperti yang diperlihatkan dalam tabel berikut.

Kait	Cakupan
WH_CALLWNDPROC	Utas atau global
WH_CALLWNDPROCRET	Utas atau global
WH_CBT	Utas atau global
WH_DEBUG	Utas atau global
WH_FOREGROUNDIDLE	Utas atau global
WH_GETMESSAGE	Utas atau global
WH_JOURNALPLAYBACK	Hanya global
WH_JOURNALRECORD	Hanya global
WH_KEYBOARD	Utas atau global
WH_KEYBOARD_LL	Hanya global
WH_MOUSE	Utas atau global
WH_MOUSE_LL	Hanya global
WH_MSGFILTER	Utas atau global
WH_SHELL	Utas atau global
WH_SYSMSGFILTER	Hanya global

Untuk jenis kait tertentu, kait utas dipanggil terlebih dahulu, lalu kait global. Ketahuilah bahwa kait WH_MOUSE, WH_KEYBOARD, WH_JOURNAL*, WH_SHELL, dan tingkat rendah dapat dipanggil pada utas yang memasang kait daripada utas yang memproses kait. Untuk kait ini, ada kemungkinan bahwa kait 32-bit dan 64-bit akan dipanggil jika kait 32-bit berada di depan kait 64-bit di rantai kait.

Kait global adalah sumber daya bersama, dan menginstalnya memengaruhi semua aplikasi di desktop yang sama dengan utas panggilan. Semua fungsi kait global harus berada di pustaka. Kait global harus dibatasi untuk aplikasi tujuan khusus atau untuk digunakan sebagai bantuan pengembangan selama penelusuran kesalahan aplikasi. Pustaka yang tidak lagi membutuhkan kait harus menghapus prosedur kaitnya.

Pengembangan aplikasi Bursa Windows Jika dwThreadId adalah nol, maka DLL kait jendela tidak dimuat dalam proses untuk proses aplikasi Windows Store dan proses broker Windows Runtime kecuali diinstal oleh proses UIAccess (alat aksesibilitas). Pemberitahuan dikirimkan pada utas alat penginstal untuk kait ini:

WH_JOURNALPLAYBACK
WH_JOURNALRECORD
WH_KEYBOARD
WH_KEYBOARD_LL
WH_MOUSE
WH_MOUSE_LL

Perilaku ini mirip dengan apa yang terjadi ketika ada ketidakcocokan arsitektur antara DLL kait dan proses aplikasi target, misalnya, ketika DLL kait adalah 32-bit dan proses aplikasi 64-bit.

Contoh

Misalnya, lihat Menginstal dan Merilis Prosedur Hook.

Catatan

Header winuser.h mendefinisikan SetWindowsHookEx 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 (sertakan Windows.h)
Pustaka	User32.lib
DLL	User32.dll
Set API	ext-ms-win-ntuser-window-l1-1-0 (diperkenalkan dalam Windows 8)