CA_SafeArrayTo1DArrayEx

HRESULT CA_SafeArrayTo1DArrayEx (LPSAFEARRAY *safeArray, unsigned int arrayType, unsigned int options, void *array, size_t *numberOfElements);

Purpose

Converts a 1D safe array into a dynamically allocated C-style array.

This function frees the safe array and its contents and sets the safe array pointer to NULL unless you pass the CVIAUTO_RETAIN_SAFEARRAY flag in the options parameter.

Example Code

double * dblArray = NULL;
LPSAFEARRAY safeArray;
unsigned numElements;
int index;
/* Call an ActiveX function that */
/* returns a Safe Array. */
...
/* Convert the Safe Array into a C-style array */

CA_SafeArrayTo1DArrayEx (&safeArray, CAVT_DOUBLE, 0, &dblArray, &numElements);

for (index = 0; index < numElements; index++)

printf ("%f", dblArray[index]);

/* Free the allocated array */
CA_FreeMemory (dblArray);

Parameters

Input
Name	Type	Description
arrayType	unsigned int	The type of array to be created from the safe array. The type of the C-style array must be the same as the type of the safe array except for the following cases. Creating a char* array from a BSTR SAFEARRAY. Creating a CAObjHandle array from an LPDISPATCH SAFEARRAY. If you do not know the type of the array, you can call CA_VariantGetType and pass its return value as the type. arrayType can contain any of the fundamental data types for variants, safe arrays, and properties except for CAVT_EMPTY or CAVT_NULL. The CAVT_ARRAY flag is ignored by this parameter.
options	unsigned int	The option constants to modify the behavior of the safe array conversion function. Pass 0 for the default behavior. Pass CVIAUTO_RETAIN_SAFEARRAY to retain the safe array and its contents. The default behavior is to free the safe array and its contents on function success and set the safe array pointer to NULL.
Output
Name	Type	Description
safeArray	LPSAFEARRAY	A 1D safe array. On success, this function frees the safe array and its contents and sets the safe array pointer to NULL unless you pass the CVIAUTO_RETAIN_SAFEARRAY flag in the options parameter.
array	void *	The 1D C-style array allocated by this function. Pass the address of a pointer variable. This array can be treated as like other 1D C arrays. Call CA_FreeMemory on the array to discard it when it is no longer needed. If the array contains elements of one of the data types in the following table, use the corresponding function to free each element when you no longer need it. Data Type Function to Free Each Element char * CA_FreeMemory CAObjHandle CA_DiscardObjHandle BSTR CA_FreeBSTR LPUNKNOWN array[i]->lpVtbl->Release() LPDISPATCH array[i]->lpVtbl->Release() VARIANT CA_VariantClear Note   CAObjHandles created by CA_SafeArrayTo1DArrayEx do not support multithreading and use LOCALE_NEUTRAL. To use different values for multithreading support and locale you can call CA_SetSupportForMultithreading and CA_SetLocale to specify the desired values for each CAObjHandle.
numberOfElements	size_t	The number of elements in array. You can pass NULL for this parameter.

Return Value

Additional Information

Library: ActiveX Library

Include file: cviauto.h

LabWindows/CVI compatibility: LabWindows/CVI 5.5 and later