Windows apps
Collapse the table of content
Expand the table of content
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Best Practices for Using Safe Arrays

Many interface methods of the Microsoft UI Automation API take arguments called safe arrays, of the SAFEARRAY data type. This topic describes the best practices for using safe arrays in a UI Automation applications.


All safe arrays that are used with the UI Automation client API methods are zero-based, one-dimensional arrays. To create a safe array for a UI Automation client method, use the SafeArrayCreateVector function, and to read from and write to a safe array, use the SafeArrayGetElement and SafeArrayPutElement functions. When you finish using a safe array, always destroy it by using the SafeArrayDestroy function, whether you created the safe array or received it from a UI Automation client method.

Several UI Automation methods, including property-retrieval methods such as GetCurrentPropertyValue, retrieve VARIANTs that can contain POINT or UiaRect structures. A POINT is packed into a VARIANT as a safe array of doubles (VT_R8) with the x member at index 0, and the y member at index 1. Similarly, a UiaRect is packed into a VARIANT as a safe array of doubles with the left, top, width, and height members at indexes 0 through 3, respectively. For an array of UiaRect structures, the safe array contains a sequential array of four doubles for each UiaRect. The left, top, width, and height members of the first UiaRect occupy index 0 through 3, the members of the second rectangle occupy index 4 through 7, and so on.

The IUIAutomation interface includes the following methods for converting between SAFEARRAY and various other data types.

IUIAutomation::IntNativeArrayToSafeArray Converts an array of integers to a SAFEARRAY.
IUIAutomation::IntSafeArrayToNativeArray Converts a SAFEARRAY of integers to an array.
IUIAutomation::SafeArrayToRectNativeArray Converts a SAFEARRAY that contains rectangle coordinates to an array of type RECT.



A provider must implement a number of interface methods that UI Automation calls to retrieve information from the provider. Many times, this information consists of an array of values. To return an array to UI Automation, the provider must pack the array into a SAFEARRAY structure. The array elements must be of the expected data type, and must appear in the expected order.

Related topics

UI Automation Properties Overview
UI Automation Fundamentals



© 2018 Microsoft