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

TopicDescription

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.

 

Related topics

Conversion and Manipulation Functions
SAFEARRAY Data Type
SAFEARRAYBOUND Structure

 

 

Show: