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

Descriptions

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.

SafeArrayAllocDescriptorEx

Allocates a safearray descriptor for an array of records of given dimensions.

SafeArrayCopy

Copies an existing array.

SafeArrayCopyData

Copies a source array to a target array after releasing source resources.

SafeArrayCreate

Creates a new array descriptor.

SafeArrayCreateEx

Creates and returns a safearray descriptor of the given VARTYPE, number of dimensions and bounds.

SafeArrayCreateVector

Creates a one-dimensional array whose lower bound is always zero.

SafeArrayCreateVectorEx

Creates and returns a one-dimensional safearray of the specified VARTYPE and bounds.

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.

SafeArrayGetElement

Returns an element.

SafeArrayGetElemsize

Returns the size of an element.

SafeArrayGetIID

Returns the GUID of the interface for the given safearray.

SafeArrayGetLBound

Retrieves the lower bound for a given dimension.

SafeArrayGetUBound

Retrieves the upper bound for a given dimension.

SafeArrayGetRecordInfo

Returns the IRecordInfo pointer for the given safearray.

SafeArrayGetVartype

Returns the type stored in the given safearray.

SafeArrayLock

Increments the lock count of an array.

SafeArrayPtrOfIndex

Returns a pointer to an array element.

SafeArrayPutElement

Assigns an element into an array.

SafeArrayRedim

Resizes a safearray.

SafeArraySetIID

Sets the GUID of the interface for the given safearray.

SafeArraySetRecordInfo

Sets the IRecordInfo stored in the given safearray.

SafeArrayUnaccessData

Frees a pointer to array data and decrements the lock count of the array.

SafeArrayUnlock

Decrements the lock count of an array.

Show:
© 2014 Microsoft