A container for any structured DataTypes which cannot be represented as one of the other built-in data types. More...

Data Structures
struct	ua_extensionobject_properties

struct	ua_extensionobject
	Structure for an UA Extensionobject, see also ua_extensionobject. More...

Typedefs
typedef int(*	ua_extensionobject_lookup_type_t )(const struct ua_nodeid type_id, struct ua_extensionobject_properties prop, void *cb_data)

typedef int(*	ua_extensionobject_lookup_encoding_t )(const struct ua_nodeid encoding_id, struct ua_extensionobject_properties prop, void *cb_data)

Enumerations
enum	ua_extensionobject_encoding { UA_EXTENSIONOBJECT_NONE = 0, UA_EXTENSIONOBJECT_ENCODEABLEOBJECT = 1, UA_EXTENSIONOBJECT_BINARY = 2, UA_EXTENSIONOBJECT_XML = 3 }
	Indicates how the body of an OpcUa_ExtensionObject is encoded. More...

Functions
void	ua_extensionobject_init (struct ua_extensionobject *t)
	Initialize an ua_extensionobject as empty object without body.

void	ua_extensionobject_clear (struct ua_extensionobject *t)
	Clear an ua_extensionobject and remove body.

int	ua_extensionobject_compare (const struct ua_extensionobject a, const struct ua_extensionobject b)
	Compare two ua_extensionobjects. More...

int	ua_extensionobject_copy (struct ua_extensionobject dst, const struct ua_extensionobject src)
	Copy the ua_extensionobject `src` to `dst`. More...

int	ua_extensionobject_create_object_numeric (struct ua_extensionobject t, uint16_t nsindex, uint32_t type_id, void *object)
	Like ua_extensionobject_create_object but for numeric type_ids.

int	ua_extensionobject_create_object (struct ua_extensionobject t, const struct ua_nodeid type_id, void **object)
	Create a new object of a given type and attach it to an ua_extensionobject. More...

static int	ua_extensionobject_verify_and_get_type (const struct ua_extensionobject val, const struct ua_dict_structure *type)

int	ua_extensionobject_field_name_to_idx (const struct ua_extensionobject val, const char field_name)
	Get the index of a field in an extensionobject by its name. More...

int	ua_extensionobject_get_scalar (struct ua_extensionobject val, int field_idx, void *scalar)
	Get the pointer to a scalar field in an extensionobject. More...

int	ua_extensionobject_get_array (struct ua_extensionobject val, int field_idx, void array, int32_t array_len)
	Get the pointer to an array field in an extensionobject. More...

int	ua_extensionobject_resize_array (struct ua_extensionobject *val, int field_idx, int32_t new_len)
	Create, delete or resize an array field in an extensionobject. More...

int	ua_extensionobject_get_field_info (struct ua_extensionobject val, int field_idx, uint32_t ua_dict_flags, struct ua_nodeid type_id, struct ua_nodeid binary_encoding_id)
	Get information about a field of an extensionobject. More...

int	ua_extensionobject_register_nsindex (uint16_t nsindex, ua_extensionobject_lookup_type_t type_lookup, void type_cb_data, ua_extensionobject_lookup_encoding_t encoding_lookup, void encoding_cb_data)

int	ua_extensionobject_unregister_nsindex (uint16_t nsindex)

static int	ua_extensionobject_get_scalar_by_name (struct ua_extensionobject val, const char field_name, void **scalar)
	Same as ua_extensionobject_get_scalar but uses field name instead of index. More...

static int	ua_extensionobject_get_array_by_name (struct ua_extensionobject val, const char field_name, void *array, int32_t array_len)
	Same as ua_extensionobject_get_array but uses field name instead of index. More...

static int	ua_extensionobject_resize_array_by_name (struct ua_extensionobject val, const char field_name, int32_t new_len)
	Same as ua_extensionobject_resize_array but uses field name instead of index. More...

static int	ua_extensionobject_get_field_info_by_name (struct ua_extensionobject val, const char field_name, uint32_t ua_dict_flags, struct ua_nodeid type_id, struct ua_nodeid *binary_encoding_id)
	Same as ua_extensionobject_get_field_info but uses field name instead of index. More...

Detailed Description

A container for any structured DataTypes which cannot be represented as one of the other built-in data types.

The ExtensionObject contains a complex value serialized as a sequence of bytes, as an XML element or not encoded as an Encodeable. It also contains an identifier which indicates what data it contains and how it is encoded.

Structured DataTypes are represented in a Server address space as subtypes of the Structure DataType. The DataEncodings available for any given structured DataTypes are represented as a DataTypeEncoding object in the Server address space. The NodeId for the DataTypeEncoding Object is the identifier stored in the ExtensionObject. Part 3 of the OPC UA Specification describes how DataTypeEncoding Nodes are related to other Nodes of the address space. Server implementers should use namespace qualified numeric NodeIds for any DataTypeEncoding objects they define. This will minimize the overhead introduced by packing structured DataType values into an extensionobject.

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.

An ExtensionObject is encoded as sequence of bytes prefixed by the NodeId of its DataTypeEncoding and the number of bytes encoded.

An ExtensionObject may be encoded by the Application which means it is passed as a ByteString or an XmlElement to the encoder. In this case, the encoder will be able to write the number of bytes in the object before it encodes the bytes. However, an ExtensionObject may know how to encode/decode itself which means the encoder shall calculate the number of bytes before it encodes the object or it shall be able to seek backwards in the stream and update the length after encoding the body.

When a decoder encounters an ExtensionObject it shall check if it recognizes the DataTypeEncoding identifier. If it does then it can call the appropriate function to decode the object body. If the decoder does not recognize the type it shall use the Encoding to determine if the body is a ByteString or an XmlElement and then decode the object body or treat it as opaque data and skip over it.

Enumeration Type Documentation

enum ua_extensionobject_encoding

Indicates how the body of an OpcUa_ExtensionObject is encoded.

Enumerator
UA_EXTENSIONOBJECT_NONE	No body is encoded.
UA_EXTENSIONOBJECT_ENCODEABLEOBJECT	The object is contained unencoded as an encodeable object.
UA_EXTENSIONOBJECT_BINARY	The body is encoded according to the binary encoding rules.
UA_EXTENSIONOBJECT_XML	The body is encoded according to the XML encoding rules.

Function Documentation

int ua_extensionobject_compare	(	const struct ua_extensionobject *	a,
		const struct ua_extensionobject *	b
	)

Compare two ua_extensionobjects.

This function also treats two ua_extensionobjects as different if they have a different encoding. This is also the case if the specific compare function for the body cannot be found.

Returns: Zero if the ua_extensionobjects are the same.

int ua_extensionobject_copy	(	struct ua_extensionobject *	dst,
		const struct ua_extensionobject *	src
	)

Copy the ua_extensionobject src to dst.

This function preserves the encoding of the ua_extensionobject.

Returns: Zero on success or errorcode on failure.

int ua_extensionobject_create_object	(	struct ua_extensionobject *	t,
		const struct ua_nodeid *	type_id,
		void **	object
	)

Create a new object of a given type and attach it to an ua_extensionobject.

The newly allocated object can be retrieved by the object parameter as shown in the following example:

 struct ua_extensionobject eo; // extensionobject to attach the new object to
 struct ua_nodeid id;          // type id of the object
 struct ua_argument *argument; // typed pointer to the object
 int ret;
 
 // set the type of the new object
 ua_nodeid_set_numeric(&id, 0, UA_ID_ARGUMENT);
 
 // the object is allocated in this function
 ret = ua_extensionobject_create_object(&eo, &id, (void **) &argument);
 if (ret != 0) return ret;
 
 // the new object can now be accessed
 ua_nodeid_set_numeric(&argument->data_type, 0, UA_ID_STRING);
 argument->value_rank = -1;
 ...

int ua_extensionobject_field_name_to_idx	(	const struct ua_extensionobject *	val,
		const char *	field_name
	)

Get the index of a field in an extensionobject by its name.

Returns: Negative errorcode on failure, non-negative index on success.

int ua_extensionobject_get_array	(	struct ua_extensionobject *	val,
		int	field_idx,
		void **	array,
		int32_t *	array_len
	)

Get the pointer to an array field in an extensionobject.

Parameters

val	The extensionobject.
field_idx	Index of the field to get (the first field has index 0).
array	Pointer where the pointer to the array is written to.
array_len	Pointer where the length of the array is written to.

Returns: Zero on success or negative errorcode on failure.

static int ua_extensionobject_get_array_by_name	(	struct ua_extensionobject *	val,
		const char *	field_name,
		void **	array,
		int32_t *	array_len
	)

inlinestatic

Same as ua_extensionobject_get_array but uses field name instead of index.

int ua_extensionobject_get_field_info	(	struct ua_extensionobject *	val,
		int	field_idx,
		uint32_t *	ua_dict_flags,
		struct ua_nodeid *	type_id,
		struct ua_nodeid *	binary_encoding_id
	)

Get information about a field of an extensionobject.

Parameters

val	The extensionobject.
field_idx	Index of the field (the first field has index 0).
ua_dict_flags	Bitmask of UA_DICT_FLAG_* flags (optional).
type_id	Pointer to struct ua_nodeid to write the type id to (optional).
binary_encoding_id	Pointer to struct ua_nodeid to write the binary encoding id to (optional).

Returns: Zero on success or negative errorcode on failure.

static int ua_extensionobject_get_field_info_by_name	(	struct ua_extensionobject *	val,
		const char *	field_name,
		uint32_t *	ua_dict_flags,
		struct ua_nodeid *	type_id,
		struct ua_nodeid *	binary_encoding_id
	)

inlinestatic

Same as ua_extensionobject_get_field_info but uses field name instead of index.

int ua_extensionobject_get_scalar	(	struct ua_extensionobject *	val,
		int	field_idx,
		void **	scalar
	)

Get the pointer to a scalar field in an extensionobject.

Parameters

val	The extensionobject.
field_idx	Index of the field to get (the first field has index 0).
scalar	Pointer where the pointer to the scalar is written to.

Returns: Zero on success or negative errorcode on failure.

static int ua_extensionobject_get_scalar_by_name	(	struct ua_extensionobject *	val,
		const char *	field_name,
		void **	scalar
	)

inlinestatic

Same as ua_extensionobject_get_scalar but uses field name instead of index.

int ua_extensionobject_resize_array	(	struct ua_extensionobject *	val,
		int	field_idx,
		int32_t	new_len
	)

Create, delete or resize an array field in an extensionobject.

When the array is not allocated a new one is created, when new_len is smaller than 1 an existing array is deleted. When the length is increased new members are initialized with zero. When the length is decreased cut off members at the end are cleared.

Parameters

val	The extensionobject.
field_idx	Index of the field to get (the first field has index 0).
new_len	New length in number of members of the array.

Returns: Zero on success or negative errorcode on failure.

static int ua_extensionobject_resize_array_by_name	(	struct ua_extensionobject *	val,
		const char *	field_name,
		int32_t	new_len
	)

inlinestatic

Same as ua_extensionobject_resize_array but uses field name instead of index.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation