SetWinEventHook

Description

The SetWinEventHook function sets an event hook function for a range of events.

C++ Syntax

PowerBASIC Syntax

Parameters

eventMin

[in] Specifies the event constant for the lowest event value in the range of events handled by the hook function. This parameter is EVENT_MIN to indicate the lowest possible event value.

eventMax

[in] Specifies the event constant for the highest event value in the range of events handled by the hook function. This parameter is EVENT_MAX to indicate the highest possible event value.

hmodWinEventProc

[in] Handle to the dynamic-link library (DLL) that contains the hook function at lpfnWinEventProc if the WINEVENT_INCONTEXT flag is specified in the dwFlags parameter. If the hook function is not located in a DLL, or if the WINEVENT_OUTOFCONTEXT flag is specified, this parameter is NULL.

lpfnWinEventProc

[out] Address of a pointer variable that receives the address of an IAccessible interface for either the object that generated the event or for the parent of the element that generated the event.

pvarChild

[in] Pointer to the event hook function. For more information about this function, see WinEventProc Callback Procedure.

idProcess

[in] Specifies the ID of the process from which the hook function receives events. Specify zero (0) to receive events from all processes.

idThread

[in] Specifies the ID of the thread from which the hook function receives events. If this parameter is zero, the hook function is associated with all existing threads.

dwFlags

[in] Flag values that specify the location of the hook function and events to skip. The following flags are valid:

WINEVENT_INCONTEXT

The DLL that contains the callback function is mapped into the address space of the process that generates the event. With this flag, the system sends event notifications to the callback function as they occur. The hook function must be in a DLL when this flag is specified. This flag has no effect when the calling process and the generating process are not both 32-bit processes or both 64-bit processes, or when the generating process is a console application.

WINEVENT_OUTOFCONTEXT

The callback function is not mapped into the address space of the process that generates the event. Because the hook function is called across process boundaries, the system must queue events. Although this method is asynchronous, events are guaranteed to be in sequential order.

WINEVENT_SKIPOWNPROCESS

Prevents this instance of the hook from receiving events generated by threads in this process. This flag does not prevent threads from generating events.

WINEVENT_SKIPOWNTHREAD

Prevents this instance of the hook from receiving events generated by the thread that is registering this hook.

The following flag combinations are valid:

* WINEVENT_INCONTEXT OR WINEVENT_SKIPOWNPROCESS

* WINEVENT_INCONTEXT OR WINEVENT_SKIPOWNTHREAD

* WINEVENT_OUTOFCONTEXT OR WINEVENT_SKIPOWNPROCESS

* WINEVENT_OUTOFCONTEXT OR WINEVENT_SKIPOWNTHREAD

Additionally, client applications can specify WINEVENT_INCONTEXT, or WINEVENT_OUTOFCONTEXT alone.

Return Values

If successful, returns an HWINEVENTHOOK value that identifies this event hook instance. Applications save this return value to use with the UnhookWinEvent function.

If unsuccessful, returns zero.

Remarks

This function allows clients to specify which processes and threads they are interested in.

If the idProcess parameter is non-zero and idThread is zero, the hook function receives the specified events from all threads in that process. If the idProcess parameter is zero and idThread is non-zero, the hook function receives the specified events only from the thread specified by idThread. If both are zero, the hook function receives the specified events from all threads and processes.

Clients can call SetWinEventHook multiple times if they want to register additional hook functions or listen for additional events.

The client thread that calls SetWinEventHook must have a message loop in order to receive events.

When you use SetWinEventHook to set a callback in managed code, you should use the GCHandle Structure to avoid exceptions. This tells the garbage collector not to move the callback.

Example

The follow example code shows how a client application might listen for menu-start and menu-end events. For simplicity, the event handler just sends some information to the standard output.

[C++]

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

  }

}

[PowerBASIC]

' // Global variable.

g_hook AS DWORD

' // Initializes COM and sets up the event hook.

' //

SUB InitializeMSAA()

  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 OR %WINEVENT_SKIPOWNPROCESS) ' // Flags.

END SUB

' // Unhooks the event and shuts down COM.

' //

SUB ShutdownMSAA()

 UnhookWinEvent(g_hook)

END SUB

' // Callback function that handles events.

' //

SUB HandleWinEvent(BYVAL hook AS DWORD, _

                 BYVAL dwEvent AS DWORD, _

                 BYVAL hwnd AS DWORD, _

                 BYVAL idObject AS LONG, _

                 BYVAL idChild AS LONG, _

                 BYVAL dwEventThread AS DWORD, _

                 BYVAL dwmsEventTime AS DWORD)

 LOCAL pAcc AS IAccessible

 LOCAL varChild AS VARIANT

 LOCAL hr AS LONG

 hr = AccessibleObjectFromEvent(hwnd, idObject, _

      idChild, pAcc, varChild)

 IF hr = %S_OK AND ISOBJECT(pAcc) THEN

    LOCAL bstrName AS STRING

    bstrName = pAcc.accName(varChild)

    IF dwRvent = %EVENT_SYSTEM_MENUSTART THEN

       PRINT "Begin: "

    ELSEIF dwEent = %EVENT_SYSTEM_MENUEND THEN

       PRINT "End:   "

    END IF

    PRINT ACODE$(bstrName)

    pAcc = NOTHING

 END IF

END SUB