SetWinEventHook 関数 (winuser.h)

  • [アーティクル]

イベントの範囲のイベント フック関数を設定します。

構文

HWINEVENTHOOK SetWinEventHook(
  [in] DWORD        eventMin,
  [in] DWORD        eventMax,
  [in] HMODULE      hmodWinEventProc,
  [in] WINEVENTPROC pfnWinEventProc,
  [in] DWORD        idProcess,
  [in] DWORD        idThread,
  [in] DWORD        dwFlags
);

パラメーター

[in] eventMin

型: UINT

フック関数によって処理されるイベントの範囲内で最も小さいイベント値のイベント 定数 を指定します。 このパラメーターは、可能な限り小さいイベント値を示すために EVENT_MIN に設定できます。

[in] eventMax

型: UINT

フック関数によって処理されるイベントの範囲内で最大のイベント値のイベント定数を指定します。 このパラメーターは、可能な限り高いイベント値を示すために EVENT_MAX に設定できます。

[in] hmodWinEventProc

種類: HMODULE

dwFlags パラメーターにWINEVENT_INCONTEXT フラグが指定されている場合は、lpfnWinEventProc のフック関数を含む DLL を処理します。 フック関数が DLL に配置されていない場合、または WINEVENT_OUTOFCONTEXT フラグが指定されている場合、このパラメーターは NULL です。

[in] pfnWinEventProc

種類: WINEVENTPROC

イベント フック関数へのポインター。 この関数の詳細については、「 WinEventProc」を参照してください。

[in] idProcess

型: DWORD

フック関数がイベントを受信するプロセスの ID を指定します。 現在のデスクトップ上のすべてのプロセスからイベントを受信するには、ゼロ (0) を指定します。

[in] idThread

型: DWORD

フック関数がイベントを受信するスレッドの ID を指定します。 このパラメーターが 0 の場合、フック関数は現在のデスクトップ上のすべての既存のスレッドに関連付けられます。

[in] dwFlags

型: UINT

フック関数の場所とスキップするイベントの場所を指定するフラグ値。 次のフラグが有効です。

値 意味
WINEVENT_INCONTEXT
 コールバック関数を含む DLL は、イベントを生成するプロセスのアドレス空間にマップされます。 このフラグを使用すると、イベント通知が発生すると、システムはコールバック関数にイベント通知を送信します。 このフラグが指定されている場合、フック関数は DLL 内に存在する必要があります。 このフラグは、呼び出し元プロセスと生成プロセスの両方が 32 ビットプロセスまたは 64 ビット・プロセスでない場合、または生成プロセスがコンソール・アプリケーションである場合には無効です。 詳細については、「 コンテキスト内フック関数」を参照してください。
WINEVENT_OUTOFCONTEXT
 コールバック関数は、イベントを生成するプロセスのアドレス空間にマップされません。 フック関数はプロセス境界を越えて呼び出されるため、システムはイベントをキューに入れなければなりません。 このメソッドは非同期ですが、イベントは順番に行われます。 詳細については、「 Out-of-Context フック関数」を参照してください。
WINEVENT_SKIPOWNPROCESS
 フックのこのインスタンスが、このプロセスのスレッドによって生成されるイベントを受信できないようにします。 このフラグは、スレッドによるイベントの生成を妨げるものではありません。
WINEVENT_SKIPOWNTHREAD
 フックのこのインスタンスが、このフックを登録しているスレッドによって生成されたイベントを受信できないようにします。
 

次のフラグの組み合わせが有効です。

  • WINEVENT_INCONTEXT |WINEVENT_SKIPOWNPROCESS
  • WINEVENT_INCONTEXT |WINEVENT_SKIPOWNTHREAD
  • WINEVENT_OUTOFCONTEXT |WINEVENT_SKIPOWNPROCESS
  • WINEVENT_OUTOFCONTEXT |WINEVENT_SKIPOWNTHREAD
さらに、クライアント アプリケーションでは、WINEVENT_INCONTEXTを指定することも、単独でWINEVENT_OUTOFCONTEXTすることもできます。

Windows ストア アプリの開発については、「解説」セクションを参照してください。

戻り値

種類: HWINEVENTHOOK

成功した場合は、このイベント フック インスタンスを識別する HWINEVENTHOOK 値を返します。 アプリケーションはこの戻り値を保存して UnhookWinEvent 関数と共に使用します。

失敗した場合は、0 を返します。

注釈

この関数を使用すると、クライアントは、関心のあるプロセスとスレッドを指定できます。

idProcess パラメーターが 0 以外で idThread が 0 の場合、フック関数はそのプロセス内のすべてのスレッドから指定されたイベントを受け取ります。 idProcess パラメーターが 0 で idThread が 0 以外の場合、フック関数は idThread で指定されたスレッドからのみ指定されたイベントを受け取ります。 両方が 0 の場合、フック関数はすべてのスレッドとプロセスから指定されたイベントを受け取ります。

クライアントは、追加のフック関数を登録したり、追加のイベントをリッスンしたりする場合に 、SetWinEventHook を複数回呼び出すことができます。

イベントを受信するには、 SetWinEventHook を呼び出すクライアント スレッドにメッセージ ループが必要です。

SetWinEventHook を使用してマネージド コードでコールバックを設定する場合は、例外を回避するために GCHandle 構造体を使用する必要があります。 これにより、コールバックを移動しないようにガベージ コレクターに指示されます。

コンテキスト外イベントの場合、イベントは SetWinEventHook と呼ばれるのと同じスレッドで配信されます。 状況によっては、WINEVENT_INCONTEXTイベントを要求した場合でも、イベントはコンテキスト外で配信されます。 これらのシナリオには、コンソール ウィンドウからのイベントと、呼び出し元とは異なるビット深度 (64 ビットと 32 ビット) を持つプロセスからのイベントが含まれます。

フック関数がイベントを処理している間に、追加のイベントがトリガーされる可能性があります。これにより、元のイベントの処理が完了する前にフック関数が再入力される可能性があります。 フック関数の再入の問題は、フック関数がこの状況を処理しない限り、イベントが順番に完了しないということです。 詳細については、「 再入を防ぐために保護する」を参照してください。

Windows ストア アプリの開発dwFlags が AND (idProcess = 0 | idThread = 0) WINEVENT_INCONTEXT場合、ウィンドウ フック DLL は、UIAccess プロセス (アクセシビリティ ツール) によってインストールされない限り、Windows ストア アプリ プロセスとWindows ランタイム ブローカー プロセスのインプロセスで読み込まれません。 通知はインストーラーのスレッドで配信されます。

この動作は、フック DLL とターゲット アプリケーション プロセスの間にアーキテクチャの不一致がある場合 (たとえば、フック DLL が 32 ビットで、アプリケーション プロセスが 64 ビットである場合) に発生する動作と似ています。

例

次のコード例は、クライアント アプリケーションがメニュー開始イベントとメニュー終了イベントをリッスンする方法を示しています。 わかりやすくするために、イベント ハンドラーは標準出力に情報を送信するだけです。


// 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();
    }
}

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー winuser.h (Windows.h を含む)
Library User32.lib
[DLL] User32.dll
再頒布可能パッケージ SP6 以降および Windows 95 を使用した Windows NT 4.0 のアクティブなアクセシビリティ 1.3 RDK

こちらもご覧ください

フック関数の登録

UnhookWinEvent

WinEventProc