ua_variant_setter

Setter and attach functions for the ua_variant structure. More...

Functions
BASE_EXPORT void	ua_variant_set_bool (struct ua_variant *v, bool val)
	Write a boolean to the ua_variant val. More...
BASE_EXPORT void	ua_variant_set_byte (struct ua_variant *v, uint8_t val)
	Write a byte(uint8) to the ua_variant val. More...
BASE_EXPORT void	ua_variant_set_sbyte (struct ua_variant *v, int8_t val)
	Write a signed byte(int8) to the ua_variant val. More...
BASE_EXPORT void	ua_variant_set_uint16 (struct ua_variant *v, uint16_t val)
	Write an uint16 to the ua_variant val. More...
BASE_EXPORT void	ua_variant_set_int16 (struct ua_variant *v, int16_t val)
	Write an int16 to the ua_variant val. More...
BASE_EXPORT void	ua_variant_set_uint32 (struct ua_variant *v, uint32_t val)
	Write an uint32 to the ua_variant val. More...
BASE_EXPORT void	ua_variant_set_int32 (struct ua_variant *v, int32_t val)
	Write an int32 to the ua_variant val. More...
BASE_EXPORT void	ua_variant_set_uint64 (struct ua_variant *v, uint64_t val)
	Write an uint64 to the ua_variant val. More...
BASE_EXPORT void	ua_variant_set_int64 (struct ua_variant *v, int64_t val)
	Write an int64 to the ua_variant val. More...
BASE_EXPORT void	ua_variant_set_float (struct ua_variant *v, float val)
	Write a float to the ua_variant val. More...
BASE_EXPORT void	ua_variant_set_double (struct ua_variant *v, double val)
	Write a double to the ua_variant val. More...
BASE_EXPORT void	ua_variant_set_datetime (struct ua_variant *v, ua_datetime val)
	Write a double to the ua_variant val. More...
BASE_EXPORT int	ua_variant_set_string (struct ua_variant *v, const char *val)
	Fills the given variant v with an OPC UA String. More...
BASE_EXPORT int	ua_variant_set_stringn (struct ua_variant *v, const char *val, size_t len)
	Fills the given variant v with an OPC UA String. More...
BASE_EXPORT int	ua_variant_set_bytestring (struct ua_variant *v, const char *data, int len)
	Fills the given variant v with an OPC UA ByteString. More...
BASE_EXPORT int	ua_variant_set_xmlelement (struct ua_variant *v, const char *data, int len)
	Fills the given variant v with an XML element. More...
BASE_EXPORT int	ua_variant_set_nodeid (struct ua_variant *v, const struct ua_nodeid *id)
	Fills the given variant v with an UA Nodeid. More...
BASE_EXPORT int	ua_variant_set_expandednodeid (struct ua_variant *v, const struct ua_expandednodeid *id)
	Fills the given variant v with an UA ExpandedNodeid. More...
BASE_EXPORT int	ua_variant_set_guid (struct ua_variant *v, const struct ua_guid *guid)
	Fills the given variant v with an UA GUID. More...
BASE_EXPORT void	ua_variant_set_statuscode (struct ua_variant *v, ua_statuscode status)
BASE_EXPORT int	ua_variant_set_qualifiedname (struct ua_variant *v, int nsindex, const char *name)
	Fills the given variant v with an UA Qualifiedname. More...
BASE_EXPORT int	ua_variant_set_localizedtext (struct ua_variant *v, const char *locale, const char *text)
	Fills the given variant v with an UA Localizedtext. More...
BASE_EXPORT int	ua_variant_set_extensionobject (struct ua_variant *v, const void *obj, const struct ua_nodeid *type_id)
	Set an encodable object as extensionobject to a variant. More...
BASE_EXPORT int	ua_variant_set_extensionobject_numeric (struct ua_variant *v, const void *obj, uint16_t nsindex, uint32_t value)
	This is a convenience overload function for ua_variant_set_extensionobject() which allows settings UA defined structure types without creating helper variables for the typeid. More...
BASE_EXPORT int	ua_variant_set_extensionobject_binary (struct ua_variant *v, const struct ua_bytestring *data, const struct ua_nodeid *encoding_id)
	Stores a pre-encoded binary extensionobject in the variant. More...
BASE_EXPORT int	ua_variant_set_scalar (struct ua_variant *dst, enum ua_variant_type type, const void *val)
	Set a scalar as value for the variant dst. More...
BASE_EXPORT void	ua_variant_attach_string (struct ua_variant *v, char *val)
	Fills the given variant v with an OPC UA String. More...
BASE_EXPORT void	ua_variant_attach_stringn (struct ua_variant *v, char *val, size_t len)
	Fills the given variant v with an OPC UA String. More...
BASE_EXPORT int	ua_variant_smart_attach_const_string (struct ua_variant *v, const char *val)
	Fills the given variant v with an OPC UA String. More...
BASE_EXPORT int	ua_variant_smart_attach_const_stringn (struct ua_variant *v, const char *val, size_t len)
	Fills the given variant v with an OPC UA String. More...
BASE_EXPORT int	ua_variant_attach_scalar (struct ua_variant *v, enum ua_variant_type type, void *val)
	Attach a scaler value to the given variant. More...
BASE_EXPORT int	ua_variant_attach_extensionobject (struct ua_variant *v, void *obj, const struct ua_nodeid *type_id)
	Attach an encodable object as extensionobject to a variant. More...
BASE_EXPORT int	ua_variant_set_bool_array (struct ua_variant *v, bool *val, size_t num)
BASE_EXPORT int	ua_variant_set_byte_array (struct ua_variant *v, uint8_t *val, size_t num)
BASE_EXPORT int	ua_variant_set_sbyte_array (struct ua_variant *v, int8_t *val, size_t num)
BASE_EXPORT int	ua_variant_set_uint16_array (struct ua_variant *v, uint16_t *val, size_t num)
BASE_EXPORT int	ua_variant_set_int16_array (struct ua_variant *v, int16_t *val, size_t num)
BASE_EXPORT int	ua_variant_set_uint32_array (struct ua_variant *v, uint32_t *val, size_t num)
BASE_EXPORT int	ua_variant_set_int32_array (struct ua_variant *v, int32_t *val, size_t num)
BASE_EXPORT int	ua_variant_set_uint64_array (struct ua_variant *v, uint64_t *val, size_t num)
BASE_EXPORT int	ua_variant_set_int64_array (struct ua_variant *v, int64_t *val, size_t num)
BASE_EXPORT int	ua_variant_set_float_array (struct ua_variant *v, float *val, size_t num)
BASE_EXPORT int	ua_variant_set_double_array (struct ua_variant *v, double *val, size_t num)
BASE_EXPORT int	ua_variant_set_extensionobject_array (struct ua_variant *v, const void *obj, size_t num, const struct ua_nodeid *type_id)
	Stores an array of custom structures in a variant. More...
BASE_EXPORT int	ua_variant_set_array (struct ua_variant *v, enum ua_variant_type type, const void *values, size_t num)
	Stores the given array data in the variant. More...
BASE_EXPORT int	ua_variant_set_string_array (struct ua_variant *v, const char **val, size_t num)
	Set a C string array as data for a variant. More...
BASE_EXPORT int	ua_variant_attach_array (struct ua_variant *v, enum ua_variant_type type, void *val, size_t num)
	Attach an array value to the given variant. More...
BASE_EXPORT int	ua_variant_smart_attach_string_array (struct ua_variant *v, const char **val, size_t num)
	Smart attach a C string array as data for a variant. More...
BASE_EXPORT int	ua_variant_attach_extensionobject_array (struct ua_variant *v, void *array, size_t num, const struct ua_nodeid *type_id)
	Attach an array of complex objects to a variant as extensionobjects. More...
BASE_EXPORT int	ua_variant_set_matrix (struct ua_variant *v, enum ua_variant_type type, const void *values, size_t num, const int32_t *dimensions, int32_t num_dimensions)
	Stores the given matrix data in the variant. More...

Detailed Description

Setter and attach functions for the ua_variant structure.

Setter functions set a copy of the value as the new value of the structure. Thus the original value must still be cleared.

Attach functions attach the original value as the new value of the structure. Thus the original value must NOT be cleared.

In both cases the original variant is not cleared, so if there is data contained in the variant ua_variant_clear must be called before calling any of these functions.

Function Documentation

ua_variant_attach_array()

BASE_EXPORT int ua_variant_attach_array	(	struct ua_variant *	v,
		enum ua_variant_type	type,
		void *	val,
		size_t	num
	)

Attach an array value to the given variant.

This function takes ownership of the memory val and must not be freed by the caller. The memory must be allocated using ipc_malloc.

Parameters

v	Variant to attach the data to.
type	The type of data.
val	Address of array value.
num	Number of elements in array.

Returns

Zero on success, UA_EBADINVALIDARGUMENT if the type is invalid.

ua_variant_attach_extensionobject()

BASE_EXPORT int ua_variant_attach_extensionobject	(	struct ua_variant *	v,
		void *	obj,
		const struct ua_nodeid *	type_id
	)

Attach an encodable object as extensionobject to a variant.

On success the variant takes ownership of the object.

Parameters

v	variant to attach object to.
obj	object to attach.
type_id	type of the object

Returns

0 on success or errorcode on failure.

ua_variant_attach_extensionobject_array()

BASE_EXPORT int ua_variant_attach_extensionobject_array	(	struct ua_variant *	v,
		void *	array,
		size_t	num,
		const struct ua_nodeid *	type_id
	)

Attach an array of complex objects to a variant as extensionobjects.

Takes a plain array of objects and converts it into an array of extensionobjects to attach to the variant. Uses as little as possible allocations, so the objects from the array are shallow copied, the array itself is of no use and must be freed by the caller.

Works only for arrays where all objects are of the same type.

In case of an error the variant is left as NULL variant and the provided array is still valid.

Parameters

v	Variant to attach array to.
array	Array with complex objects.
num	Number of objects in the array
type_id	TypeId of the objects.

Returns

Zero on success or errorcode on failure.

ua_variant_attach_scalar()

BASE_EXPORT int ua_variant_attach_scalar	(	struct ua_variant *	v,
		enum ua_variant_type	type,
		void *	val
	)

Attach a scaler value to the given variant.

For simple non-pointer types (e.g. bool, int, float, ...) this is a simple memcpy and the value is not further touched.

For structures (e.g. Guid, NodeId, ByteString, ...) the pointer is attached and the variant takes ownership of the memory. So val must not be freed and must have been allocated with ipc_malloc by the caller.

Parameters

v	Variant to attach the data to.
type	The type of data.
val	Address of scalar value.

Returns

Zero on success, UA_EBADINVALIDARGUMENT if the type is invalid.

ua_variant_attach_string()

BASE_EXPORT void ua_variant_attach_string	(	struct ua_variant *	v,
		char *	val
	)

Fills the given variant v with an OPC UA String.

This function does not create a copy of the provided string val. The string must be UTF-8 encoded. It is safe to pass a NULL pointer here, in this case the UA string becomes a NULL-String.

ua_variant_attach_stringn()

BASE_EXPORT void ua_variant_attach_stringn	(	struct ua_variant *	v,
		char *	val,
		size_t	len
	)

Fills the given variant v with an OPC UA String.

This function behaves like ua_variant_attach_string, but avoids a strlen call by providing the string length as an additional parameter.

ua_variant_set_array()

BASE_EXPORT int ua_variant_set_array	(	struct ua_variant *	v,
		enum ua_variant_type	type,
		const void *	values,
		size_t	num
	)

Stores the given array data in the variant.

This operation creates a copy of the given data.

void demo_array(struct ua_variant *value)
{
    /* demo data */
    uint32_t data[5] = { 1, 2, 3, 4, 5 };

    /* store array data in variant */
    ua_variant_set_array(value, UA_VT_UINT32, data, countof(data));
}

Parameters

v	The variant to work on.
type	The datatype of the array elements.
values	Array of values of type type.
num	Number of elements in val.

Returns

Zero on success or a negative error code on failure. Possible errors are:

• UA_EBADNOMEM The memory allocation failed.
• UA_EBADINVALIDARGUMENT One of the arguments was invalid.

ua_variant_set_bool()

BASE_EXPORT void ua_variant_set_bool	(	struct ua_variant *	v,
		bool	val
	)

Write a boolean to the ua_variant val.

ua_variant_set_byte()

BASE_EXPORT void ua_variant_set_byte	(	struct ua_variant *	v,
		uint8_t	val
	)

Write a byte(uint8) to the ua_variant val.

ua_variant_set_bytestring()

BASE_EXPORT int ua_variant_set_bytestring	(	struct ua_variant *	v,
		const char *	data,
		int	len
	)

Fills the given variant v with an OPC UA ByteString.

This function creates a copy of the provided data.

ua_variant_set_datetime()

BASE_EXPORT void ua_variant_set_datetime	(	struct ua_variant *	v,
		ua_datetime	val
	)

Write a double to the ua_variant val.

ua_variant_set_double()

BASE_EXPORT void ua_variant_set_double	(	struct ua_variant *	v,
		double	val
	)

Write a double to the ua_variant val.

ua_variant_set_expandednodeid()

BASE_EXPORT int ua_variant_set_expandednodeid	(	struct ua_variant *	v,
		const struct ua_expandednodeid *	id
	)

Fills the given variant v with an UA ExpandedNodeid.

This function creates a copy of the provided id.

Returns

• UA_EGOOD on success
• UA_EBADINVALIDARGUMENT if id is a null pointer
• UA_EBADNOMEM if memory allocation fails

ua_variant_set_extensionobject()

BASE_EXPORT int ua_variant_set_extensionobject	(	struct ua_variant *	v,
		const void *	obj,
		const struct ua_nodeid *	type_id
	)

Set an encodable object as extensionobject to a variant.

The variant receives a copy of the object, so the caller is responsible for deleting the object.

The type must be registered in the SDK's type system using ua_type_table_register_structure. The encoding_id will be set internally if the given type_id is known type.

The SDK will encode the object using the registered type information.

Parameters

v	Variant which receives the extensionobject.
obj	object to set.
type_id	type of the object

Returns

0 on success or errorcode on failure.

ua_variant_set_extensionobject_array()

BASE_EXPORT int ua_variant_set_extensionobject_array	(	struct ua_variant *	v,
		const void *	obj,
		size_t	num,
		const struct ua_nodeid *	type_id
	)

Stores an array of custom structures in a variant.

The difficulty here is that according to how UA has defined this feature, the extensionobject does not store the native array in one extensionobject, but creates an array of extensionobjects, where each element just store one structure array element.

This function creates a deep copy of the gievn structure array.

It is allowed to use 0 for num, which will create an empty array.

Parameters

v	Variant to attach the data to.
obj	Array of structure to store in the variant.
num	Array size.
type_id	type of the object.

Returns

Zero on success, UA_EBADNOTFOUND if the type is not known. UA_EBADNOMEM in case of an out of memory situation.

ua_variant_set_extensionobject_binary()

BASE_EXPORT int ua_variant_set_extensionobject_binary	(	struct ua_variant *	v,
		const struct ua_bytestring *	data,
		const struct ua_nodeid *	encoding_id
	)

Stores a pre-encoded binary extensionobject in the variant.

This function is used for custom structures which are encoded on application level. This structures must be pre-encoded in UA binary format. The SDK does not need to know this type, so they don't need to be registered at the SDK.

Parameters

v	Variant which receives the extensionobject.
data	Bytestring with pre-encoded UA binary data.
encoding_id	EncodingId of the custom type.

Returns

Zero on success or negative errorcode on failure.

ua_variant_set_extensionobject_numeric()

BASE_EXPORT int ua_variant_set_extensionobject_numeric	(	struct ua_variant *	v,
		const void *	obj,
		uint16_t	nsindex,
		uint32_t	value
	)

This is a convenience overload function for ua_variant_set_extensionobject() which allows settings UA defined structure types without creating helper variables for the typeid.

This also works for other non-UA defined types with numeric typeid. For performance reasons, most types are using numeric typeids anyway.

struct ua_variant val;
struct ua_optionset os;
uint8_t bits[5] = { 0xaa, 0xaa, 0xaa, 0x55, 0x55 };
uint8_t valid[5] = { 0xff, 0xff, 0xff, 0xff, 0xff };
int ret;

// create optionset
ua_optionset_init(&os);
ret = ua_bytestring_set(&os.value, (const char *)bits, sizeof(bits));
if (ret != 0) handle_error();
ret = ua_bytestring_set(&os.valid_bits, (const char *)valid, sizeof(valid));
if (ret != 0) handle_error();

// store in variant
ret = ua_variant_set_extensionobject_numeric(&val, &os, 0, UA_ID_OPTIONSET);
if (ret != 0) handle_error();

Parameters

v	Variant which receives the extensionobject.
obj	object to set.
nsindex	The namespace index of the typeid. Zero for UA defined types.
value	The numeric value of the typeid. You can use the generated defines UA_ID_* for this.

Returns

0 on success or errorcode on failure.

ua_variant_set_float()

BASE_EXPORT void ua_variant_set_float	(	struct ua_variant *	v,
		float	val
	)

Write a float to the ua_variant val.

ua_variant_set_guid()

BASE_EXPORT int ua_variant_set_guid	(	struct ua_variant *	v,
		const struct ua_guid *	guid
	)

Fills the given variant v with an UA GUID.

This function creates a copy of the provided guid.

Returns

• UA_EGOOD on success
• UA_EBADNOMEM if memory allocation fails

ua_variant_set_int16()

BASE_EXPORT void ua_variant_set_int16	(	struct ua_variant *	v,
		int16_t	val
	)

Write an int16 to the ua_variant val.

ua_variant_set_int32()

BASE_EXPORT void ua_variant_set_int32	(	struct ua_variant *	v,
		int32_t	val
	)

Write an int32 to the ua_variant val.

ua_variant_set_int64()

BASE_EXPORT void ua_variant_set_int64	(	struct ua_variant *	v,
		int64_t	val
	)

Write an int64 to the ua_variant val.

ua_variant_set_localizedtext()

BASE_EXPORT int ua_variant_set_localizedtext	(	struct ua_variant *	v,
		const char *	locale,
		const char *	text
	)

Fills the given variant v with an UA Localizedtext.

This function creates a copy of the provided locale and text.

ua_variant_set_matrix()

BASE_EXPORT int ua_variant_set_matrix	(	struct ua_variant *	v,
		enum ua_variant_type	type,
		const void *	values,
		size_t	num,
		const int32_t *	dimensions,
		int32_t	num_dimensions
	)

Stores the given matrix data in the variant.

This operation creates a copy of the given data.

void demo_matrix(struct ua_variant *value)
{
    #define rows 3
    #define cols 5
    /* demo data */
    uint32_t data[rows][cols] = {
        {  1,  2,  3,  4,  5 },
        {  6,  7,  8,  9, 10 },
        { 11, 12, 13, 14, 15 }
    };
    int32_t num_dimensions = 2;
    int32_t dimensions[2]  = { cols, rows }; /* "The lower rank dimensions appear first in the array.", Part6 - OPC UA spec. */
    size_t num_elements;
    unsigned int row, col;
    int i;

    /* calculate total number of elements in data */
    for (num_elements = 1, i = 0; i < num_dimensions; ++i) {
        num_elements *= dimensions[i];
    }

    /* store matrix data in variant */
    ua_variant_set_matrix(value, UA_VT_UINT32, data, num_elements, dimensions, num_dimensions);

    /* Print example data */
    printf("example matrix:\n");
    printf("A = (\n");
    for (row = 0; row < rows; ++row) {
        printf("      ( ");
        for (col = 0; col < cols; ++col) {
            printf("%2u ", data[row][col]);
        }
        printf(")\n");
    }
    printf("    )\n");
}

Parameters

v	The variant to work on.
type	The datatype of the array elements.
values	The matrix data. This contains num values of type * type.
num	Total number of elements in values
dimensions	Array of matrix dimensions, where each elements contains the length of the matrix dimension. The lower rank dimension is encoded first.
num_dimensions	Number of dimensions. This is the length of dimensions.

Returns

Zero on success or a negative error code on failure. Possible errors are:

• UA_EBADNOMEM The memory allocation failed.
• UA_EBADINVALIDARGUMENT One of the arguments was invalid.

ua_variant_set_nodeid()

BASE_EXPORT int ua_variant_set_nodeid	(	struct ua_variant *	v,
		const struct ua_nodeid *	id
	)

Fills the given variant v with an UA Nodeid.

This function creates a copy of the provided id.

Returns

• UA_EGOOD on success
• UA_EBADINVALIDARGUMENT if id is a null pointer
• UA_EBADNOMEM if memory allocation fails

ua_variant_set_qualifiedname()

BASE_EXPORT int ua_variant_set_qualifiedname	(	struct ua_variant *	v,
		int	nsindex,
		const char *	name
	)

Fills the given variant v with an UA Qualifiedname.

This function creates a copy of the provided name.

ua_variant_set_sbyte()

BASE_EXPORT void ua_variant_set_sbyte	(	struct ua_variant *	v,
		int8_t	val
	)

Write a signed byte(int8) to the ua_variant val.

ua_variant_set_scalar()

BASE_EXPORT int ua_variant_set_scalar	(	struct ua_variant *	dst,
		enum ua_variant_type	type,
		const void *	val
	)

Set a scalar as value for the variant dst.

Creates as copy of the value pointed to by val and sets it as value for the variant.

Returns

Zero on success or negative errorcode on failure.

ua_variant_set_string()

BASE_EXPORT int ua_variant_set_string	(	struct ua_variant *	v,
		const char *	val
	)

Fills the given variant v with an OPC UA String.

This function creates a copy of the provided string val. The string must be UTF-8 encoded. It is safe to pass a NULL pointer here, in this case the UA string becomes a NULL-String.

ua_variant_set_string_array()

BASE_EXPORT int ua_variant_set_string_array	(	struct ua_variant *	v,
		const char **	val,
		size_t	num
	)

Set a C string array as data for a variant.

Parameters

v	Variant structure to set array.
val	Array of C strings.
num	Number of element in the array.

Returns

Zero on success or a negative error code on failure.

ua_variant_set_stringn()

BASE_EXPORT int ua_variant_set_stringn	(	struct ua_variant *	v,
		const char *	val,
		size_t	len
	)

Fills the given variant v with an OPC UA String.

This function behaves like ua_variant_set_string, but avoids a strlen call by providing the string length as an additional parameter.

ua_variant_set_uint16()

BASE_EXPORT void ua_variant_set_uint16	(	struct ua_variant *	v,
		uint16_t	val
	)

Write an uint16 to the ua_variant val.

ua_variant_set_uint32()

BASE_EXPORT void ua_variant_set_uint32	(	struct ua_variant *	v,
		uint32_t	val
	)

Write an uint32 to the ua_variant val.

ua_variant_set_uint64()

BASE_EXPORT void ua_variant_set_uint64	(	struct ua_variant *	v,
		uint64_t	val
	)

Write an uint64 to the ua_variant val.

ua_variant_set_xmlelement()

BASE_EXPORT int ua_variant_set_xmlelement	(	struct ua_variant *	v,
		const char *	data,
		int	len
	)

Fills the given variant v with an XML element.

This function creates a copy of the provided data. This is technically equivalent to ua_variant_set_bytestring. But data should contain a valid UTF-8 encoded XML element. This code does not perform any XML validtion so the caller is responsible for providing valid data.

ua_variant_smart_attach_const_string()

BASE_EXPORT int ua_variant_smart_attach_const_string	(	struct ua_variant *	v,
		const char *	val
	)

Fills the given variant v with an OPC UA String.

When compiled without MEMORY_USE_SHM this simply attaches the string to the variant. When compiled with MEMORY_USE_SHM this creates a copy in shared memory, which is necessary to work across memory boundaries. Attaching a string is faster and consumes less memory than coping a string, so we try to avoid the latter one if possible.

ua_variant_smart_attach_const_stringn()

BASE_EXPORT int ua_variant_smart_attach_const_stringn	(	struct ua_variant *	v,
		const char *	val,
		size_t	len
	)

Fills the given variant v with an OPC UA String.

This function behaves like ua_variant_smart_attach_const_string, but avoids a strlen call by providing the string length as an additional parameter.

ua_variant_smart_attach_string_array()

BASE_EXPORT int ua_variant_smart_attach_string_array	(	struct ua_variant *	v,
		const char **	val,
		size_t	num
	)

Smart attach a C string array as data for a variant.

Similar to ua_variant_set_string_array but uses ua_string_smart_attach_const to set the individual array members. This is faster and consumes less memory when MEMORY_USE_SHM is disabled.