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. |