Identifier for UA nodes. More...

Data Structures
struct	ua_nodeid
	Structure for an UA Nodeid, see also ua_nodeid. More...

Macros
#define	UA_NODEID_INITIALIZER { { 0 }, UA_IDENTIFIER_NUMERIC, 0 }
	Initializes a nodeid struct as numeric null nodeid.

#define	UA_NODEID_NUMERIC_INITIALIZER(id, ns) { { id }, UA_IDENTIFIER_NUMERIC, ns }
	Initializes a nodeid struct as numeric nodeid with identifier and namespace index. More...

Enumerations
enum	ua_identifiertype { UA_IDENTIFIER_NUMERIC = 0, UA_IDENTIFIER_STRING, UA_IDENTIFIER_GUID, UA_IDENTIFIER_OPAQUE }
	The set of known node identifier types. More...

Functions
BASE_EXPORT void	ua_nodeid_init (struct ua_nodeid *id)
	Initializes `id` with a null nodeid.

BASE_EXPORT void	ua_nodeid_clear (struct ua_nodeid *id)
	Cleans all resources in `id` and makes it a null nodeid.

BASE_EXPORT void	ua_nodeid_set_numeric (struct ua_nodeid *id, uint16_t nsindex, uint32_t value)
	Set a numeric value and namespace index for a nodeid. More...

BASE_EXPORT int	ua_nodeid_set_string (struct ua_nodeid id, uint16_t nsindex, const char value)
	Set a string value and namespace index for a nodeid. More...

BASE_EXPORT int	ua_nodeid_set_guid (struct ua_nodeid id, uint16_t nsindex, const struct ua_guid value)
	Set a guid value and namespace index for a nodeid. More...

BASE_EXPORT int	ua_nodeid_set_bytestring (struct ua_nodeid id, uint16_t nsindex, const char value, int32_t len)
	Set a bytestring value and namespace index for a nodeid. More...

BASE_EXPORT int	ua_nodeid_attach_string (struct ua_nodeid id, uint16_t nsindex, char value)
	Attach a string value and set a namespace index for a nodeid. More...

BASE_EXPORT int	ua_nodeid_attach_string_const (struct ua_nodeid id, uint16_t nsindex, const char value)
	Attach a constant string value and set a namespace index for a nodeid. More...

BASE_EXPORT void	ua_nodeid_attach_guid (struct ua_nodeid id, uint16_t nsindex, struct ua_guid value)
	Attach a guid value and set a namespace index for a nodeid. More...

BASE_EXPORT int	ua_nodeid_attach_bytestring (struct ua_nodeid id, uint16_t nsindex, char value, int32_t len)
	Attach a bytestring value and set a namespace index for a nodeid. More...

BASE_EXPORT int	ua_nodeid_compare (const struct ua_nodeid a, const struct ua_nodeid b) UA_PURE_FUNCTION
	Compare two ua_nodeids. More...

BASE_EXPORT int	ua_nodeid_compare_numeric (const struct ua_nodeid *a, uint16_t nsidx, uint32_t value) UA_PURE_FUNCTION
	Convenience function to compare a nodeid with a numeric value. More...

BASE_EXPORT int	ua_nodeid_compare_string (const struct ua_nodeid a, uint16_t nsidx, const char value) UA_PURE_FUNCTION
	Convenience function to compare a nodeid with a string value. More...

BASE_EXPORT int	ua_nodeid_copy (struct ua_nodeid dst, const struct ua_nodeid src)
	Copy the ua_nodeid `src` to `dst`. More...

BASE_EXPORT bool	ua_nodeid_is_null (const struct ua_nodeid *id)
	Test if the nodeid `id` is a null nodeid according to Part 3, 8.2.4.

BASE_EXPORT int	ua_nodeid_to_string (const struct ua_nodeid id, struct ua_string dst) UA_WARN_UNUSED_RESULT
	Converts a nodeid into a UA string. More...

BASE_EXPORT int	ua_nodeid_snprintf (char dst, size_t size, const struct ua_nodeid id)
	Converts a nodeid into a string and writes the result into the given string buffer. More...

BASE_EXPORT int	ua_nodeid_from_string (struct ua_nodeid id, const struct ua_string src)
	Parses a nodeid string that was created using ua_nodeid_to_string. More...

BASE_EXPORT const char *	ua_nodeid_printable (const struct ua_nodeid *id)
	Return a printable representation of a nodeid. More...

Detailed Description

Identifier for UA nodes.

Identifier for a unique node in the addressspace of an OPC UA Server. The nodeid consists of the index for the namespace it belongs to and the actual identifier. The identifier can be one of the four types defined by the ua_identifiertype.

A Server shall persist the NodeId of a Node, that is, it is not allowed to generate new NodeIds when rebooting. The server is not allowed to change the namespace index for a namespace URI as long as the server is not restarted, but new namespaces can be added. The namespace index for a namespace URI may change after a server restart.

Clients must be prepared for changes of the namespace index in a NodeId and must persist their own namespace table together with the stored NodeIds for a server.

The following three elements identify a Node within a Server:

Name	Type	Description
namespaceIndex	UInt16	The index for a namespace URI used in an OPC UA server
identifierType	enum	The format and data type of the identifier
identifier	*	The identifier for a node in the address space of an OPC UA server

Namespace Index

The namespace is a URI that identifies the naming authority responsible for assigning the identifier element of the NodeId. Naming authorities include the local server, the underlying system, standards bodies and consortia. It is expected that most nodes will use the URI of the server or of the underlying system.

Using a namespace URI allows multiple OPC UA servers attached to the same underlying system to use the same identifier to identify the same object. This enables clients that connect to those Servers to recognise Objects that they have in common.

Namespace URIs are identified by numeric values in OPC UA services to permit more efficient transfer and processing (e.g. table lookups). The numeric values used to identify namespaces correspond to the index into the NamespaceArray. The NamespaceArray is a variable that is part of the Server object in the address space.

The URI for the OPC UA namespace is “http://opcfoundation.org/UA/”. Its corresponding index in the namespace table is 0.

The Namespace URI is case sensitive.

Identifier Type

The IdentifierType element identifies the type of the NodeId, its format and its scope. The following IdentifierTypes are available:

Value	Description
UA_IDENTIFIER_NUMERIC	Numeric value
UA_IDENTIFIER_STRING	String value
UA_IDENTIFIER_GUID	Globally Unique Identifier
UA_IDENTIFIER_OPAQUE	Namespace specific format in a ByteString

Identifier value

The identifier value element is used within the context of the first two elements to identify a node. Its data type and format is defined by the identifierType.

Numeric identifiers are typically used for static namespaces or for NodeIds in generated code. Such identifiers in generated code have typically defines generated which makes them easy to use and read in code.

String identifiers are typically used for nodes that are dynamically generated during system configuration. The string is either a path of nodes with a server specific delimiters or a server specific addressing schema contained in the string.

String identifiers are case sensitive. That is, clients shall consider them case sensitive. Servers are allowed to provide alternative NodeIds and using this mechanism severs can handle NodeIds as case insensitive.

Normally the scope of NodeIds is the server in which they are defined. For certain types of NodeIds, NodeIds can uniquely identify a Node within a system, or across systems (e.g. GUIDs). System-wide and globally-unique identifiers allow clients to track Nodes, such as work orders, as they move between OPC UA servers as they progress through the system.

Opaque identifiers are identifiers that are free-format byte strings that might or might not be human interpretable.

Identifier values of IdentifierType STRING are restricted to 4096 characters. Identifier values of IdentifierType OPAQUE are restricted to 4096 bytes.

A null NodeId has special meaning. For example, many services define special behaviour if a null NodeId is passed as a parameter. A null NodeId always has a NamespaceIndex equal to 0. A node in the address space cannot have a null NodeId. Each identifier type has a set of identifier values that represent a null NodeId:

Identifier Type	Identifier
NUMERIC	0
STRING	A null or Empty String (“”)
GUID	A Guid initialised with zeros (e.g. 00000000-0000-0000-0000-000000)
OPAQUE	A ByteString with Length=0

Macro Definition Documentation

◆ UA_NODEID_NUMERIC_INITIALIZER

#define UA_NODEID_NUMERIC_INITIALIZER	(	id,
		ns
	)	{ { id }, UA_IDENTIFIER_NUMERIC, ns }

Initializes a nodeid struct as numeric nodeid with identifier and namespace index.

Parameters

id	The numeric identifier.
ns	The namespace index.

Enumeration Type Documentation

◆ ua_identifiertype

enum ua_identifiertype

The set of known node identifier types.

Enumerator
UA_IDENTIFIER_NUMERIC	The identifier is a 32bit unsigned integer.
UA_IDENTIFIER_STRING	The identifier is a ua_string.
UA_IDENTIFIER_GUID	The identifier is a ua_guid.
UA_IDENTIFIER_OPAQUE	The identifier is a ua_bytestring.

Function Documentation

◆ ua_nodeid_attach_bytestring()

BASE_EXPORT int ua_nodeid_attach_bytestring	(	struct ua_nodeid *	id,
		uint16_t	nsindex,
		char *	value,
		int32_t	len
	)

Attach a bytestring value and set a namespace index for a nodeid.

This function takes ownership of value and frees it, when ua_nodeid_clear is called on that nodeid. Thus value must not be freed after attaching to the nodeid.

Parameters

id	Nodeid to attach the value.
nsindex	Namespace index to set.
value	Bytestring to attach.
len	Length of the bytestring to attach.

◆ ua_nodeid_attach_guid()

BASE_EXPORT void ua_nodeid_attach_guid	(	struct ua_nodeid *	id,
		uint16_t	nsindex,
		struct ua_guid *	value
	)

Attach a guid value and set a namespace index for a nodeid.

This function takes ownership of value and frees it, when ua_nodeid_clear is called on that nodeid. Thus value must not be freed after attaching to the nodeid.

Parameters

id	Nodeid to attach the value.
nsindex	Namespace index to set.
value	ua_guid to attach.

◆ ua_nodeid_attach_string()

BASE_EXPORT int ua_nodeid_attach_string	(	struct ua_nodeid *	id,
		uint16_t	nsindex,
		char *	value
	)

Attach a string value and set a namespace index for a nodeid.

This function takes ownership of value and frees it, when ua_nodeid_clear is called on that nodeid. Thus value must not be freed after attaching to the nodeid.

Parameters

id	Nodeid to attach the value.
nsindex	Namespace index to set.
value	Zero terminated string to attach.

◆ ua_nodeid_attach_string_const()

BASE_EXPORT int ua_nodeid_attach_string_const	(	struct ua_nodeid *	id,
		uint16_t	nsindex,
		const char *	value
	)

Attach a constant string value and set a namespace index for a nodeid.

This function takes ownership of value but does not free it, when ua_nodeid_clear is called on that nodeid. Thus only string literals should be passed as value. It is still necessary to call ua_nodeid_clear on the nodeid when it is no longer needed.

Parameters

id	Nodeid to attach the value.
nsindex	Namespace index to set.
value	Zero terminated string literal to attach.

◆ ua_nodeid_compare()

BASE_EXPORT int ua_nodeid_compare	(	const struct ua_nodeid *	a,
		const struct ua_nodeid *	b
	)

Compare two ua_nodeids.

Returns: Zero if the ua_nodeids are the same.

◆ ua_nodeid_compare_numeric()

BASE_EXPORT int ua_nodeid_compare_numeric	(	const struct ua_nodeid *	a,
		uint16_t	nsidx,
		uint32_t	value
	)

Convenience function to compare a nodeid with a numeric value.

Returns: Zero if nsdix and value match, non-zero value otherwise.

◆ ua_nodeid_compare_string()

BASE_EXPORT int ua_nodeid_compare_string	(	const struct ua_nodeid *	a,
		uint16_t	nsidx,
		const char *	value
	)

Convenience function to compare a nodeid with a string value.

Returns: Zero if nsdix and value match, non-zero value otherwise.

◆ ua_nodeid_copy()

BASE_EXPORT int ua_nodeid_copy	(	struct ua_nodeid *	dst,
		const struct ua_nodeid *	src
	)

Copy the ua_nodeid src to dst.

Returns: Zero on success or errorcode on failure.

◆ ua_nodeid_from_string()

BASE_EXPORT int ua_nodeid_from_string	(	struct ua_nodeid *	id,
		const struct ua_string *	src
	)

Parses a nodeid string that was created using ua_nodeid_to_string.

Parameters

id	Nodeid to fill with information from the string.
src	String containing a nodeid description. Only zero terminated strings are allowed, otherwise UA_EBADINVALIDARGUMENT is returned.

Returns

UA_EGOOD on success.
UA_EBADINVALIDARGUMENT for null-strings and empty strings.
UA_EBADDECODING if the string format is invalid.
UA_EBADNOMEM if memory allocation failed. Numeric Nodeids don't require memory allocation, all other types require one ipc_malloc call to create the internal string, guid or bytestring object.

See also: ua_nodeid_snprintf for mode information on the string format.

◆ ua_nodeid_printable()

BASE_EXPORT const char* ua_nodeid_printable ( const struct ua_nodeid * id )

Return a printable representation of a nodeid.

The returned string is intended for printing/tracing the nodeid, it is purely informative and you cannot rely on the format of the returned value. Also the string may be incomplete if the whole nodeid does not fit into the internal buffer.

The string is allocated in a static internal buffer, every call to this function overwrites the previously returned string. So to print multiple nodeids each must be printed in a separated statement or the returned string must be copied.

This function always returns a zero terminated string, which can be directly used for printing.

◆ ua_nodeid_set_bytestring()

BASE_EXPORT int ua_nodeid_set_bytestring	(	struct ua_nodeid *	id,
		uint16_t	nsindex,
		const char *	value,
		int32_t	len
	)

Set a bytestring value and namespace index for a nodeid.

This function creates a copy of value, that is attached to the nodeid and freed when ua_nodeid_clear is called on that nodeid.

Parameters

id	Nodeid to set the value.
nsindex	Namespace index to set.
value	Bytestring to set.
len	Length of the bytestring to set.

◆ ua_nodeid_set_guid()

BASE_EXPORT int ua_nodeid_set_guid	(	struct ua_nodeid *	id,
		uint16_t	nsindex,
		const struct ua_guid *	value
	)

Set a guid value and namespace index for a nodeid.

This function creates a copy of value, that is attached to the nodeid and freed when ua_nodeid_clear is called on that nodeid.

Parameters

id	Nodeid to set the value.
nsindex	Namespace index to set.
value	ua_guid to set.

◆ ua_nodeid_set_numeric()

BASE_EXPORT void ua_nodeid_set_numeric	(	struct ua_nodeid *	id,
		uint16_t	nsindex,
		uint32_t	value
	)

Set a numeric value and namespace index for a nodeid.

Parameters

id	Nodeid to set the value.
nsindex	Namespace index to set.
value	Numeric value to set.

◆ ua_nodeid_set_string()

BASE_EXPORT int ua_nodeid_set_string	(	struct ua_nodeid *	id,
		uint16_t	nsindex,
		const char *	value
	)

Set a string value and namespace index for a nodeid.

This function creates a copy of value, that is attached to the nodeid and freed when ua_nodeid_clear is called on that nodeid.

Parameters

id	Nodeid to set the value.
nsindex	Namespace index to set.
value	Zero terminated string to set.

◆ ua_nodeid_snprintf()

BASE_EXPORT int ua_nodeid_snprintf	(	char *	dst,
		size_t	size,
		const struct ua_nodeid *	id
	)

Converts a nodeid into a string and writes the result into the given string buffer.

The buffer must be pre-allocated by the caller.

If dst=NULL and size=0 the function returns the number of character that would be written. This is useful to get the required memory for the result. Don't forget to add one additional byte for the null terminator when allocating memory.

String format: [ ns=<nsidx>; ] i=<value> | s=<string> | g=<guid> | b=<bytestring
value: decimal encoded number
string: utf8 encoded string
guid: GUID as created by ua_guid_to_string (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
bytestrng: Base64 encoded data as created by ua_bytestring_to_string

For nsidx=0 the nsidx does not need to be encoded.

Examples:

Numeric: "i=85" which is equal to "ns=0;i=85"
String : "ns=2;s=Hello World"
Guid : "ns=2;g=382c74c3-721d-4f34-80e5-57657b6cbc27"
Opaque : "ns=2;b=SGVsbG8gV29ybGQ="

Parameters

dst	Pointer to string buffer.
size	Size of `dst` in bytes.
id	Nodeid to convert.

Returns: Zero on success. UA_EBADTRUNCATED if the string was truncated.

See also: ua_nodeid_to_string

◆ ua_nodeid_to_string()

BASE_EXPORT int ua_nodeid_to_string	(	const struct ua_nodeid *	id,
		struct ua_string *	dst
	)

Converts a nodeid into a UA string.

This function uses ua_nodeid_snprintf internally.

Parameters

id	Nodeid to convert.
dst	Pointer to UA string which receives the result. The function allocates the required memory automatically. Use ua_string_clear to cleanup the string.

Returns: Zero on success. UA_EBADNOMEM if the memory for the string could not be allocated.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ UA_NODEID_NUMERIC_INITIALIZER

Enumeration Type Documentation

◆ ua_identifiertype

Function Documentation

◆ ua_nodeid_attach_bytestring()

◆ ua_nodeid_attach_guid()

◆ ua_nodeid_attach_string()

◆ ua_nodeid_attach_string_const()

◆ ua_nodeid_compare()

◆ ua_nodeid_compare_numeric()

◆ ua_nodeid_compare_string()

◆ ua_nodeid_copy()

◆ ua_nodeid_from_string()

◆ ua_nodeid_printable()

◆ ua_nodeid_set_bytestring()

◆ ua_nodeid_set_guid()

◆ ua_nodeid_set_numeric()

◆ ua_nodeid_set_string()

◆ ua_nodeid_snprintf()

◆ ua_nodeid_to_string()