DS_GetAttrValue

Download PDF

Updated2023-02-21
5 minute(s) read

HRESULT DS_GetAttrValue (DSHandle DSHandle, const char *attributeName, unsigned int type, void *value, unsigned int size, unsigned int *dimension1, unsigned int *dimension2);

Purpose

Returns the data value of a DataSocket object attribute.

This function is a convenience function that performs, in a single operation, the same task as calling DS_GetAttrHandle to obtain a handle to an attribute and then calling DS_GetDataValue to get the data value of the attribute.

The data value of a DataSocket attribute object might not be the same as the current data value of the DataSocket data source to which the DataSocket object is connected. The DataSocket object obtains the DataSocket data source's attribute data value at the time that the connection is made, depending on how the DataSocket object is configured. If the DataSocket object is configured for ReadAutoUpdate mode, the DataSocket object obtains the DataSocket data source's attribute data value each time it changes. If the DataSocket object is configured for Read mode, the DataSocket object obtains the DataSocket data source's attribute data value each time you call DS_Update.

Note If the execution model of your DataSocket object is the 'Event Model', it is highly recommended that you call this function in your DataSocket callback function in response to DS_EVENT_DATAUPDATED events. Otherwise, you will only get the latest data and may lose intermediate data.

Parameters

Input

Name Type Description

DSHandle DSHandle Pass the handle you obtained from DS_Open, DS_GetAttrHandle, or DS_CreateAttrHandle to identify the DataSocket object.

attributeName const char * A string to specify the name of the attribute. If the attribute does not exist, this function returns E_INVALIDARG (0x80070057).

type

unsigned int

A constant to indicate the type of the attribute's data value. The attribute's data value can be one of the valid types or an array of one of the valid types other than CAVT_VARIANT. The following table lists the valid type constants and their corresponding C/Windows types:

Constant	C/Windows type
CAVT_DOUBLE	double
CAVT_FLOAT	float
CAVT_LONG	long
CAVT_SHORT	short
CAVT_UCHAR	unsigned char
CAVT_CSTRING	char *
CAVT_BOOL	short
CAVT_VARIANT	VARIANT

To specify an array type, combine the CAVT_ARRAY flag with one of the preceding data types (other than CAVT_VARIANT) using the bitwise OR operator (|). For example, to indicate an array of long values, pass CAVT_LONG | CAVT_ARRAY.

Press <Ctrl-T> to change this parameter's ring control to a manual input box.

size unsigned int The size, in bytes, of the buffer you pass in the value parameter if the constant you pass in the type parameter indicates an array or a string.

If the constant you pass in the type parameter indicates a scalar, this parameter is meaningless.

Output

Name Type Description

value

void *

The address of a variable to hold the data value if the constant you pass in the type parameter does not indicate an array or a string, that is, the constant is a scalar.

Some servers support non-Automation types, such as unsigned short and unsigned long. In this case, if you pass CAVT_VARIANT for the type parameter and the address of an empty VARIANT variable in the Value parameter, this function returns the data in the variant.

If the type you pass is a string or an array, you must allocate and pass a buffer that is large enough to hold all of the data. This function copies the data into the buffer that you pass.

If the type you pass is an array of strings, you must allocate an array of pointers (of type char *) that is large enough to hold all of the strings in the array. This function allocates memory for each string and stores pointers to that memory in the array that you pass. You must call DS_FreeMemory to free each of these strings.

Example

Example of scalar of type double
double value;
DS_GetAttrValue (dsHandle, "Attribute1", CAVT_DOUBLE, &value, 0, 0, 0);

Example of string
unsigned int size;
char *value;
DS_GetAttrType (dsHandle, "Attribute1", NULL, &size, NULL);
value = malloc (size+1);
DS_GetAttrValue (dsHandle, "Attribute1", CAVT_CSTRING, value, size+1, 0, 0);
// Free the memory
free (value);

Example of 1D array of doubles
unsigned int size;
double *value;
DS_GetAttrType (dsHandle, "Attribute1", NULL, &size, NULL);
value = malloc (size * sizeof (double));
DS_GetAttrValue (dsHandle, "Attribute1", CAVT_DOUBLE | CAVT_ARRAY, value, size * sizeof(double), 0, 0);
// Free the memory
free (value);

Example of 1D array of strings
unsigned int size, n;
char **value;
DS_GetAttrType (dsHandle, "Attribute1", NULL, &size, NULL);
value = malloc (size * sizeof (char *));
DS_GetAttrValue (dsHandle, "Attribute1", CAVT_CSTRING | CAVT_ARRAY, value, size * sizeof(char *), 0, 0);
// Free the strings
for (n = 0; n < size; n++)
DS_FreeMemory (value[n]);
// Free the array
free (value);

Example of 2D array of doubles
unsigned int size1, size2;
double *value;
DS_GetAttrType (dsHandle, "Attribute1", NULL, &size1, &size2);
value = malloc (size1 * size2 * sizeof (double));
DS_GetAttrValue (dsHandle, "Attribute1", CAVT_DOUBLE | CAVT_ARRAY, value, size1*size2*sizeof(double), size1, size2);
// Free the memory
free (value);

dimension1 unsigned int Returns the length of the string if the constant you pass in the type parameter is CAVT_CSTRING. The length does not include the terminating NUL byte.

Returns the number of elements in the array if the constant you pass in the type parameter indicates a 1D array of any type.

Returns the size of the first dimension of the array if the constant you pass in the type parameter indicates a 2D array of any type.

If the constant you pass in the type parameter indicates a neither a string nor an array, the value returned is not defined.

Pass NULL if you do not want this value.

dimension2 unsigned int Returns the size of the second dimension of the array if the constant you pass in the type parameter indicates a 2D array of any type.

If the constant you pass in the type parameter does not indicate a 2D array, the value returned is not defined.

Pass NULL if you do not want this value.

Return Value

Name	Type	Description
status	HRESULT	The value that indicates whether an error occurred. A negative error code indicates function failure. Error codes are defined in CVIversion\toolslib\datasock\dataskt.h and <Program Files>\National Instruments\Shared\MSDTRedistributables\SDKHeaderFiles\8.1\winerror.h. Other error codes in winerror.h are generated by ActiveX Servers and are passed on to you by the DataSocket Library.

Additional Information

Library: DataSocket Library

Include file: datasock\dataskt.h

LabWindows/CVI compatibility: LabWindows/CVI 5.5 and later

LabWindows/CVI