UiaReturnRawElementProvider Function

Gets an interface to the UI Automation provider for a window.

Syntax

LRESULT UiaReturnRawElementProvider(      
    HWND hwnd,
    WPARAM wparam,
    LPARAM lparam,
    IRawElementProviderSimple *el
);

Parameters

• hwnd
  [in] The window containing the element served by the provider.
• wparam
  [in] The WPARAM argument of the WM_GETOBJECT message.
• lparam
  [in] The LPARAM argument of the WM_GETOBJECT message. If this is not UiaRootObjectId, the function returns 0.
• el
  [out] The address of the IRawElementProviderSimple interface of the UI Automation provider.

Return Value

The key for the client process to connect to the server process through Microsoft UI Automation.

This function returns zero when it is used to notify UI Automation that it is safe to remove the provider raised-event map. For more information, see Remarks.

Remarks

This function is called by a control when it receives the WM_GETOBJECT message, to provide UI Automation with the UI Automation provider for the control. The control's window procedure should return the result of this function.

When Microsoft Active Accessibility clients are listening to events raised by a UI Automation provider, UI Automation maintains a map of the providers that have raised events. When the Microsoft Active Accessibility clients request further information, UI Automation uses the map to route the requests to the appropriate providers. When a window that previously returned providers has been destroyed, you should notify UI Automation by calling the UiaReturnRawElementProvider as follows: UiaReturnRawElementProvider(hwnd, 0, 0, NULL). This call tells UI Automation that it can safely remove all map entries that refer to the specified window. This call can save memory because it releases references to the providers being held by the raised-event map. The function returns zero when called with these special parameters. Microsoft recommends making this call from the WM_DESTROY message handler of the window that returns the UI Automation providers.

Function Information

Stock Implementation	uiautomationcore.dll
Custom Implementation	No
Header	uiautomationcoreapi.h
Import library	uiautomationcore.lib
Minimum operating systems	Windows XP