Information Modelling¶
Information modelling in OPC UA combines concepts from object-orientation and semantic modelling. At the core, an OPC UA information model is a graph made up of
- Nodes: There are eight possible Node types (variable, object, method, …)
- References: Typed and directed relations between two nodes
Every node is identified by a unique (within the server) NodeId.
Reference are triples of the form (source-nodeid, referencetype-nodeid,
target-nodeid). An example reference between nodes is a
hasTypeDefinition reference between a Variable and its VariableType. Some
ReferenceTypes are hierarchic and must not form directed loops. See the
section on ReferenceTypes for more details on
possible references and their semantics.
Warning!! The structures defined in this section are only relevant for the developers of custom Nodestores. The interaction with the information model is possible only via the OPC UA Services. So the following sections are purely informational so that users may have a clear mental model of the underlying representation.
Node Lifecycle: Constructors, Destructors and Node Contexts¶
To finalize the instantiation of a node, a (user-defined) constructor callback is executed. There can be both a global constructor for all nodes and node-type constructor specific to the TypeDefinition of the new node (attached to an ObjectTypeNode or VariableTypeNode).
In the hierarchy of ObjectTypes and VariableTypes, only the constructor of
the (lowest) type defined for the new node is executed. Note that every
Object and Variable can have only one isTypeOf reference. But type-nodes
can technically have several hasSubType references to implement multiple
inheritance. Issues of (multiple) inheritance in the constructor need to be
solved by the user.
When a node is destroyed, the node-type destructor is called before the global destructor. So the overall node lifecycle is as follows:
- Global Constructor (set in the server config)
- Node-Type Constructor (for VariableType or ObjectTypes)
- (Usage-period of the Node)
- Node-Type Destructor
- Global Destructor
The constructor and destructor callbacks can be set to NULL and are not
used in that case. If the node-type constructor fails, the global destructor
will be called before removing the node. The destructors are assumed to never
fail.
Every node carries a user-context and a constructor-context pointer. The
user-context is used to attach custom data to a node. But the (user-defined)
constructors and destructors may replace the user-context pointer if they
wish to do so. The initial value for the constructor-context is NULL.
When the AddNodes service is used over the network, the user-context
pointer of the new node is also initially set to NULL.
Global Node Lifecycle¶
Global constructor and destructor callbacks used for every node type. To be set in the server config.
typedef struct {
/* Can be NULL. May replace the nodeContext */
UA_StatusCode (*constructor)(UA_Server *server,
const UA_NodeId *sessionId, void *sessionContext,
const UA_NodeId *nodeId, void **nodeContext);
/* Can be NULL. The context cannot be replaced since the node is destroyed
* immediately afterwards anyway. */
void (*destructor)(UA_Server *server,
const UA_NodeId *sessionId, void *sessionContext,
const UA_NodeId *nodeId, void *nodeContext);
/* Can be NULL. Called during recursive node instantiation. While mandatory
* child nodes are automatically created if not already present, optional child
* nodes are not. This callback can be used to define whether an optional child
* node should be created.
*
* @param server The server executing the callback
* @param sessionId The identifier of the session
* @param sessionContext Additional data attached to the session in the
* access control layer
* @param sourceNodeId Source node from the type definition. If the new node
* shall be created, it will be a copy of this node.
* @param targetParentNodeId Parent of the potential new child node
* @param referenceTypeId Identifies the reference type which that the parent
* node has to the new node.
* @return Return UA_TRUE if the child node shall be instantiated,
* UA_FALSE otherwise. */
UA_Boolean (*createOptionalChild)(UA_Server *server,
const UA_NodeId *sessionId,
void *sessionContext,
const UA_NodeId *sourceNodeId,
const UA_NodeId *targetParentNodeId,
const UA_NodeId *referenceTypeId);
/* Can be NULL. Called when a node is to be copied during recursive
* node instantiation. Allows definition of the NodeId for the new node.
* If the callback is set to NULL or the resulting NodeId is UA_NODEID_NUMERIC(X,0)
* an unused nodeid in namespace X will be used. E.g. passing UA_NODEID_NULL will
* result in a NodeId in namespace 0.
*
* @param server The server executing the callback
* @param sessionId The identifier of the session
* @param sessionContext Additional data attached to the session in the
* access control layer
* @param sourceNodeId Source node of the copy operation
* @param targetParentNodeId Parent node of the new node
* @param referenceTypeId Identifies the reference type which that the parent
* node has to the new node. */
UA_StatusCode (*generateChildNodeId)(UA_Server *server,
const UA_NodeId *sessionId, void *sessionContext,
const UA_NodeId *sourceNodeId,
const UA_NodeId *targetParentNodeId,
const UA_NodeId *referenceTypeId,
UA_NodeId *targetNodeId);
} UA_GlobalNodeLifecycle;
Node Type Lifecycle¶
Constructor and destructors for specific object and variable types.
typedef struct {
/* Can be NULL. May replace the nodeContext */
UA_StatusCode (*constructor)(UA_Server *server,
const UA_NodeId *sessionId, void *sessionContext,
const UA_NodeId *typeNodeId, void *typeNodeContext,
const UA_NodeId *nodeId, void **nodeContext);
/* Can be NULL. May replace the nodeContext. */
void (*destructor)(UA_Server *server,
const UA_NodeId *sessionId, void *sessionContext,
const UA_NodeId *typeNodeId, void *typeNodeContext,
const UA_NodeId *nodeId, void **nodeContext);
} UA_NodeTypeLifecycle;
ReferenceType Bitfield Representation¶
ReferenceTypes have an alternative represention as an index into a bitfield for fast comparison. The index is generated when the corresponding ReferenceTypeNode is added. By bounding the number of ReferenceTypes that can exist in the server, the bitfield can represent a set of an combination of ReferenceTypes.
Every ReferenceTypeNode contains a bitfield with the set of all its subtypes. This speeds up the Browse services substantially.
The following ReferenceTypes have a fixed index. The NS0 bootstrapping creates these ReferenceTypes in-order.
#define UA_REFERENCETYPEINDEX_REFERENCES 0
#define UA_REFERENCETYPEINDEX_HASSUBTYPE 1
#define UA_REFERENCETYPEINDEX_AGGREGATES 2
#define UA_REFERENCETYPEINDEX_HIERARCHICALREFERENCES 3
#define UA_REFERENCETYPEINDEX_NONHIERARCHICALREFERENCES 4
#define UA_REFERENCETYPEINDEX_HASCHILD 5
#define UA_REFERENCETYPEINDEX_ORGANIZES 6
#define UA_REFERENCETYPEINDEX_HASEVENTSOURCE 7
#define UA_REFERENCETYPEINDEX_HASMODELLINGRULE 8
#define UA_REFERENCETYPEINDEX_HASENCODING 9
#define UA_REFERENCETYPEINDEX_HASDESCRIPTION 10
#define UA_REFERENCETYPEINDEX_HASTYPEDEFINITION 11
#define UA_REFERENCETYPEINDEX_GENERATESEVENT 12
#define UA_REFERENCETYPEINDEX_HASPROPERTY 13
#define UA_REFERENCETYPEINDEX_HASCOMPONENT 14
#define UA_REFERENCETYPEINDEX_HASNOTIFIER 15
#define UA_REFERENCETYPEINDEX_HASORDEREDCOMPONENT 16
#define UA_REFERENCETYPEINDEX_HASINTERFACE 17
/* The maximum number of ReferrenceTypes. Must be a multiple of 32. */
#define UA_REFERENCETYPESET_MAX 128
typedef struct { UA_UInt32 bits[UA_REFERENCETYPESET_MAX / 32]; } UA_ReferenceTypeSet;
static UA_INLINE void
UA_ReferenceTypeSet_init(UA_ReferenceTypeSet *set) {
memset(set, 0, sizeof(UA_ReferenceTypeSet));
}
static UA_INLINE void
UA_ReferenceTypeSet_any(UA_ReferenceTypeSet *set) {
memset(set, -1, sizeof(UA_ReferenceTypeSet));
}
static UA_INLINE UA_ReferenceTypeSet
UA_REFTYPESET(UA_Byte index) {
UA_Byte i = index / 32, j = index % 32;
UA_ReferenceTypeSet set;
UA_ReferenceTypeSet_init(&set);
set.bits[i] |= ((UA_UInt32)1) << j;
return set;
}
static UA_INLINE UA_ReferenceTypeSet
UA_ReferenceTypeSet_union(const UA_ReferenceTypeSet setA,
const UA_ReferenceTypeSet setB) {
UA_ReferenceTypeSet set;
for(size_t i = 0; i < UA_REFERENCETYPESET_MAX / 32; i++)
set.bits[i] = setA.bits[i] | setB.bits[i];
return set;
}
static UA_INLINE UA_Boolean
UA_ReferenceTypeSet_contains(const UA_ReferenceTypeSet *set, UA_Byte index) {
UA_Byte i = index / 32, j = index % 32;
return !!(set->bits[i] & (((UA_UInt32)1) << j));
}
Node Pointer¶
The “native” format for reference between nodes is the ExpandedNodeId. That is, references can also point to external servers. In practice, most references point to local nodes using numerical NodeIds from the standard-defined namespace zero. In order to save space (and time), pointer-tagging is used for compressed “NodePointer” representations. Numerical NodeIds are immediately contained in the pointer. Full NodeIds and ExpandedNodeIds are behind a pointer indirection. If the Nodestore supports it, a NodePointer can also be an actual pointer to the target node.
Depending on the processor architecture, some numerical NodeIds don’t fit into an immediate encoding and are kept as pointers. ExpandedNodeIds may be internally translated to “normal” NodeIds. Use the provided functions to generate NodePointers that fit the assumptions for the local architecture.
/* Forward declaration. All node structures begin with the NodeHead. */
struct UA_NodeHead;
typedef struct UA_NodeHead UA_NodeHead;
/* Tagged Pointer structure. */
typedef union {
uintptr_t immediate; /* 00: Small numerical NodeId */
const UA_NodeId *id; /* 01: Pointer to NodeId */
const UA_ExpandedNodeId *expandedId; /* 10: Pointer to ExternalNodeId */
const UA_NodeHead *node; /* 11: Pointer to a node */
} UA_NodePointer;
/* Sets the pointer to an immediate NodeId "ns=0;i=0" similar to a freshly
* initialized UA_NodeId */
static UA_INLINE void
UA_NodePointer_init(UA_NodePointer *np) { np->immediate = 0; }
/* NodeId and ExpandedNodeId targets are freed */
void
UA_NodePointer_clear(UA_NodePointer *np);
/* Makes a deep copy */
UA_StatusCode
UA_NodePointer_copy(UA_NodePointer in, UA_NodePointer *out);
/* Test if an ExpandedNodeId or a local NodeId */
UA_Boolean
UA_NodePointer_isLocal(UA_NodePointer np);
UA_Order
UA_NodePointer_order(UA_NodePointer p1, UA_NodePointer p2);
static UA_INLINE UA_Boolean
UA_NodePointer_equal(UA_NodePointer p1, UA_NodePointer p2) {
return (UA_NodePointer_order(p1, p2) == UA_ORDER_EQ);
}
/* Cannot fail. The resulting NodePointer can point to the memory from the
* NodeId. Make a deep copy if required. */
UA_NodePointer
UA_NodePointer_fromNodeId(const UA_NodeId *id);
/* Cannot fail. The resulting NodePointer can point to the memory from the
* ExpandedNodeId. Make a deep copy if required. */
UA_NodePointer
UA_NodePointer_fromExpandedNodeId(const UA_ExpandedNodeId *id);
/* Can point to the memory from the NodePointer */
UA_ExpandedNodeId
UA_NodePointer_toExpandedNodeId(UA_NodePointer np);
/* Can point to the memory from the NodePointer. Discards the ServerIndex and
* NamespaceUri of a potential ExpandedNodeId inside the NodePointer. Test
* before if the NodePointer is local. */
UA_NodeId
UA_NodePointer_toNodeId(UA_NodePointer np);
Base Node Attributes¶
Nodes contain attributes according to their node type. The base node attributes are common to all node types. In the OPC UA Services, attributes are referred to via the NodeId of the containing node and an integer Attribute Id.
Internally, open62541 uses UA_Node in places where the exact node type is
not known or not important. The nodeClass attribute is used to ensure the
correctness of casting from UA_Node to a specific node type.
typedef struct {
UA_NodePointer targetId; /* Has to be the first entry */
UA_UInt32 targetNameHash; /* Hash of the target's BrowseName. Set to zero
* if the target is remote. */
} UA_ReferenceTarget;
typedef struct {
UA_ReferenceTarget target; /* Has to be the first entry */
UA_UInt32 targetIdHash; /* Hash of the targetId */
struct aa_entry idTreeEntry; /* Binary-Tree for fast lookup */
struct aa_entry nameTreeEntry;
} UA_ReferenceTargetTreeElem;
/* List of reference targets with the same reference type and direction. Uses
* either an array or a tree structure. The SDK will not change the type of
* reference target structure internally. The nodestore implementations may
* switch internally when a node is updated.
*
* The recommendation is to switch to a tree once the number of refs > 8. */
typedef struct {
union {
/* Organize the references in an array. Uses less memory, but incurs
* lookups in linear time. Recommended if the number of references is
* known to be small. */
UA_ReferenceTarget *array;
/* Organize the references in a tree for fast lookup */
struct {
struct aa_entry *idTreeRoot; /* Fast lookup based on the target id */
struct aa_entry *nameTreeRoot; /* Fast lookup based on the target browseName*/
} tree;
} targets;
size_t targetsSize;
UA_Boolean hasRefTree; /* RefTree or RefArray? */
UA_Byte referenceTypeIndex;
UA_Boolean isInverse;
} UA_NodeReferenceKind;
/* Iterate over the references. Assumes that "prev" points to a
* NodeReferenceKind. If prev == NULL, the first element is returned. At the end
* of the iteration, NULL is returned.
*
* Do not continue the iteration after the rk was modified. */
const UA_ReferenceTarget *
UA_NodeReferenceKind_iterate(const UA_NodeReferenceKind *rk,
const UA_ReferenceTarget *prev);
/* Switch between array and tree representation. Does nothing upon error (e.g.
* out-of-memory). */
UA_StatusCode
UA_NodeReferenceKind_switch(UA_NodeReferenceKind *rk);
/* Every Node starts with these attributes */
struct UA_NodeHead {
UA_NodeId nodeId;
UA_NodeClass nodeClass;
UA_QualifiedName browseName;
UA_LocalizedText displayName;
UA_LocalizedText description;
UA_UInt32 writeMask;
size_t referencesSize;
UA_NodeReferenceKind *references;
/* Members specific to open62541 */
void *context;
UA_Boolean constructed; /* Constructors were called */
#ifdef UA_ENABLE_SUBSCRIPTIONS
UA_MonitoredItem *monitoredItems; /* MonitoredItems for Events and immediate
* DataChanges (no sampling interval). */
#endif
};
VariableNode¶
Variables store values in a DataValue together with metadata for introspection. Most notably, the attributes data type, value rank and array dimensions constrain the possible values the variable can take on.
Variables come in two flavours: properties and datavariables. Properties are
related to a parent with a hasProperty reference and may not have child
nodes themselves. Datavariables may contain properties (hasProperty) and
also datavariables (hasComponents).
All variables are instances of some VariableTypeNode in return constraining the possible data type, value rank and array dimensions attributes.
Data Type¶
The (scalar) data type of the variable is constrained to be of a specific type or one of its children in the type hierarchy. The data type is given as a NodeId pointing to a DataTypeNode in the type hierarchy. See the Section DataTypeNode for more details.
If the data type attribute points to UInt32, then the value attribute
must be of that exact type since UInt32 does not have children in the
type hierarchy. If the data type attribute points Number, then the type
of the value attribute may still be UInt32, but also Float or
Byte.
Consistency between the data type attribute in the variable and its VariableTypeNode is ensured.
Value Rank¶
This attribute indicates whether the value attribute of the variable is an array and how many dimensions the array has. It may have the following values:
n >= 1: the value is an array with the specified number of dimensionsn = 0: the value is an array with one or more dimensionsn = -1: the value is a scalarn = -2: the value can be a scalar or an array with any number of dimensionsn = -3: the value can be a scalar or a one dimensional array
Consistency between the value rank attribute in the variable and its VariableTypeNode is ensured.
Array Dimensions¶
If the value rank permits the value to be a (multi-dimensional) array, the exact length in each dimensions can be further constrained with this attribute.
- For positive lengths, the variable value is guaranteed to be of the same length in this dimension.
- The dimension length zero is a wildcard and the actual value may have any length in this dimension.
Consistency between the array dimensions attribute in the variable and its VariableTypeNode is ensured.
/* Indicates whether a variable contains data inline or whether it points to an
* external data source */
typedef enum {
UA_VALUESOURCE_DATA,
UA_VALUESOURCE_DATASOURCE
} UA_ValueSource;
typedef struct {
/* Called before the value attribute is read. It is possible to write into the
* value attribute during onRead (using the write service). The node is
* re-opened afterwards so that changes are considered in the following read
* operation.
*
* @param handle Points to user-provided data for the callback.
* @param nodeid The identifier of the node.
* @param data Points to the current node value.
* @param range Points to the numeric range the client wants to read from
* (or NULL). */
void (*onRead)(UA_Server *server, const UA_NodeId *sessionId,
void *sessionContext, const UA_NodeId *nodeid,
void *nodeContext, const UA_NumericRange *range,
const UA_DataValue *value);
/* Called after writing the value attribute. The node is re-opened after
* writing so that the new value is visible in the callback.
*
* @param server The server executing the callback
* @sessionId The identifier of the session
* @sessionContext Additional data attached to the session
* in the access control layer
* @param nodeid The identifier of the node.
* @param nodeUserContext Additional data attached to the node by
* the user.
* @param nodeConstructorContext Additional data attached to the node
* by the type constructor(s).
* @param range Points to the numeric range the client wants to write to (or
* NULL). */
void (*onWrite)(UA_Server *server, const UA_NodeId *sessionId,
void *sessionContext, const UA_NodeId *nodeId,
void *nodeContext, const UA_NumericRange *range,
const UA_DataValue *data);
} UA_ValueCallback;
typedef struct {
/* Copies the data from the source into the provided value.
*
* !! ZERO-COPY OPERATIONS POSSIBLE !!
* It is not required to return a copy of the actual content data. You can
* return a pointer to memory owned by the user. Memory can be reused
* between read callbacks of a DataSource, as the result is already encoded
* on the network buffer between each read operation.
*
* To use zero-copy reads, set the value of the `value->value` Variant
* without copying, e.g. with `UA_Variant_setScalar`. Then, also set
* `value->value.storageType` to `UA_VARIANT_DATA_NODELETE` to prevent the
* memory being cleaned up. Don't forget to also set `value->hasValue` to
* true to indicate the presence of a value.
*
* @param server The server executing the callback
* @param sessionId The identifier of the session
* @param sessionContext Additional data attached to the session in the
* access control layer
* @param nodeId The identifier of the node being read from
* @param nodeContext Additional data attached to the node by the user
* @param includeSourceTimeStamp If true, then the datasource is expected to
* set the source timestamp in the returned value
* @param range If not null, then the datasource shall return only a
* selection of the (nonscalar) data. Set
* UA_STATUSCODE_BADINDEXRANGEINVALID in the value if this does not
* apply
* @param value The (non-null) DataValue that is returned to the client. The
* data source sets the read data, the result status and optionally a
* sourcetimestamp.
* @return Returns a status code for logging. Error codes intended for the
* original caller are set in the value. If an error is returned,
* then no releasing of the value is done
*/
UA_StatusCode (*read)(UA_Server *server, const UA_NodeId *sessionId,
void *sessionContext, const UA_NodeId *nodeId,
void *nodeContext, UA_Boolean includeSourceTimeStamp,
const UA_NumericRange *range, UA_DataValue *value);
/* Write into a data source. This method pointer can be NULL if the
* operation is unsupported.
*
* @param server The server executing the callback
* @param sessionId The identifier of the session
* @param sessionContext Additional data attached to the session in the
* access control layer
* @param nodeId The identifier of the node being written to
* @param nodeContext Additional data attached to the node by the user
* @param range If not NULL, then the datasource shall return only a
* selection of the (nonscalar) data. Set
* UA_STATUSCODE_BADINDEXRANGEINVALID in the value if this does not
* apply
* @param value The (non-NULL) DataValue that has been written by the client.
* The data source contains the written data, the result status and
* optionally a sourcetimestamp
* @return Returns a status code for logging. Error codes intended for the
* original caller are set in the value. If an error is returned,
* then no releasing of the value is done
*/
UA_StatusCode (*write)(UA_Server *server, const UA_NodeId *sessionId,
void *sessionContext, const UA_NodeId *nodeId,
void *nodeContext, const UA_NumericRange *range,
const UA_DataValue *value);
} UA_DataSource;
Value Callback¶
Value Callbacks can be attached to variable and variable type nodes. If
not NULL, they are called before reading and after writing respectively.
typedef struct {
/* Called before the value attribute is read. The external value source can be
* be updated and/or locked during this notification call. After this function returns
* to the core, the external value source is readed immediately.
*/
UA_StatusCode (*notificationRead)(UA_Server *server, const UA_NodeId *sessionId,
void *sessionContext, const UA_NodeId *nodeid,
void *nodeContext, const UA_NumericRange *range);
/* Called after writing the value attribute. The node is re-opened after
* writing so that the new value is visible in the callback.
*
* @param server The server executing the callback
* @sessionId The identifier of the session
* @sessionContext Additional data attached to the session
* in the access control layer
* @param nodeid The identifier of the node.
* @param nodeUserContext Additional data attached to the node by
* the user.
* @param nodeConstructorContext Additional data attached to the node
* by the type constructor(s).
* @param range Points to the numeric range the client wants to write to (or
* NULL). */
UA_StatusCode (*userWrite)(UA_Server *server, const UA_NodeId *sessionId,
void *sessionContext, const UA_NodeId *nodeId,
void *nodeContext, const UA_NumericRange *range,
const UA_DataValue *data);
} UA_ExternalValueCallback;
typedef enum {
UA_VALUEBACKENDTYPE_NONE,
UA_VALUEBACKENDTYPE_INTERNAL,
UA_VALUEBACKENDTYPE_DATA_SOURCE_CALLBACK,
UA_VALUEBACKENDTYPE_EXTERNAL
} UA_ValueBackendType;
typedef struct {
UA_ValueBackendType backendType;
union {
struct {
UA_DataValue value;
UA_ValueCallback callback;
} internal;
UA_DataSource dataSource;
struct {
UA_DataValue **value;
UA_ExternalValueCallback callback;
} external;
} backend;
} UA_ValueBackend;
#define UA_NODE_VARIABLEATTRIBUTES \
/* Constraints on possible values */ \
UA_NodeId dataType; \
UA_Int32 valueRank; \
size_t arrayDimensionsSize; \
UA_UInt32 *arrayDimensions; \
\
UA_ValueBackend valueBackend; \
\
/* The current value */ \
UA_ValueSource valueSource; \
union { \
struct { \
UA_DataValue value; \
UA_ValueCallback callback; \
} data; \
UA_DataSource dataSource; \
} value;
typedef struct {
UA_NodeHead head;
UA_NODE_VARIABLEATTRIBUTES
UA_Byte accessLevel;
UA_Double minimumSamplingInterval;
UA_Boolean historizing;
/* Members specific to open62541 */
UA_Boolean isDynamic; /* Some variables are "static" in the sense that they
* are not attached to a dynamic process in the
* background. Only dynamic variables conserve source
* and server timestamp for the value attribute.
* Static variables have timestamps of "now". */
} UA_VariableNode;
VariableTypeNode¶
VariableTypes are used to provide type definitions for variables.
VariableTypes constrain the data type, value rank and array dimensions
attributes of variable instances. Furthermore, instantiating from a specific
variable type may provide semantic information. For example, an instance from
MotorTemperatureVariableType is more meaningful than a float variable
instantiated from BaseDataVariable.
typedef struct {
UA_NodeHead head;
UA_NODE_VARIABLEATTRIBUTES
UA_Boolean isAbstract;
/* Members specific to open62541 */
UA_NodeTypeLifecycle lifecycle;
} UA_VariableTypeNode;
MethodNode¶
Methods define callable functions and are invoked using the Call service. MethodNodes may have special properties (variable
children with a hasProperty reference) with the QualifiedName (0,
"InputArguments") and (0, "OutputArguments"). The input and output
arguments are both described via an array of UA_Argument. While the Call
service uses a generic array of Variant for input and output, the
actual argument values are checked to match the signature of the MethodNode.
Note that the same MethodNode may be referenced from several objects (and object types). For this, the NodeId of the method and of the object providing context is part of a Call request message.
typedef UA_StatusCode
(*UA_MethodCallback)(UA_Server *server, const UA_NodeId *sessionId,
void *sessionContext, const UA_NodeId *methodId,
void *methodContext, const UA_NodeId *objectId,
void *objectContext, size_t inputSize,
const UA_Variant *input, size_t outputSize,
UA_Variant *output);
typedef struct {
UA_NodeHead head;
UA_Boolean executable;
/* Members specific to open62541 */
UA_MethodCallback method;
#if UA_MULTITHREADING >= 100
UA_Boolean async; /* Indicates an async method call */
#endif
} UA_MethodNode;
ObjectNode¶
Objects are used to represent systems, system components, real-world objects and software objects. Objects are instances of an object type and may contain variables, methods and further objects.
typedef struct {
UA_NodeHead head;
UA_Byte eventNotifier;
} UA_ObjectNode;
ObjectTypeNode¶
ObjectTypes provide definitions for Objects. Abstract objects cannot be instantiated. See Node Lifecycle: Constructors, Destructors and Node Contexts for the use of constructor and destructor callbacks.
typedef struct {
UA_NodeHead head;
UA_Boolean isAbstract;
/* Members specific to open62541 */
UA_NodeTypeLifecycle lifecycle;
} UA_ObjectTypeNode;
ReferenceTypeNode¶
Each reference between two nodes is typed with a ReferenceType that gives meaning to the relation. The OPC UA standard defines a set of ReferenceTypes as a mandatory part of OPC UA information models.
- Abstract ReferenceTypes cannot be used in actual references and are only used to structure the ReferenceTypes hierarchy
- Symmetric references have the same meaning from the perspective of the source and target node
The figure below shows the hierarchy of the standard ReferenceTypes (arrows
indicate a hasSubType relation). Refer to Part 3 of the OPC UA
specification for the full semantics of each ReferenceType.
The ReferenceType hierarchy can be extended with user-defined ReferenceTypes. Many Companion Specifications for OPC UA define new ReferenceTypes to be used in their domain of interest.
For the following example of custom ReferenceTypes, we attempt to model the
structure of a technical system. For this, we introduce two custom
ReferenceTypes. First, the hierarchical contains ReferenceType indicates
that a system (represented by an OPC UA object) contains a component (or
subsystem). This gives rise to a tree-structure of containment relations. For
example, the motor (object) is contained in the car and the crankshaft is
contained in the motor. Second, the symmetric connectedTo ReferenceType
indicates that two components are connected. For example, the motor’s
crankshaft is connected to the gear box. Connections are independent of the
containment hierarchy and can induce a general graph-structure. Further
subtypes of connectedTo could be used to differentiate between physical,
electrical and information related connections. A client can then learn the
layout of a (physical) system represented in an OPC UA information model
based on a common understanding of just two custom reference types.
typedef struct {
UA_NodeHead head;
UA_Boolean isAbstract;
UA_Boolean symmetric;
UA_LocalizedText inverseName;
/* Members specific to open62541 */
UA_Byte referenceTypeIndex;
UA_ReferenceTypeSet subTypes; /* contains the type itself as well */
} UA_ReferenceTypeNode;
DataTypeNode¶
DataTypes represent simple and structured data types. DataTypes may contain
arrays. But they always describe the structure of a single instance. In
open62541, DataTypeNodes in the information model hierarchy are matched to
UA_DataType type descriptions for Generic Type Handling via their NodeId.
Abstract DataTypes (e.g. Number) cannot be the type of actual values.
They are used to constrain values to possible child DataTypes (e.g.
UInt32).
typedef struct {
UA_NodeHead head;
UA_Boolean isAbstract;
} UA_DataTypeNode;
ViewNode¶
Each View defines a subset of the Nodes in the AddressSpace. Views can be used when browsing an information model to focus on a subset of nodes and references only. ViewNodes can be created and be interacted with. But their use in the Browse service is currently unsupported in open62541.
typedef struct {
UA_NodeHead head;
UA_Byte eventNotifier;
UA_Boolean containsNoLoops;
} UA_ViewNode;
Node Union¶
A union that represents any kind of node. The node head can always be used. Check the NodeClass before accessing specific content.
typedef union {
UA_NodeHead head;
UA_VariableNode variableNode;
UA_VariableTypeNode variableTypeNode;
UA_MethodNode methodNode;
UA_ObjectNode objectNode;
UA_ObjectTypeNode objectTypeNode;
UA_ReferenceTypeNode referenceTypeNode;
UA_DataTypeNode dataTypeNode;
UA_ViewNode viewNode;
} UA_Node;
Nodestore Plugin API¶
The following definitions are used for implementing custom node storage backends. Most users will want to use the default nodestore and don’t need to work with the nodestore API.
Outside of custom nodestore implementations, users should not manually edit nodes. Please use the OPC UA services for that. Otherwise, all consistency checks are omitted. This can crash the application eventually.
typedef void (*UA_NodestoreVisitor)(void *visitorCtx, const UA_Node *node);
typedef struct {
/* Nodestore context and lifecycle */
void *context;
void (*clear)(void *nsCtx);
/* The following definitions are used to create empty nodes of the different
* node types. The memory is managed by the nodestore. Therefore, the node
* has to be removed via a special deleteNode function. (If the new node is
* not added to the nodestore.) */
UA_Node * (*newNode)(void *nsCtx, UA_NodeClass nodeClass);
void (*deleteNode)(void *nsCtx, UA_Node *node);
/* ``Get`` returns a pointer to an immutable node. ``Release`` indicates
* that the pointer is no longer accessed afterwards. */
const UA_Node * (*getNode)(void *nsCtx, const UA_NodeId *nodeId);
void (*releaseNode)(void *nsCtx, const UA_Node *node);
/* Returns an editable copy of a node (needs to be deleted with the
* deleteNode function or inserted / replaced into the nodestore). */
UA_StatusCode (*getNodeCopy)(void *nsCtx, const UA_NodeId *nodeId,
UA_Node **outNode);
/* Inserts a new node into the nodestore. If the NodeId is zero, then a
* fresh numeric NodeId is assigned. If insertion fails, the node is
* deleted. */
UA_StatusCode (*insertNode)(void *nsCtx, UA_Node *node,
UA_NodeId *addedNodeId);
/* To replace a node, get an editable copy of the node, edit and replace
* with this function. If the node was already replaced since the copy was
* made, UA_STATUSCODE_BADINTERNALERROR is returned. If the NodeId is not
* found, UA_STATUSCODE_BADNODEIDUNKNOWN is returned. In both error cases,
* the editable node is deleted. */
UA_StatusCode (*replaceNode)(void *nsCtx, UA_Node *node);
/* Removes a node from the nodestore. */
UA_StatusCode (*removeNode)(void *nsCtx, const UA_NodeId *nodeId);
/* Maps the ReferenceTypeIndex used for the references to the NodeId of the
* ReferenceType. The returned pointer is stable until the Nodestore is
* deleted. */
const UA_NodeId * (*getReferenceTypeId)(void *nsCtx, UA_Byte refTypeIndex);
/* Execute a callback for every node in the nodestore. */
void (*iterate)(void *nsCtx, UA_NodestoreVisitor visitor,
void *visitorCtx);
} UA_Nodestore;
/* Attributes must be of a matching type (VariableAttributes, ObjectAttributes,
* and so on). The attributes are copied. Note that the attributes structs do
* not contain NodeId, NodeClass and BrowseName. The NodeClass of the node needs
* to be correctly set before calling this method. UA_Node_clear is called on
* the node when an error occurs internally. */
UA_StatusCode
UA_Node_setAttributes(UA_Node *node, const void *attributes,
const UA_DataType *attributeType);
/* Reset the destination node and copy the content of the source */
UA_StatusCode
UA_Node_copy(const UA_Node *src, UA_Node *dst);
/* Allocate new node and copy the values from src */
UA_Node *
UA_Node_copy_alloc(const UA_Node *src);
/* Add a single reference to the node */
UA_StatusCode
UA_Node_addReference(UA_Node *node, UA_Byte refTypeIndex, UA_Boolean isForward,
const UA_ExpandedNodeId *targetNodeId,
UA_UInt32 targetBrowseNameHash);
/* Delete a single reference from the node */
UA_StatusCode
UA_Node_deleteReference(UA_Node *node, UA_Byte refTypeIndex, UA_Boolean isForward,
const UA_ExpandedNodeId *targetNodeId);
/* Deletes references from the node which are not matching any type in the given
* array. Could be used to e.g. delete all the references, except
* 'HASMODELINGRULE' */
void
UA_Node_deleteReferencesSubset(UA_Node *node, const UA_ReferenceTypeSet *keepSet);
/* Delete all references of the node */
void
UA_Node_deleteReferences(UA_Node *node);
/* Remove all malloc'ed members of the node and reset */
void
UA_Node_clear(UA_Node *node);