Array Manipulation Functions

The arrays passed by IDispatch::Invoke within VARIANTARG are called safearrays. A safearray contains 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.

In this section

Topic Description
SafeArrayAccessData
Increments the lock count of an array, and retrieves a pointer to the array data.
SafeArrayAddRef
Increases the pinning reference count of the descriptor for the specified safe array by one, and may increase the pinning reference count of the data for the specified safe array by one if that data was dynamically allocated, as determined by the descriptor of the safe array.
SafeArrayAllocData
Allocates memory for a safe array, based on a descriptor created with SafeArrayAllocDescriptor.
SafeArrayAllocDescriptor
Allocates memory for a safe array descriptor.
SafeArrayAllocDescriptorEx
Creates a safe array descriptor for an array of any valid variant type, including VT_RECORD, without allocating the array data.
SafeArrayCopy
Creates a copy of an existing safe array.
SafeArrayCopyData
Copies the source array to the specified target array after releasing any resources in the target array.
SafeArrayCreate
Creates a new array descriptor, allocates and initializes the data for the array, and returns a pointer to the new array descriptor.
SafeArrayCreateEx
Creates and returns a safe array descriptor from the specified VARTYPE, number of dimensions and bounds.
SafeArrayCreateVector
Creates a one-dimensional array. A safe array created with SafeArrayCreateVector is a fixed size, so the constant FADF_FIXEDSIZE is always set.
SafeArrayCreateVectorEx
Creates and returns a one-dimensional safe array of the specified VARTYPE and bounds.
SafeArrayDestroy
Destroys an existing array descriptor and all of the data in the array.
SafeArrayDestroyData
Destroys all the data in the specified safe array.
SafeArrayDestroyDescriptor
Destroys the descriptor of the specified safe array.
SafeArrayGetDim
Gets the number of dimensions in the array.
SafeArrayGetElement
Retrieves a single element of the array.
SafeArrayGetElemsize
Gets the size of an element.
SafeArrayGetIID
Gets the GUID of the interface contained within the specified safe array.
SafeArrayGetLBound
Gets the lower bound for any dimension of the specified safe array.
SafeArrayGetRecordInfo
Retrieves the IRecordInfo interface of the UDT contained in the specified safe array.
SafeArrayGetUBound
Gets the upper bound for any dimension of the specified safe array.
SafeArrayGetVartype
Gets the VARTYPE stored in the specified safe array.
SafeArrayLock
Increments the lock count of an array, and places a pointer to the array data in pvData of the array descriptor.
SafeArrayPtrOfIndex
Gets a pointer to an array element.
SafeArrayPutElement
Stores the data element at the specified location in the array.
SafeArrayRedim
Changes the right-most (least significant) bound of the specified safe array.
SafeArrayReleaseData
Decreases the pinning reference count for the specified safe array data by one. When that count reaches 0, the memory for that data is no longer prevented from being freed.
SafeArrayReleaseDescriptor
Decreases the pinning reference count for the descriptor of the specified safe array by one. When that count reaches 0, the memory for that descriptor is no longer prevented from being freed.
SafeArraySetIID
Sets the GUID of the interface for the specified safe array.
SafeArraySetRecordInfo
Sets the record info in the specified safe array.
SafeArrayUnaccessData
Decrements the lock count of an array, and invalidates the pointer retrieved by SafeArrayAccessData.
SafeArrayUnlock
Decrements the lock count of an array so it can be freed or resized.
SAFEARRAY
Represents a safe array.
SAFEARRAYBOUND
Represents the bounds of one dimension of the array.

Conversion and Manipulation Functions

SAFEARRAY Data Type

SAFEARRAYBOUND Structure