AccessibleObjectFromEvent

[This is preliminary documentation and subject to change.]

Retrieves the address of the IAccessible interface for an object that generated a given event.

STDAPI AccessibleObjectFromEvent(
  HWND hwnd,
  DWORD dwId,
  DWORD dwChildId,
  IAccessible** ppacc,
  VARIANT* pvarChild
);

Parameters

hwnd: Handle to the window that generated the event.
dwId: Object ID. This value can be one of the standard object identifier constants or a custom object ID.
dwChildId: ID of the child element that triggered the event, or CHILDID_SELF if the object itself triggered the event.
ppacc: Address of a variable that will contain the address of the child object's IAccessible interface if the child is an accessible object. If not, this is the address of the IAccessible interface of the child's parent object. See the description for the pvarChild parameter for information about which interface is returned.
pvarChild: Address of a VARIANT structure that will contain information describing the call's result. The vt member will always be set to VT_I4. If the lVal member is set to zero, then the IAccessible interface pointer at ppacc belongs to the child object specified in dwChildId. Otherwise, ppacc is the address of the IAccessible interface of the child's parent object.

Return Values

Returns S_OK if successful or a standard COM error code otherwise. When the idObject parameter identifies a system object, oleacc.dll checks for a valid idChild value. However, if the object identified by the idObject parameter is not a system object, the server is responsible for returning failure when the idChild parameter is invalid.

Clients call this function to retrieve a specific child object that generated an event. The client uses the parameters sent to its WinEventProc callback function to fill this function's parameters.

Remarks

This function retrieves the lowest-level accessible object that is associated with an event. If the child that generated the event is not an accessible object (that is, does not support IAccessible), then the function returns that child's parent. The parent is assumed to support the functionality extended by the IAccessible interface on the child's behalf.

This function increases an object's reference count, and must have a corresponding call to Release. Even though an object has a reference count greater than zero, that object can still be destroyed, and clients are not guaranteed that getting properties from or calling methods on an object will succeed. This is what Microsoft® Word does with its objects when it shuts down: As with standard OLE Automation objects, Word will quit and CoDisconnect the object so that if anyone tries to access it cross-process after the quit, OLE will return an error. A reference count on a OLE Automation object does not affect the reference count in the application.