CA_SafeArrayTo2DArrayBuf

HRESULT CA_SafeArrayTo2DArrayBuf (LPSAFEARRAY *safeArray, unsigned int arrayType, void *arrayBuffer, size_t bufferSizeInBytes, size_t *sizeOf1stDimension, size_t *sizeOf2ndDimension);

Purpose

Note    This function has been superseded by CA_SafeArrayTo2DArrayBufEx. The new function takes an additional parameter for options. Calling CA_SafeArrayTo2DArrayBuf is equivalent to passing 0 for the options parameter with CA_SafeArrayTo2DArrayBufEx.

Converts a 2D safe array into a C-style array you pass as a buffer.

Upon success, CA_SafeArrayTo2DArrayBuf frees the safe array and its contents and sets the safe array pointer to NULL.

CA_SafeArrayTo2DArrayBuf returns an error if the buffer is not big enough to hold the array.

Example Code

The following code shows you how to use CA_SafeArrayTo2DArrayBuf:

double dblArray[1024];
LPSAFEARRAY safeArray;
unsigned numElemsDim1, numElemsDim2;
int index1, index2;
/* Call an ActiveX function that returns a safe array. */
.
.
.
/* Convert the safe array into a C-style array. */

CA_SafeArrayTo2DArrayBuf (&safeArray, CAVT_DOUBLE, dblArray, sizeof(dblArray), &numElemsDim1, &numElemsDim2);

for (index1 = 0; index1 < numElemsDim1; index1++)

for (index2 = 0; index2 < numElemsDim2; index2++)

{
double d;
d = CA_Get2DArrayElement (dblArray, numElemsDim1, numElemsDim2, index1, index2, double);
printf ("%f", d);
}

Parameters

Input
Name	Type	Description
arrayType	unsigned int	Data type of the array that CA_SafeArrayTo2DArrayBuf creates from the safe array. arrayType must be the same as the type of the safe array except for the following cases: Creating a C-style array that contains char* elements from a BSTR safe array. Creating a C-style array that contains CAObjHandle elements from an LPDISPATCH safe array. arrayType can be any of the fundamental data types for variants, safe arrays, and properties except CAVT_EMPTY or CAVT_NULL. CA_SafeArrayTo2DArrayBuf ignores the CAVT_ARRAY modifier.
bufferSizeInBytes	size_t	Number of bytes in the arrayBuffer parameter.
Output
Name	Type	Description
safeArray	LPSAFEARRAY	2D safe array. Pass the address of the safe array pointer. CA_SafeArrayTo2DArrayBuf frees the safe array and its contents and sets the safe array pointer to NULL.
arrayBuffer	void *	Buffer to receive the C-style array elements. The type of the array must be the same as arrayType. To access the elements of array, use the CA_Get2DArrayElement macro, which is declared in cviauto.h. If the C-style 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 that this function creates 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.
sizeOf1stDimension	size_t	Number of elements in the first dimension of array. You can pass NULL for this parameter.
sizeOf2ndDimension	size_t	Number of elements in the second dimension of 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.0 and later