Array Manipulation Functions
The arrays passed by the IDispatch::Invoke interface within VARIANTARGs are called SAFEARRAYs. SAFEARRAYs contain information about the number of dimensions and bounds within them. When an array is an argument or the return value of a function, the parray field of VARIANTARG points to an array descriptor. Do not access this array descriptor directly, unless you are creating arrays containing elements with nonvariant data types. Instead, use the SafeArrayAccessData and SafeArrayUnaccessData functions to access the data.
The base type of the array is indicated by VT_ tag | VT_ARRAY. The data referenced by an array descriptor is stored in column-major order, which is the same ordering scheme used by Visual Basic and Fortran, but different from C and Pascal. Column-major order is when the left-most dimension, as specified in programming language syntax, changes first.
The following table shows the functions to use when accessing the data in the descriptor and the array.
| Array manipulation function | Description |
|---|---|
| SafeArrayAccessData | Increments the lock count of an array and returns a pointer to array data. |
| SafeArrayAllocData | Allocates memory for a SAFEARRAY based on a descriptor created with SafeArrayAllocDescriptor. |
| SafeArrayAllocDescriptor | Allocates memory for a SAFEARRAY descriptor. |
| SafeArrayCopy | Copies an existing array. |
| SafeArrayCopyData | Copies a source array to a target array after releasing source resources. |
| SafeArrayCreate | Creates a new array descriptor. |
| SafeArrayCreateVector | Creates a one-dimensional array whose lower bound is always zero. |
| SafeArrayDestroy | Destroys an array descriptor. |
| SafeArrayDestroyData | Frees memory used by the data elements in a SAFEARRAY. |
| SafeArrayDestroyDescriptor | Frees memory used by a SAFEARRAY descriptor. |
| SafeArrayGetDim | Returns the number of dimensions in an array. |
| SafeArrayGetElemsize | Returns the size of an element. |
| SafeArrayGetLBound | Retrieves the lower bound for a given dimension. |
| SafeArrayGetUBound | Retrieves the upper bound for a given dimension. |
| SafeArrayLock | Increments the lock count of an array. |
| SafeArrayPtrOfIndex | Returns a pointer to an array element. |
| SafeArrayPutElement | Assigns an element to an array. |
| SafeArrayRedim | Resizes a SAFEARRAY. |
| SafeArrayUnaccessData | Frees a pointer to array data and decrements the lock count of the array. |
| SafeArrayUnlock | Decrements the lock count of an array. |
Last updated on Wednesday, April 13, 2005
© 2005 Microsoft Corporation. All rights reserved.