[This is preliminary documentation and subject to change.]
The WinEventProc callback function is the starting point for most client activity. Active Accessibility calls this hook procedure in response to specific ranges of events that server applications generate. You specify which events a hook procedure is called for when you register it with the SetWinEventHook function.
WinEventProc receives seven parameters. The first, hWinEventHook, is an identifier for the hook procedure, and is provided for reference—you won't usually do anything with it. The second parameter, event, is one of the event constants that describes the type of event that occurred. The next three parameters, hwnd, idObject, and idChild, combine to tell you about the window, object, and possible child element that generated the event. The following table provides additional explanation for these three parameters.
| Parameter name | Description |
|---|---|
| hwnd | Handle to the window where the event originated. |
| idObject | Object identifier of the object associated with the event. This is one of the object constants, and is set to OBJID_WINDOW if the window itself generated the event. |
| idChild | Identifier of the child element that generated the event. This is CHILDID_SELF if no child element generated the event. |
Generally, a client does little more with these three parameters than use them in an object retrieval call, such as the AccessibleObjectFromEvent function. For more information about identifiers, see Object and Child Identifiers.
The remaining two parameters, idEventThread and dwmsEventTime, provide background information about the thread associated with the event and the time the event occurred.
In-context and Out-of-context Hook Procedures
There are two types of hook procedures, in-context and out-of-context. These terms describe the WinEventProc callback function's memory location relative to the server's address space. An in-context hook procedure is located in a dynamic-link library (DLL) that Active Accessibility maps into the server's address space. Similarly, an out-of-context hook procedure is located in the client's address space, whether it's in the code body or in a DLL.
In-context callbacks receive event notifications synchronously from the server, while out-of-context callbacks receive asynchronous event notifications. As a result, in-context callbacks tend to be very fast, since processing occurs in the server's address space, requiring no marshaling across process boundaries. NOTE: For greatest performance, use In-Context Event Notification and access object properties within the same address space of the object. When using in-context callbacks, client developers must ensure that the provided function doesn't use a lot of processor time, since the server must wait for the callback to return before it can continue.
Since out-of-context callbacks aren't mapped into the server's address space, Active Accessibility marshals across process boundaries, making event notifications asynchronous and causing responses noticeably slower than in-context callbacks. Although the event notifications are asynchronous, Active Accessibility assures that the callback function receives all events in the order they were generated.
Multiple Hook Procedures
You can register multiple hooks to respond to various ranges of events. Therefore, the callback function's label doesn't necessarily need to be "WinEventProc"—it can be anything you want, so long as its argument list and return value are identical to the function declaration for the WinEventProc function.