Admin Production ni-theme
Current Publication

CA_VariantGet2DArray

LabWindows/CVI

CA_VariantGet2DArray

HRESULT CA_VariantGet2DArray (VARIANT *variant, unsigned int arrayType, void *array, size_t *sizeOf1stDimension, size_t *sizeOf2ndDimension);

Purpose

Converts a 2D safe array in a variant parameter into a dynamically allocated C-style array.

Upon success, CA_VariantGet2DArray frees the contents of the variant parameter and marks it as empty.

Use CA_FreeMemory to free the returned array.

Example Code

The following code shows you how to use CA_VariantGet2Darray:

double * dblArray = NULL;
VARIANT variant;
unsigned numElemsDim1, numElemsDim2;
int index1, index2;
/* Call an ActiveX function that returns a safe array in a Variant. */
.
.
.
/* Convert the safe array the variant contains into a C-style array. */

HRESULT CA_VariantGet2DArray(&variant, CAVT_DOUBLE, &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);
}

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

Parameters

Input
Name Type Description
arrayType unsigned int Data type of the array that CA_VariantGet2DArray 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 contain any of the fundamental data types for variants, safe arrays, and properties except CAVT_EMPTY or CAVT_NULL.

CA_VariantGet2Darray ignores the CAVT_ARRAY modifier.

If you do not know the type of the array, you can call CA_VariantGetType and pass its return value as the arrayType.
Output
Name Type Description
variant VARIANT Pointer to a variant that contains a 2D safe array.

CA_VariantGet2DArray frees the contents of the variant contents and marks it as empty.
array void * C-style array that CA_VariantGet2DArray dynamically allocates. The type of the array must be the same as arrayType. Pass the address of an array pointer.

To access the elements of array, use the CA_Get2DArrayElement macro, which is declared in cviauto.h.

When you no longer need the C-style array, call CA_FreeMemory to discard it. 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
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

Name Type Description
status HRESULT A value indicating whether an error occurred. Negative error codes indicate function failure.

Error codes are defined in CVIversion\include\cviauto.h and <Program Files>\National Instruments\Shared\MSDTRedistributables\SDKHeaderFiles\8.1\winerror.h. The LabWindows/CVI ActiveX Library explicitly returns error codes. Other error codes in winerror.h are generated by ActiveX servers and passed on to you by the LabWindows/CVI ActiveX Library.

You can use CA_GetAutomationErrorString to get the description of an error code or CA_DisplayErrorInfo to display the description of the error code.

Additional Information

Library: ActiveX Library

Include file: cviauto.h

LabWindows/CVI compatibility: LabWindows/CVI 5.0 and later