Fungsi SetWinEventHook (winuser.h)

Artikel
08/28/2023

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
WINEVENT_INCONTEXT	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.
WINEVENT_OUTOFCONTEXT	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.
WINEVENT_SKIPOWNPROCESS	Mencegah instans hook ini menerima peristiwa yang dihasilkan oleh utas dalam proses ini. Bendera ini tidak mencegah utas menghasilkan peristiwa.
WINEVENT_SKIPOWNTHREAD	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

Selain itu, aplikasi klien dapat menentukan WINEVENT_INCONTEXT, atau WINEVENT_OUTOFCONTEXT saja.

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

Mendaftarkan Fungsi Hook

UnhookWinEvent

WinEventProc

Bagikan melalui

Fungsi SetWinEventHook (winuser.h)

Sintaks

Parameter

Mengembalikan nilai

Keterangan

Contoh

Persyaratan

Lihat juga

Saran dan Komentar

Sumber Daya Tambahan: