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.
Clients
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.
| Method | Description |
|---|---|
| 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. |
Providers
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