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