Array Manipulation Functions [Automation]
The arrays passed by IDispatch::Invoke 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 functions SafeArrayAccessData and SafeArrayUnaccessData 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 a programming language syntax) changes first.
The following table contains the functions you use when accessing the data in the descriptor and the array:
Array Manipulation Function
Increments the lock count of an array and returns a pointer to array data.
Allocates memory for a safearray based on a descriptor created with SafeArrayAllocDescriptor.
Allocates memory for a safearray descriptor.
Allocates a safearray descriptor for an array of records of given dimensions.
Copies an existing array.
Copies a source array to a target array after releasing source resources.
Creates a new array descriptor.
Creates and returns a safearray descriptor of the given VARTYPE, number of dimensions and bounds.
Creates a one-dimensional array whose lower bound is always zero.
Creates and returns a one-dimensional safearray of the specified VARTYPE and bounds.
Destroys an array descriptor.
Frees memory used by the data elements in a safearray.
Frees memory used by a safearray descriptor.
Returns the number of dimensions in an array.
Returns an element.
Returns the size of an element.
Returns the GUID of the interface for the given safearray.
Retrieves the lower bound for a given dimension.
Retrieves the upper bound for a given dimension.
Returns the IRecordInfo pointer for the given safearray.
Returns the type stored in the given safearray.
Increments the lock count of an array.
Returns a pointer to an array element.
Assigns an element into an array.
Resizes a safearray.
Sets the GUID of the interface for the given safearray.
Sets the IRecordInfo stored in the given safearray.
Frees a pointer to array data and decrements the lock count of the array.
Decrements the lock count of an array.