CA_SafeArrayTo1DArray
HRESULT CA_SafeArrayTo1DArray (LPSAFEARRAY *safeArray, unsigned int arrayType, void *array, size_t *numberOfElements);
Purpose
 |
Note This function has been superseded by CA_SafeArrayTo1DArrayEx. The new function takes an additional parameter for options. Calling CA_SafeArrayTo1DArray is equivalent to passing 0 for the options parameter with CA_SafeArrayTo1DArrayEx. |
Converts a 1D safe array into a dynamically allocated C-style array.
Upon success, CA_SafeArrayTo1DArray frees the safe array and its contents and sets the safe array pointer to NULL.
Example Code
The following code shows you how to use CA_SafeArrayTo1Darray:
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_SafeArrayTo1DArray (&safeArray, CAVT_DOUBLE, &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 | Data type of the array that CA_SafeArrayTo1DArray creates from the safe array. arrayType must be the same as the type of the safe array except for the following cases:
arrayType can be any of the fundamental data types for variants, safe arrays, and properties except CAVT_EMPTY or CAVT_NULL. CA_SafeArrayTo1DArray ignores the CAVT_ARRAY modifier. |
||||||||||||||||
| Output | ||||||||||||||||||
| Name | Type | Description | ||||||||||||||||
| safeArray | LPSAFEARRAY | 1D safe array. Pass the address of the safe array pointer. CA_SafeArrayTo1DArray frees the safe array and its contents and sets the safe array pointer to NULL. |
||||||||||||||||
| array | void * | 1D C-style array that CA_SafeArrayTo1DArray dynamically allocates. The type of the array must be the same as arrayType. Pass the address of an array pointer. 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.
|
||||||||||||||||
| numberOfElements | size_t | Number of elements in 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