Fungsi SetWinEventHook (winuser.h)
Mengatur fungsi hook peristiwa untuk berbagai peristiwa.
Sintaks
HWINEVENTHOOK SetWinEventHook(
[in] DWORD eventMin,
[in] DWORD eventMax,
[in] HMODULE hmodWinEventProc,
[in] WINEVENTPROC pfnWinEventProc,
[in] DWORD idProcess,
[in] DWORD idThread,
[in] DWORD dwFlags
);
Parameter
[in] eventMin
Jenis: UINT
Menentukan konstanta peristiwa untuk nilai peristiwa terendah dalam rentang peristiwa yang ditangani oleh fungsi hook. Parameter ini dapat diatur ke EVENT_MIN untuk menunjukkan nilai peristiwa terendah yang mungkin.
[in] eventMax
Jenis: UINT
Menentukan konstanta peristiwa untuk nilai peristiwa tertinggi dalam rentang peristiwa yang ditangani oleh fungsi hook. Parameter ini dapat diatur ke EVENT_MAX untuk menunjukkan nilai peristiwa setingkat mungkin.
[in] hmodWinEventProc
Jenis: HMODULE
Tangani ke DLL yang berisi fungsi hook di lpfnWinEventProc, jika bendera WINEVENT_INCONTEXT ditentukan dalam parameter dwFlags . Jika fungsi hook tidak terletak di DLL, atau jika bendera WINEVENT_OUTOFCONTEXT ditentukan, parameter ini adalah NULL.
[in] pfnWinEventProc
Jenis: WINEVENTPROC
Arahkan ke fungsi hook peristiwa. Untuk informasi selengkapnya tentang fungsi ini, lihat WinEventProc.
[in] idProcess
Jenis: DWORD
Menentukan ID proses tempat fungsi hook menerima peristiwa. Tentukan nol (0) untuk menerima peristiwa dari semua proses pada desktop saat ini.
[in] idThread
Jenis: DWORD
Menentukan ID utas tempat fungsi hook menerima peristiwa. Jika parameter ini nol, fungsi hook dikaitkan dengan semua utas yang ada di desktop saat ini.
[in] dwFlags
Jenis: UINT
Benderai nilai yang menentukan lokasi fungsi hook dan peristiwa yang akan dilewati. Bendera berikut ini valid:
| Nilai | Makna |
|---|---|
|
DLL yang berisi fungsi panggilan balik dipetakan ke ruang alamat proses yang menghasilkan peristiwa. Dengan bendera ini, sistem mengirim pemberitahuan peristiwa ke fungsi panggilan balik saat terjadi. Fungsi hook harus dalam DLL ketika bendera ini ditentukan. Bendera ini tidak berpengaruh ketika proses panggilan dan proses pembuatan bukan proses 32-bit atau 64-bit, atau ketika proses pembuatan adalah aplikasi konsol. Untuk informasi selengkapnya, lihat Fungsi Hook Dalam Konteks. |
|
Fungsi panggilan balik tidak dipetakan ke ruang alamat proses yang menghasilkan peristiwa. Karena fungsi kait dipanggil melintasi batas proses, sistem harus mengantre peristiwa. Meskipun metode ini asinkron, peristiwa dijamin berada dalam urutan berurutan. Untuk informasi selengkapnya, lihat Fungsi Hook Di Luar Konteks. |
|
Mencegah instans hook ini menerima peristiwa yang dihasilkan oleh utas dalam proses ini. Bendera ini tidak mencegah utas menghasilkan peristiwa. |
|
Mencegah instans hook ini menerima peristiwa yang dihasilkan oleh utas yang mendaftarkan hook ini. |
Kombinasi bendera berikut ini valid:
- WINEVENT_INCONTEXT | WINEVENT_SKIPOWNPROCESS
- WINEVENT_INCONTEXT | WINEVENT_SKIPOWNTHREAD
- WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS
- WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNTHREAD
Lihat bagian Keterangan untuk informasi tentang pengembangan aplikasi Bursa Windows.
Mengembalikan nilai
Jenis: HWINEVENTHOOK
Jika berhasil, mengembalikan nilai HWINEVENTHOOK yang mengidentifikasi instans hook peristiwa ini. Aplikasi menyimpan nilai pengembalian ini untuk menggunakannya dengan fungsi UnhookWinEvent .
Jika tidak berhasil, mengembalikan nol.
Keterangan
Fungsi ini memungkinkan klien untuk menentukan proses dan utas mana yang mereka minati.
Jika parameter idProcess bukan nol dan idThread adalah nol, fungsi hook menerima peristiwa yang ditentukan dari semua utas dalam proses tersebut. Jika parameter idProcess adalah nol dan idThread bukan nol, fungsi hook hanya menerima peristiwa yang ditentukan dari utas yang ditentukan oleh idThread. Jika keduanya nol, fungsi hook menerima peristiwa yang ditentukan dari semua utas dan proses.
Klien dapat memanggil SetWinEventHook beberapa kali jika mereka ingin mendaftarkan fungsi hook tambahan atau mendengarkan peristiwa tambahan.
Utas klien yang memanggil SetWinEventHook harus memiliki perulangan pesan untuk menerima peristiwa.
Saat Anda menggunakan SetWinEventHook untuk mengatur panggilan balik dalam kode terkelola, Anda harus menggunakan struktur GCHandle untuk menghindari pengecualian. Ini memberi tahu pengumpul sampah untuk tidak memindahkan panggilan balik.
Untuk peristiwa di luar konteks, peristiwa dikirimkan pada utas yang sama yang disebut SetWinEventHook. Dalam beberapa situasi, bahkan jika Anda meminta peristiwa WINEVENT_INCONTEXT, peristiwa akan tetap dikirimkan di luar konteks. Skenario ini mencakup peristiwa dari jendela konsol dan peristiwa dari proses yang memiliki kedalaman bit yang berbeda (64 bit versus 32 bit) daripada pemanggil.
Sementara fungsi kait memproses peristiwa, peristiwa tambahan dapat dipicu, yang dapat menyebabkan fungsi kait masuk kembali sebelum pemrosesan untuk peristiwa asli selesai. Masalah dengan masuknya kembali dalam fungsi kait adalah bahwa peristiwa selesai secara berurutan kecuali fungsi kait menangani situasi ini. Untuk informasi selengkapnya, lihat Menjaga Terhadap Reentrancy.
Pengembangan aplikasi Bursa Windows Jika dwFlags WINEVENT_INCONTEXT AND (idProcess = 0 | idThread = 0), maka DLL kait jendela tidak dimuat dalam proses untuk proses aplikasi Windows Store dan proses broker Windows Runtime kecuali jika diinstal oleh proses UIAccess (alat aksesibilitas). Pemberitahuan dikirimkan pada utas alat penginstal.
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
Contoh kode berikut menunjukkan bagaimana aplikasi klien mungkin mendengarkan peristiwa menu-start dan menu-end. Untuk kesederhanaan, penanganan aktivitas hanya mengirim beberapa informasi ke output standar.
// Global variable.
HWINEVENTHOOK g_hook;
// Initializes COM and sets up the event hook.
//
void InitializeMSAA()
{
CoInitialize(NULL);
g_hook = SetWinEventHook(
EVENT_SYSTEM_MENUSTART, EVENT_SYSTEM_MENUEND, // Range of events (4 to 5).
NULL, // Handle to DLL.
HandleWinEvent, // The callback.
0, 0, // Process and thread IDs of interest (0 = all)
WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS); // Flags.
}
// Unhooks the event and shuts down COM.
//
void ShutdownMSAA()
{
UnhookWinEvent(g_hook);
CoUninitialize();
}
// Callback function that handles events.
//
void CALLBACK HandleWinEvent(HWINEVENTHOOK hook, DWORD event, HWND hwnd,
LONG idObject, LONG idChild,
DWORD dwEventThread, DWORD dwmsEventTime)
{
IAccessible* pAcc = NULL;
VARIANT varChild;
HRESULT hr = AccessibleObjectFromEvent(hwnd, idObject, idChild, &pAcc, &varChild);
if ((hr == S_OK) && (pAcc != NULL))
{
BSTR bstrName;
pAcc->get_accName(varChild, &bstrName);
if (event == EVENT_SYSTEM_MENUSTART)
{
printf("Begin: ");
}
else if (event == EVENT_SYSTEM_MENUEND)
{
printf("End: ");
}
printf("%S\n", bstrName);
SysFreeString(bstrName);
pAcc->Release();
}
}
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 2000 Professional [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2003 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | winuser.h (termasuk Windows.h) |
| Pustaka | User32.lib |
| DLL | User32.dll |
| Redistribusi | Aksesibilitas Aktif 1.3 RDK pada Windows NT 4.0 dengan SP6 dan yang lebih baru dan Windows 95 |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk