A union of all built-in data types including an OpcUa_ExtensionObject. More...

Data Structures
struct	ua_variant_array

struct	ua_variant_matrix

struct	ua_variant
	Structure for an UA Variant, see also ua_variant. More...

Enumerations
enum	ua_variant_type { UA_VT_NULL = 0, UA_VT_BOOLEAN = 1, UA_VT_SBYTE = 2, UA_VT_BYTE = 3, UA_VT_INT16 = 4, UA_VT_UINT16 = 5, UA_VT_INT32 = 6, UA_VT_UINT32 = 7, UA_VT_INT64 = 8, UA_VT_UINT64 = 9, UA_VT_FLOAT = 10, UA_VT_DOUBLE = 11, UA_VT_STRING = 12, UA_VT_DATETIME = 13, UA_VT_GUID = 14, UA_VT_BYTESTRING = 15, UA_VT_XMLELEMENT = 16, UA_VT_NODEID = 17, UA_VT_EXPANDEDNODEID = 18, UA_VT_STATUSCODE = 19, UA_VT_QUALIFIEDNAME = 20, UA_VT_LOCALIZEDTEXT = 21, UA_VT_EXTENSIONOBJECT = 22, UA_VT_DATAVALUE = 23, UA_VT_VARIANT = 24, UA_VT_DIAGNOSTICINFO = 25, UA_VT_ENCODED_BINARY = 26, UA_VT_IS_MATRIX = 0xc0, UA_VT_IS_ARRAY = 0x80, UA_VT_ARRAYMASK = 0xc0, UA_VT_TYPEMASK = 0x3f }
	Type identifier for a variant.

Functions
void	ua_variant_init (struct ua_variant *v)
	Initialize an ua_variant as null variant.

void	ua_variant_clear (struct ua_variant *v)
	clear an ua_variant. More...

void	ua_variant_set_bool (struct ua_variant *v, bool val)
	Write a boolean to the ua_variant `val`. More...

void	ua_variant_set_byte (struct ua_variant *v, uint8_t val)
	Write a byte(uint8) to the ua_variant `val`. More...

void	ua_variant_set_sbyte (struct ua_variant *v, int8_t val)
	Write a signed byte(int8) to the ua_variant `val`. More...

void	ua_variant_set_uint16 (struct ua_variant *v, uint16_t val)
	Write an uint16 to the ua_variant `val`. More...

void	ua_variant_set_int16 (struct ua_variant *v, int16_t val)
	Write an int16 to the ua_variant `val`. More...

void	ua_variant_set_uint32 (struct ua_variant *v, uint32_t val)
	Write an uint32 to the ua_variant `val`. More...

void	ua_variant_set_int32 (struct ua_variant *v, int32_t val)
	Write an int32 to the ua_variant `val`. More...

void	ua_variant_set_uint64 (struct ua_variant *v, uint64_t val)
	Write an uint64 to the ua_variant `val`. More...

void	ua_variant_set_int64 (struct ua_variant *v, int64_t val)
	Write an int64 to the ua_variant `val`. More...

void	ua_variant_set_float (struct ua_variant *v, float val)
	Write a float to the ua_variant `val`. More...

void	ua_variant_set_double (struct ua_variant *v, double val)
	Write a double to the ua_variant `val`. More...

int	ua_variant_set_string (struct ua_variant v, const char val)
	Fills the given variant `v` with an OPC UA String. More...

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

void	ua_variant_attach_string (struct ua_variant v, char val)
	Fills the given variant `v` with an OPC UA String. More...

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

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

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

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

int	ua_variant_set_xmlelement (struct ua_variant v, const char data, int len)
	Fills the given variant `v` with an XML element. More...

int	ua_variant_set_nodeid (struct ua_variant v, const struct ua_nodeid id)
	Fills the given variant `v` with an UA Nodeid. More...

int	ua_variant_set_qualifiedname (struct ua_variant v, int nsindex, const char name)
	Fills the given variant `v` with an UA Qualifiedname. More...

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

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

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

int	ua_variant_detach_extensionobject (struct ua_variant v, void obj, struct ua_nodeid type_id)
	Detach an encodable object from a variant. More...

int	ua_variant_compare (const struct ua_variant a, const struct ua_variant b) UA_PURE_FUNCTION
	Compare the variants `a` and `b`. More...

int	ua_variant_copy (struct ua_variant dst, const struct ua_variant src)
	Create a copy of variant `src`. More...

ua_statuscode	ua_variant_read_indexrange (struct ua_variant dst, const struct ua_variant src, const struct ua_indexrange *ranges, unsigned int num_ranges)
	Copy the elements of variant `src` specified by an indexrange `ranges` to the variant `dst`.

int	ua_variant_to_string (const struct ua_variant src, struct ua_string dst)

int	ua_variant_from_string (struct ua_variant dst, uint8_t type, const struct ua_string src)

static bool	ua_variant_is_null (const struct ua_variant *v)
	Test if the ua_variant `v` is a null variant.

static enum ua_variant_type	ua_variant_get_type (const struct ua_variant *v)
	Returns the built-in datatype of the given variant. More...

static bool	ua_variant_is_array (const struct ua_variant *v)
	Returns true if the given variant is an array. More...

static bool	ua_variant_is_matrix (const struct ua_variant *v)
	Returns true if the given variant is a matrix. More...

int	ua_variant_set_bool_array (struct ua_variant v, bool val, size_t num)

int	ua_variant_set_byte_array (struct ua_variant v, uint8_t val, size_t num)

int	ua_variant_set_sbyte_array (struct ua_variant v, int8_t val, size_t num)

int	ua_variant_set_uint16_array (struct ua_variant v, uint16_t val, size_t num)

int	ua_variant_set_int16_array (struct ua_variant v, int16_t val, size_t num)

int	ua_variant_set_uint32_array (struct ua_variant v, uint32_t val, size_t num)

int	ua_variant_set_int32_array (struct ua_variant v, int32_t val, size_t num)

int	ua_variant_set_uint64_array (struct ua_variant v, uint64_t val, size_t num)

int	ua_variant_set_int64_array (struct ua_variant v, int64_t val, size_t num)

int	ua_variant_set_float_array (struct ua_variant v, float val, size_t num)

int	ua_variant_set_double_array (struct ua_variant v, double val, size_t num)

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

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

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

int	ua_variant_get_bool (const struct ua_variant v, bool val) UA_NONNULL(1

int int	ua_variant_get_byte (const struct ua_variant v, uint8_t val) UA_NONNULL(1

int int int	ua_variant_get_sbyte (const struct ua_variant v, int8_t val) UA_NONNULL(1

int int int int	ua_variant_get_uint16 (const struct ua_variant v, uint16_t val) UA_NONNULL(1

int int int int int	ua_variant_get_int16 (const struct ua_variant v, int16_t val) UA_NONNULL(1

int int int int int int	ua_variant_get_uint32 (const struct ua_variant v, uint32_t val) UA_NONNULL(1

int int int int int int int	ua_variant_get_int32 (const struct ua_variant v, int32_t val) UA_NONNULL(1

int int int int int int int int	ua_variant_get_uint64 (const struct ua_variant v, uint64_t val) UA_NONNULL(1

int int int int int int int int int	ua_variant_get_int64 (const struct ua_variant v, int64_t val) UA_NONNULL(1

int int int int int int int int int int	ua_variant_get_float (const struct ua_variant v, float val) UA_NONNULL(1

int int int int int int int int int int int	ua_variant_get_double (const struct ua_variant v, double val) UA_NONNULL(1

int int int int int int int int int int int int	ua_variant_get_string (const struct ua_variant v, struct ua_string val) UA_NONNULL(1

int int int int int int int int int int int int int	ua_variant_get_bytestring (const struct ua_variant v, struct ua_bytestring val) UA_NONNULL(1

int int int int int int int int int int int int int int	ua_variant_get_xmlelement (const struct ua_variant v, struct ua_xmlelement val) UA_NONNULL(1

int int int int int int int int int int int int int int int	ua_variant_get_nodeid (const struct ua_variant v, struct ua_nodeid val) UA_NONNULL(1

int int int int int int int int int int int int int int int int	ua_variant_get_qualifiedname (const struct ua_variant v, struct ua_qualifiedname val) UA_NONNULL(1

int int int int int int int int int int int int int int int int int	ua_variant_get_localizedtext (const struct ua_variant v, struct ua_localizedtext val) UA_NONNULL(1

int int int int int int int int int int int int int int int int int int	ua_variant_get_array (const struct ua_variant v, struct ua_variant_array const *array)

int	ua_variant_array_get_data (const struct ua_variant_array array, void const data, int32_t length)
	Returns the array raw data of the variant array. More...

int	ua_variant_get_matrix (const struct ua_variant v, struct ua_variant_matrix const *matrix)

int	ua_variant_matrix_get_data (const struct ua_variant_matrix matrix, void const data, int32_t length)
	Returns the matrix raw data of the variant matrix. More...

int	ua_variant_matrix_get_dimensions (const struct ua_variant_matrix matrix, int32_t const dimensions, int32_t num_dimensions)
	Returns the dimensions of the variant matrix. More...

Detailed Description

A union of all built-in data types including an OpcUa_ExtensionObject.

Variants can also contain arrays of any of these built-in types. Variants are used to store any value or parameter with a data type of BaseDataType or one of its subtypes.

Variants can be empty. An empty Variant is described as having a null value and should be treated like a null column in a SQL database. A null value in a Variant may not be the same as a null value for data types that support nulls such as Strings. Some development platforms may not be able to preserve the distinction between a null for a DataType and a null for a Variant. Therefore applications shall not rely on this distinction.

Variants can contain arrays of Variants but they cannot directly contain another Variant.

DataValue and DiagnosticInfo types only have meaning when returned in a response message with an associated StatusCode. As a result, Variants cannot contain instances of DataValue or DiagnosticInfo. This requirement means that if an attribute supports the writing of a null value, it shall also support writing of an empty Variant and vice versa.

Variables with a DataType of BaseDataType are mapped to a Variant, however, the ValueRank and ArrayDimensions attributes place restrictions on what is allowed in the Variant. For example, if the ValueRank is Scalar, the Variant may only contain scalar values.

ExtensionObjects and Variants allow unlimited nesting which could result in stack overflow errors even if the message size is less than the maximum allowed. Decoders shall support at least 100 nesting levels. Decoders shall report an error if the number of nesting levels exceeds what it supports.

Function Documentation

int ua_variant_array_get_data	(	const struct ua_variant_array *	array,
		void const **	data,
		int32_t *	length
	)

Returns the array raw data of the variant array.

Parameters

array	The variant array ret"urned by ua_variant_get_array.
data	Pointer to array (return value).
length	Pointer the length field (return value).

Returns: Zero on success.

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.

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.

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.

void ua_variant_clear ( struct ua_variant * v )

clear an ua_variant.

Frees all resources allocated by the varaiant v.

Parameters

v	the variant to be cleared. Will be a null-variant afterwards.

int ua_variant_compare	(	const struct ua_variant *	a,
		const struct ua_variant *	b
	)

Compare the variants a and b.

It returns an integer less than, equal to, or greater than zero if a is less than, matches, or is greater than b. Unfortunately errors cannot be distinguished from a valid result and return -1, which has the same meaning as a is less than b.

This can be used for sorting values.

first the datatype is compared. If the datatypes are not equal the types are compared, which means a is smaller than b if a->type < b->type.
if the types are equal the values get compared, which means simple numeric comparison for numeric values, and string compare for strings. For more complex types the according <type>_compare function is called.

int ua_variant_copy	(	struct ua_variant *	dst,
		const struct ua_variant *	src
	)

Create a copy of variant src.

Parameters

dst	pointer to preallocated variant, is not required to be initialized. If `dst` is already a variant that holds further memory, it will not be freed.
src	the variant to copy.

Returns: 0 on success or errorcode on failure. If copy fails all resources allocated during copy are released and no clear must be called on dst.

int ua_variant_detach_extensionobject	(	struct ua_variant *	v,
		void **	obj,
		struct ua_nodeid *	type_id
	)

Detach an encodable object from a variant.

On success the variant is left as null variant.

Parameters

v	variant to detach object, must be of type extensionobject.
obj	the detached object.
type_id	struct provided by caller, will be assigned the type of the object, may be NULL if the caller is not interested in the type.

Returns: 0 on success or errorcode on failure.

static enum ua_variant_type ua_variant_get_type ( const struct ua_variant * v )

inlinestatic

Returns the built-in datatype of the given variant.

This unmasks any array or matrix flags so that the return value contains the pure datatype information.

static bool ua_variant_is_array ( const struct ua_variant * v )

inlinestatic

Returns true if the given variant is an array.

This is also true for matrix values.

static bool ua_variant_is_matrix ( const struct ua_variant * v )

inlinestatic

Returns true if the given variant is a matrix.

A matrix is any form for multi-dimensional array, which has more than one dimension.

int ua_variant_matrix_get_data	(	const struct ua_variant_matrix *	matrix,
		void const **	data,
		int32_t *	length
	)

Returns the matrix raw data of the variant matrix.

The raw data is an array with length = dim[0] * dim[1] * ... * dim[n-1], where n is the number of dimensions. E.g. a three dimensional matrix with dimensions = { 2, 3, 4 }, the length would be 2 * 3 * 4 = 24.

Parameters

matrix	The variant matrix returned by ua_variant_get_matrix.
data	Pointer to array (return value). Optional, can be NULL if not needed.
length	Pointer the length field (return value). Optional, can be NULL if not needed.

Returns: Zero on success.

int ua_variant_matrix_get_dimensions	(	const struct ua_variant_matrix *	matrix,
		int32_t const **	dimensions,
		int32_t *	num_dimensions
	)

Returns the dimensions of the variant matrix.

Parameters

matrix	The variant matrix returned by ua_variant_get_matrix.
dimensions	Pointer to array with dimensions lengths (return value). Optional, can be NULL if not needed.
num_dimensions	Pointer the length field (return value), which is the number of elements in `dimensions`. Optional, can be NULL if not needed.

Returns: Zero on success.

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.

void ua_variant_set_bool	(	struct ua_variant *	v,
		bool	val
	)

Write a boolean to the ua_variant val.

void ua_variant_set_byte	(	struct ua_variant *	v,
		uint8_t	val
	)

Write a byte(uint8) to the ua_variant val.

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.

void ua_variant_set_double	(	struct ua_variant *	v,
		double	val
	)

Write a double to the ua_variant val.

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.

Parameters

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

Returns: 0 on success or errorcode on failure.

void ua_variant_set_float	(	struct ua_variant *	v,
		float	val
	)

Write a float to the ua_variant val.

void ua_variant_set_int16	(	struct ua_variant *	v,
		int16_t	val
	)

Write an int16 to the ua_variant val.

void ua_variant_set_int32	(	struct ua_variant *	v,
		int32_t	val
	)

Write an int32 to the ua_variant val.

void ua_variant_set_int64	(	struct ua_variant *	v,
		int64_t	val
	)

Write an int64 to the ua_variant val.

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.

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.

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.

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.

void ua_variant_set_sbyte	(	struct ua_variant *	v,
		int8_t	val
	)

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

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.

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.

void ua_variant_set_uint16	(	struct ua_variant *	v,
		uint16_t	val
	)

Write an uint16 to the ua_variant val.

void ua_variant_set_uint32	(	struct ua_variant *	v,
		uint32_t	val
	)

Write an uint32 to the ua_variant val.

void ua_variant_set_uint64	(	struct ua_variant *	v,
		uint64_t	val
	)

Write an uint64 to the ua_variant val.

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.

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.

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.

Data Structures

Enumerations

Functions

Detailed Description

Function Documentation