CA_SafeArrayTo2DArrayBufEx
HRESULT CA_SafeArrayTo2DArrayBufEx (LPSAFEARRAY *safeArray, unsigned int arrayType, unsigned int options, void *arrayBuffer, size_t bufferSizeInBytes, size_t *sizeOf1stDimension, size_t *sizeOf2ndDimension);
Purpose
Converts a 2D safe array into a C-style array that you pass as a buffer.
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.
CA_SafeArrayTo2DArrayBufEx returns an error if the buffer is not big enough to hold the array.
Example Code
double dblArray[1024];
LPSAFEARRAY safeArray;
unsigned dim1Size, dim2Size;
int index1, index2;
/* Call an ActiveX function that */
/* returns Safe Array. */
...
/* Convert the Safe Array into a C-style array */
CA_SafeArrayTo2DArrayBufEx(&safeArray, CAVT_DOUBLE, 0, dblArray, sizeof(dblArray), &dim1Size, &dim2Size);
for (index1 = 0; index1 < dim1Size; index1++)
for (index2 = 0; index2 < dim2Size; index2++)
{
double d;
d = CA_Get2DArrayElement(dblArray, dim1Size, dim2Size,
index1, index2, double);
printf("%f", d);
}
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.
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. |
||||||||||||||||
| bufferSizeInBytes | size_t | The size, in bytes, of arrayBuffer. | ||||||||||||||||
| Output | ||||||||||||||||||
| Name | Type | Description | ||||||||||||||||
| safeArray | LPSAFEARRAY | A 2D 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. |
||||||||||||||||
| arrayBuffer | void * | The buffer in which the array elements are stored. You can use the CA_Get2DArrayElement macro to access elements of this array. 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.
|
||||||||||||||||
| sizeOf1stDimension | size_t | The number of elements in the first dimension of the array in arrayBuffer. You can pass NULL for this parameter. |
||||||||||||||||
| sizeOf2ndDimension | size_t | The number of elements in the second dimension of the array in arrayBuffer. 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.5 and later