Create instances of objecttypes at runtime. More...

Data Structures
struct	ua_instance_pre_create2_info
	Information passed to ua_instance_pre_create2_cb. More...

struct	ua_instance_typedefinition_info
	Information passed to ua_instance_typedefinition_cb. More...

struct	ua_instance_reference_info
	Information passed to ua_instance_typedefinition_cb. More...

struct	ua_instance_ctx

Macros
#define	UA_INSTANCE_MAX_RECURSION_DEPTH 20
	Maximum default recursion depth.

#define	UA_INSTANCE_MAX_BROWSEPATH_LEN 20

Typedefs
typedef enum ua_instance_node_action(*	ua_instance_pre_create_cb) (struct ua_instance_ctx ctx, ua_node_t declaration_node, enum ua_nodeclass nc, enum ua_instance_modelling_rule m_rule, struct ua_nodeid nodeid)
	Called before creating a particular node to decide how to handle the node and optionally set a nodeid. More...

typedef enum ua_instance_node_action(*	ua_instance_pre_create2_cb) (struct ua_instance_ctx ctx, struct ua_instance_pre_create2_info info)
	Similar to ua_instance_pre_create_cb, but called for all modelling rules. More...

typedef ua_node_t(*	ua_instance_typedefinition_cb) (struct ua_instance_ctx ctx, struct ua_instance_typedefinition_info info)
	Determine the typedefinition to use for the instance of an instance declaration. More...

typedef int(*	ua_instance_reference_cb) (struct ua_instance_ctx ctx, struct ua_instance_reference_info info)
	Callback when encountering a non-hierarchical reference. More...

typedef int(*	ua_instance_post_create_cb) (struct ua_instance_ctx *ctx, ua_node_t new_node, ua_node_t declaration_node, enum ua_nodeclass nc)
	Called after node creation to give the caller of ua_instance_new the chance to alter attributes. More...

typedef int(*	ua_instance_delete_cb) (struct ua_instance_ctx *ctx, ua_node_t node)
	Called before a node is deleted in ua_instance_remove or in rollback of ua_instance_new. More...

Enumerations
enum	ua_instance_modelling_rule { UA_INSTANCE_MODELLING_RULE_NONE, UA_INSTANCE_MODELLING_RULE_OPTIONAL, UA_INSTANCE_MODELLING_RULE_MANDATORY, UA_INSTANCE_MODELLING_RULE_OTHER }
	Modelling rules relevant for instance creation, other modelling rules are ignored. More...

enum	ua_instance_node_action { UA_INSTANCE_NODE_IGNORE, UA_INSTANCE_NODE_COPY, UA_INSTANCE_NODE_REFERENCE, UA_INSTANCE_NODE_ABORT }
	Action how ua_instance_new should handle a particular node used as the result of the ua_instance_pre_create_cb. More...

enum	ua_instance_mode { UA_INSTANCE_MODE_CREATE, UA_INSTANCE_MODE_REFERENCES }

Functions
SERVER_EXPORT struct ua_instance_ctx *	ua_instance_ctx_create (void)
	Create a new instance context used for ua_instance_new and ua_instance_remove. More...

SERVER_EXPORT void	ua_instance_ctx_delete (struct ua_instance_ctx *ctx)
	Delete an instance context created with ua_instance_ctx_create.

SERVER_EXPORT int	ua_instance_new (struct ua_instance_ctx ctx, const struct ua_nodeid nodeid, ua_node_t type, uint16_t browsename_idx, const char browsename, const char displayname)
	Create an instance of a given objecttype. More...

SERVER_EXPORT int	ua_instance_remove (struct ua_instance_ctx *ctx, ua_node_t node)
	Remove an instance of any type. More...

SERVER_EXPORT ua_node_t	ua_instance_get_new_node (struct ua_instance_ctx *ctx)
	Get the top level node of the last created instance. More...

SERVER_EXPORT void	ua_instance_set_max_depth (struct ua_instance_ctx *ctx, uint8_t max_depth)
	Set the maximum recursion depth during instance creation. More...

SERVER_EXPORT void *	ua_instance_get_cb_data (struct ua_instance_ctx *ctx)
	Get the callback data.

SERVER_EXPORT void	ua_instance_set_cb_data (struct ua_instance_ctx ctx, void data)
	Set some arbitrary callback data, can be retrieved with ua_instance_get_cb_data.

SERVER_EXPORT void	ua_instance_set_pre_create_cb (struct ua_instance_ctx *ctx, ua_instance_pre_create_cb cb)
	Set the pre create callback. More...

SERVER_EXPORT void	ua_instance_set_pre_create2_cb (struct ua_instance_ctx *ctx, ua_instance_pre_create2_cb cb)
	Set the pre create 2 callback. More...

SERVER_EXPORT void	ua_instance_set_post_create_cb (struct ua_instance_ctx *ctx, ua_instance_post_create_cb cb)
	Set the post create callback. More...

SERVER_EXPORT void	ua_instance_set_typedefinition_cb (struct ua_instance_ctx *ctx, ua_instance_typedefinition_cb cb)
	Set the typedefinition callback. More...

SERVER_EXPORT void	ua_instance_set_reference_cb (struct ua_instance_ctx *ctx, ua_instance_reference_cb cb)
	Set the reference callback. More...

SERVER_EXPORT void	ua_instance_set_delete_cb (struct ua_instance_ctx *ctx, ua_instance_delete_cb cb)
	Set the delete callback. More...

SERVER_EXPORT void	ua_instance_set_parent (struct ua_instance_ctx *ctx, ua_node_t parent_node, ua_node_t ref_type)
	Set a parent for new instances. More...

SERVER_EXPORT uint32_t	ua_instance_get_last_numeric_id (struct ua_instance_ctx *ctx)
	Get the number used for the last created node with numeric nodeid. More...

SERVER_NO_EXPORT void	ua_instance_ctx_init (struct ua_instance_ctx *ctx)

SERVER_NO_EXPORT bool	ua_instance_is_hierarchical_referencetype (ua_node_t ref_type)

SERVER_NO_EXPORT enum ua_instance_modelling_rule	ua_instance_find_modelling_rule (ua_node_t node, ua_node_t *m_rule_other)

SERVER_NO_EXPORT int	ua_instance_find_node_with_browsename (ua_node_t parent, ua_node_t node, ua_node_t *child)

SERVER_NO_EXPORT int	ua_instance_reference_add (ua_node_t source, ua_node_t target, ua_node_t reference_type)

Detailed Description

Create instances of objecttypes at runtime.

Typedef Documentation

◆ ua_instance_delete_cb

typedef int(* ua_instance_delete_cb) (struct ua_instance_ctx *ctx, ua_node_t node)

Called before a node is deleted in ua_instance_remove or in rollback of ua_instance_new.

The parameters are the current instance context and the handle for the node to be deleted.

Must always return 0.

◆ ua_instance_post_create_cb

typedef int(* ua_instance_post_create_cb) (struct ua_instance_ctx *ctx, ua_node_t new_node, ua_node_t declaration_node, enum ua_nodeclass nc)

Called after node creation to give the caller of ua_instance_new the chance to alter attributes.

The input parameters are the current instance context, the handle for the newly created node, the handle for the instance declaration node (the node at the type) and the nodeclass of the new node.

Must return 0 on success, or errorcode to abort instance creation with that errorcode and clean up all previously created nodes.

◆ ua_instance_pre_create2_cb

typedef enum ua_instance_node_action(* ua_instance_pre_create2_cb) (struct ua_instance_ctx *ctx, struct ua_instance_pre_create2_info *info)

Similar to ua_instance_pre_create_cb, but called for all modelling rules.

Especially for the placeholder modelling rules this callback can be used to create the nodes from within the callback and return UA_INSTANCE_NODE_IGNORE to not replicate the placeholder itself.

◆ ua_instance_pre_create_cb

typedef enum ua_instance_node_action(* ua_instance_pre_create_cb) (struct ua_instance_ctx *ctx, ua_node_t declaration_node, enum ua_nodeclass nc, enum ua_instance_modelling_rule m_rule, struct ua_nodeid *nodeid)

Called before creating a particular node to decide how to handle the node and optionally set a nodeid.

Note: This callback is only called for instance declarations with the modelling rule optional or mandatory, to be called for other modelling rules and to get more information about the to be created node the ua_instance_pre_create2_cb callback can be used. If ua_instance_pre_create2_cb is set this callback will no longer be called.

As input parameters the current instance context, the handle for the instance declaration node (the node at the type), the nodeclass of the declaration node and the modelling rule of the declaration node. The nodeid is an output parameter, which is set to a null nodeid initially, if the function sets this to a valid nodeid it will be used for the instance node, else a new nodeid will be generated automatically. If any memory is allocated in the nodeid parameter it will be cleared by the caller.

When this callback is not set, optional nodes are being ignored. For mandatory nodes, method nodes are referenced, node of other nodeclasses are copied.

◆ ua_instance_reference_cb

typedef int(* ua_instance_reference_cb) (struct ua_instance_ctx *ctx, struct ua_instance_reference_info *info)

Callback when encountering a non-hierarchical reference.

When the SDK encounters a non-hierarchical reference at an instance declaration it tries to determine an analogous reference for the currently created instance and calls this callback. The callee may return zero to confirm the creation of the reference or UA_EBADNOTHINGTODO for the reference not to be created. Other return values are reserved and not allowed at the moment.

◆ ua_instance_typedefinition_cb

typedef ua_node_t(* ua_instance_typedefinition_cb) (struct ua_instance_ctx *ctx, struct ua_instance_typedefinition_info *info)

Determine the typedefinition to use for the instance of an instance declaration.

Instance declarations might have typedefinitions itself, in this case it might be preferable to replicate this node on the instance with a different typedefinition (e.g. a subtype of the original typedefinition) and run the full instancing algorithm on the newly created node.

When an instance declaration with typedefinition is encountered this callback is called, returning a valid node handle results in running the instancing algorithm on the newly created node with the returned node as typedefinition. The returned node might be a subtype of the original typedefinition or the original typedefinition itself. If UA_NODE_INVALID is returned no additional instance creation is started and the original typedefinition is set as typedefinition of the new node.

If the returned node is a valid node handle it must also be a valid type node in the context of the instance, ususally only the proposed type and subtypes of that type are allowed. However the SDK has no further checks regarding returned type, so the callback implementation is responsible for returning the handle to a correct node.

Enumeration Type Documentation

◆ ua_instance_mode

enum ua_instance_mode

Enumerator
UA_INSTANCE_MODE_CREATE	traverse to create instance nodes
UA_INSTANCE_MODE_REFERENCES	traverse to handle non-hierarchical references

◆ ua_instance_modelling_rule

enum ua_instance_modelling_rule

Modelling rules relevant for instance creation, other modelling rules are ignored.

Enumerator
UA_INSTANCE_MODELLING_RULE_NONE	indicates a node has no modelling rule at all
UA_INSTANCE_MODELLING_RULE_OPTIONAL	modelling rule optional (ns=0;i=80)
UA_INSTANCE_MODELLING_RULE_MANDATORY	modelling rule mandatory (ns=0;i=78)
UA_INSTANCE_MODELLING_RULE_OTHER	any other modelling rule like optional/mandatory placeholder

◆ ua_instance_node_action

enum ua_instance_node_action

Action how ua_instance_new should handle a particular node used as the result of the ua_instance_pre_create_cb.

Enumerator
UA_INSTANCE_NODE_IGNORE	ignore node, do not copy or reference that node or any child node of that node
UA_INSTANCE_NODE_COPY	create a copy of that node and process all child nodes recursively
UA_INSTANCE_NODE_REFERENCE	create a reference to the original node
UA_INSTANCE_NODE_ABORT	abort instance creation with the error UA_EBADOPCANCELLED, cleans up all previously created nodes of this instance

Function Documentation

◆ ua_instance_ctx_create()

SERVER_EXPORT struct ua_instance_ctx* ua_instance_ctx_create ( void )

Create a new instance context used for ua_instance_new and ua_instance_remove.

A single context can be used for multiple operations, when it is no longer needed it must be deleted with ua_instance_ctx_delete.

Returns: Newly created instance context or NULL on error.

◆ ua_instance_get_last_numeric_id()

SERVER_EXPORT uint32_t ua_instance_get_last_numeric_id ( struct ua_instance_ctx * ctx )

Get the number used for the last created node with numeric nodeid.

May be used to calculate the nodeid for the next instance without gaps, however only the numeric part is returned, so the namespace index must still be set.

In case no node with numeric nodeid was ever created with this ctx it returns zero.

◆ ua_instance_get_new_node()

SERVER_EXPORT ua_node_t ua_instance_get_new_node ( struct ua_instance_ctx * ctx )

Get the top level node of the last created instance.

Returns UA_NODE_INVALID if no instance was created or instance creation failed.

◆ ua_instance_new()

SERVER_EXPORT int ua_instance_new	(	struct ua_instance_ctx *	ctx,
		const struct ua_nodeid *	nodeid,
		ua_node_t	type,
		uint16_t	browsename_idx,
		const char *	browsename,
		const char *	displayname
	)

Create an instance of a given objecttype.

The nodeids for the child nodes are generated dynamically and depend on nodeid. If nodeid is a string identifier the new nodes are concatenations of this string with the browsename of the child node. If nodeid is a numeric identifier the nodeid is incremented for each child. Guid identifiers are generated randomly for each new child node. Opaque identifiers are not supported for nodeid.

The top level node of the newly created instance can be retrieved with ua_instance_get_new_node. If the instance should be referenced by another node ua_instance_set_parent can be used.

Parameters

ctx	The ua_instance context.
nodeid	Nodeid the new instance should have. Must not exist yet.
type	The type of the new instance.
browsename	Browsename for the new node, no browsename is set if NULL.
browsename_idx	Namespace index for the browsename of the new node.
displayname	Displayname for the new node, not displayname is set if NULL.

Returns: Zero on success or negative errorcode on failure.

◆ ua_instance_remove()

SERVER_EXPORT int ua_instance_remove	(	struct ua_instance_ctx *	ctx,
		ua_node_t	node
	)

Remove an instance of any type.

Removes the node node and all its hierachical referenced subnodes and all references from or to these nodes.

Nodes with modelling rules will not be removed as these are most likely part of the instance declaration.

The instance context may be omitted for this function, in this case no callbacks are invoked.

Note: If additional nodes were added to the instance these will also be deleted and if there is a hierachical reference to the root node your complete addressspace might be deleted.

◆ ua_instance_set_delete_cb()

SERVER_EXPORT void ua_instance_set_delete_cb	(	struct ua_instance_ctx *	ctx,
		ua_instance_delete_cb	cb
	)

Set the delete callback.

For further information regarding the callback see ua_instance_delete_cb.

◆ ua_instance_set_max_depth()

SERVER_EXPORT void ua_instance_set_max_depth	(	struct ua_instance_ctx *	ctx,
		uint8_t	max_depth
	)

Set the maximum recursion depth during instance creation.

The default value is UA_INSTANCE_MAX_RECURSION_DEPTH.

◆ ua_instance_set_parent()

SERVER_EXPORT void ua_instance_set_parent	(	struct ua_instance_ctx *	ctx,
		ua_node_t	parent_node,
		ua_node_t	ref_type
	)

Set a parent for new instances.

When setting a parent, a new reference from the parent node to the top level node of the newly created instance will be created after instantiation.

To unset the parent pass UA_NODE_INVALID as parent node and reference type.

Parameters

ctx	The ua_instance context to modify.
parent_node	Node handle of the parent node.
ref_type	Node handle of the reference type from the parent node to the new instance.

◆ ua_instance_set_post_create_cb()

SERVER_EXPORT void ua_instance_set_post_create_cb	(	struct ua_instance_ctx *	ctx,
		ua_instance_post_create_cb	cb
	)

Set the post create callback.

For further information regarding the callback see ua_instance_post_create_cb.

◆ ua_instance_set_pre_create2_cb()

SERVER_EXPORT void ua_instance_set_pre_create2_cb	(	struct ua_instance_ctx *	ctx,
		ua_instance_pre_create2_cb	cb
	)

Set the pre create 2 callback.

For further information regarding the callback see ua_instance_pre_create2_cb.

◆ ua_instance_set_pre_create_cb()

SERVER_EXPORT void ua_instance_set_pre_create_cb	(	struct ua_instance_ctx *	ctx,
		ua_instance_pre_create_cb	cb
	)

Set the pre create callback.

Note: This callback is not called if ua_instance_pre_create2_cb is set.

For further information regarding the callback see ua_instance_pre_create_cb.

◆ ua_instance_set_reference_cb()

SERVER_EXPORT void ua_instance_set_reference_cb	(	struct ua_instance_ctx *	ctx,
		ua_instance_reference_cb	cb
	)

Set the reference callback.

For further information regarding the callback see ua_instance_reference_cb. If the callback is not set, the behavior is not to create non-hierarchical references.

The callback must be set before calling ua_instance_new, otherwise it may not be called.

◆ ua_instance_set_typedefinition_cb()

SERVER_EXPORT void ua_instance_set_typedefinition_cb	(	struct ua_instance_ctx *	ctx,
		ua_instance_typedefinition_cb	cb
	)

Set the typedefinition callback.

For further information regarding the callback see ua_instance_typedefinition_cb. If the callback is not set, the behavior is like a callback that always returns UA_NODE_INVALID.

Data Structures

Macros

Typedefs

Enumerations

Functions