ua_plugin_nodestore.h 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520
  1. /* This Source Code Form is subject to the terms of the Mozilla Public
  2. * License, v. 2.0. If a copy of the MPL was not distributed with this
  3. * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  4. *
  5. * Copyright 2017 (c) Julius Pfrommer, Fraunhofer IOSB
  6. * Copyright 2017 (c) Julian Grothoff
  7. * Copyright 2017 (c) Stefan Profanter, fortiss GmbH
  8. */
  9. #ifndef UA_SERVER_NODES_H_
  10. #define UA_SERVER_NODES_H_
  11. /* !!! Warning !!!
  12. *
  13. * If you are not developing a nodestore plugin, then you should not work with
  14. * the definitions from this file directly. The underlying node structures are
  15. * not meant to be used directly by end users. Please use the public server API
  16. * / OPC UA services to interact with the information model. */
  17. #ifdef __cplusplus
  18. extern "C" {
  19. #endif
  20. #include "ua_server.h"
  21. /**
  22. * .. _information-modelling:
  23. *
  24. * Information Modelling
  25. * =====================
  26. *
  27. * Information modelling in OPC UA combines concepts from object-orientation and
  28. * semantic modelling. At the core, an OPC UA information model is a graph made
  29. * up of
  30. *
  31. * - Nodes: There are eight possible Node types (variable, object, method, ...)
  32. * - References: Typed and directed relations between two nodes
  33. *
  34. * Every node is identified by a unique (within the server) :ref:`nodeid`.
  35. * Reference are triples of the form ``(source-nodeid, referencetype-nodeid,
  36. * target-nodeid)``. An example reference between nodes is a
  37. * ``hasTypeDefinition`` reference between a Variable and its VariableType. Some
  38. * ReferenceTypes are *hierarchic* and must not form *directed loops*. See the
  39. * section on :ref:`ReferenceTypes <referencetypenode>` for more details on
  40. * possible references and their semantics.
  41. *
  42. * **Warning!!** The structures defined in this section are only relevant for
  43. * the developers of custom Nodestores. The interaction with the information
  44. * model is possible only via the OPC UA :ref:`services`. So the following
  45. * sections are purely informational so that users may have a clear mental
  46. * model of the underlying representation.
  47. *
  48. * Base Node Attributes
  49. * --------------------
  50. *
  51. * Nodes contain attributes according to their node type. The base node
  52. * attributes are common to all node types. In the OPC UA :ref:`services`,
  53. * attributes are referred to via the :ref:`nodeid` of the containing node and
  54. * an integer :ref:`attribute-id`.
  55. *
  56. * Internally, open62541 uses ``UA_Node`` in places where the exact node type is
  57. * not known or not important. The ``nodeClass`` attribute is used to ensure the
  58. * correctness of casting from ``UA_Node`` to a specific node type. */
  59. /* List of reference targets with the same reference type and direction */
  60. typedef struct {
  61. UA_NodeId referenceTypeId;
  62. UA_Boolean isInverse;
  63. size_t targetIdsSize;
  64. UA_ExpandedNodeId *targetIds;
  65. } UA_NodeReferenceKind;
  66. #define UA_NODE_BASEATTRIBUTES \
  67. UA_NodeId nodeId; \
  68. UA_NodeClass nodeClass; \
  69. UA_QualifiedName browseName; \
  70. UA_LocalizedText displayName; \
  71. UA_LocalizedText description; \
  72. UA_UInt32 writeMask; \
  73. size_t referencesSize; \
  74. UA_NodeReferenceKind *references; \
  75. \
  76. /* Members specific to open62541 */ \
  77. void *context;
  78. typedef struct {
  79. UA_NODE_BASEATTRIBUTES
  80. } UA_Node;
  81. /**
  82. * VariableNode
  83. * ------------
  84. *
  85. * Variables store values in a :ref:`datavalue` together with
  86. * metadata for introspection. Most notably, the attributes data type, value
  87. * rank and array dimensions constrain the possible values the variable can take
  88. * on.
  89. *
  90. * Variables come in two flavours: properties and datavariables. Properties are
  91. * related to a parent with a ``hasProperty`` reference and may not have child
  92. * nodes themselves. Datavariables may contain properties (``hasProperty``) and
  93. * also datavariables (``hasComponents``).
  94. *
  95. * All variables are instances of some :ref:`variabletypenode` in return
  96. * constraining the possible data type, value rank and array dimensions
  97. * attributes.
  98. *
  99. * Data Type
  100. * ^^^^^^^^^
  101. *
  102. * The (scalar) data type of the variable is constrained to be of a specific
  103. * type or one of its children in the type hierarchy. The data type is given as
  104. * a NodeId pointing to a :ref:`datatypenode` in the type hierarchy. See the
  105. * Section :ref:`datatypenode` for more details.
  106. *
  107. * If the data type attribute points to ``UInt32``, then the value attribute
  108. * must be of that exact type since ``UInt32`` does not have children in the
  109. * type hierarchy. If the data type attribute points ``Number``, then the type
  110. * of the value attribute may still be ``UInt32``, but also ``Float`` or
  111. * ``Byte``.
  112. *
  113. * Consistency between the data type attribute in the variable and its
  114. * :ref:`VariableTypeNode` is ensured.
  115. *
  116. * Value Rank
  117. * ^^^^^^^^^^
  118. *
  119. * This attribute indicates whether the value attribute of the variable is an
  120. * array and how many dimensions the array has. It may have the following
  121. * values:
  122. *
  123. * - ``n >= 1``: the value is an array with the specified number of dimensions
  124. * - ``n = 0``: the value is an array with one or more dimensions
  125. * - ``n = -1``: the value is a scalar
  126. * - ``n = -2``: the value can be a scalar or an array with any number of dimensions
  127. * - ``n = -3``: the value can be a scalar or a one dimensional array
  128. *
  129. * Consistency between the value rank attribute in the variable and its
  130. * :ref:`variabletypenode` is ensured.
  131. *
  132. * Array Dimensions
  133. * ^^^^^^^^^^^^^^^^
  134. *
  135. * If the value rank permits the value to be a (multi-dimensional) array, the
  136. * exact length in each dimensions can be further constrained with this
  137. * attribute.
  138. *
  139. * - For positive lengths, the variable value is guaranteed to be of the same
  140. * length in this dimension.
  141. * - The dimension length zero is a wildcard and the actual value may have any
  142. * length in this dimension.
  143. *
  144. * Consistency between the array dimensions attribute in the variable and its
  145. * :ref:`variabletypenode` is ensured. */
  146. /* Indicates whether a variable contains data inline or whether it points to an
  147. * external data source */
  148. typedef enum {
  149. UA_VALUESOURCE_DATA,
  150. UA_VALUESOURCE_DATASOURCE
  151. } UA_ValueSource;
  152. #define UA_NODE_VARIABLEATTRIBUTES \
  153. /* Constraints on possible values */ \
  154. UA_NodeId dataType; \
  155. UA_Int32 valueRank; \
  156. size_t arrayDimensionsSize; \
  157. UA_UInt32 *arrayDimensions; \
  158. \
  159. /* The current value */ \
  160. UA_ValueSource valueSource; \
  161. union { \
  162. struct { \
  163. UA_DataValue value; \
  164. UA_ValueCallback callback; \
  165. } data; \
  166. UA_DataSource dataSource; \
  167. } value;
  168. typedef struct {
  169. UA_NODE_BASEATTRIBUTES
  170. UA_NODE_VARIABLEATTRIBUTES
  171. UA_Byte accessLevel;
  172. UA_Double minimumSamplingInterval;
  173. UA_Boolean historizing; /* currently unsupported */
  174. } UA_VariableNode;
  175. /**
  176. * .. _variabletypenode:
  177. *
  178. * VariableTypeNode
  179. * ----------------
  180. *
  181. * VariableTypes are used to provide type definitions for variables.
  182. * VariableTypes constrain the data type, value rank and array dimensions
  183. * attributes of variable instances. Furthermore, instantiating from a specific
  184. * variable type may provide semantic information. For example, an instance from
  185. * ``MotorTemperatureVariableType`` is more meaningful than a float variable
  186. * instantiated from ``BaseDataVariable``. */
  187. typedef struct {
  188. UA_NODE_BASEATTRIBUTES
  189. UA_NODE_VARIABLEATTRIBUTES
  190. UA_Boolean isAbstract;
  191. /* Members specific to open62541 */
  192. UA_NodeTypeLifecycle lifecycle;
  193. } UA_VariableTypeNode;
  194. /**
  195. * .. _methodnode:
  196. *
  197. * MethodNode
  198. * ----------
  199. *
  200. * Methods define callable functions and are invoked using the :ref:`Call
  201. * <method-services>` service. MethodNodes may have special properties (variable
  202. * childen with a ``hasProperty`` reference) with the :ref:`qualifiedname` ``(0,
  203. * "InputArguments")`` and ``(0, "OutputArguments")``. The input and output
  204. * arguments are both described via an array of ``UA_Argument``. While the Call
  205. * service uses a generic array of :ref:`variant` for input and output, the
  206. * actual argument values are checked to match the signature of the MethodNode.
  207. *
  208. * Note that the same MethodNode may be referenced from several objects (and
  209. * object types). For this, the NodeId of the method *and of the object
  210. * providing context* is part of a Call request message. */
  211. typedef struct {
  212. UA_NODE_BASEATTRIBUTES
  213. UA_Boolean executable;
  214. /* Members specific to open62541 */
  215. UA_MethodCallback method;
  216. } UA_MethodNode;
  217. /**
  218. * ObjectNode
  219. * ----------
  220. *
  221. * Objects are used to represent systems, system components, real-world objects
  222. * and software objects. Objects are instances of an :ref:`object
  223. * type<objecttypenode>` and may contain variables, methods and further
  224. * objects. */
  225. typedef struct {
  226. UA_NODE_BASEATTRIBUTES
  227. UA_Byte eventNotifier;
  228. } UA_ObjectNode;
  229. /**
  230. * .. _objecttypenode:
  231. *
  232. * ObjectTypeNode
  233. * --------------
  234. *
  235. * ObjectTypes provide definitions for Objects. Abstract objects cannot be
  236. * instantiated. See :ref:`node-lifecycle` for the use of constructor and
  237. * destructor callbacks. */
  238. typedef struct {
  239. UA_NODE_BASEATTRIBUTES
  240. UA_Boolean isAbstract;
  241. /* Members specific to open62541 */
  242. UA_NodeTypeLifecycle lifecycle;
  243. } UA_ObjectTypeNode;
  244. /**
  245. * .. _referencetypenode:
  246. *
  247. * ReferenceTypeNode
  248. * -----------------
  249. *
  250. * Each reference between two nodes is typed with a ReferenceType that gives
  251. * meaning to the relation. The OPC UA standard defines a set of ReferenceTypes
  252. * as a mandatory part of OPC UA information models.
  253. *
  254. * - Abstract ReferenceTypes cannot be used in actual references and are only
  255. * used to structure the ReferenceTypes hierarchy
  256. * - Symmetric references have the same meaning from the perspective of the
  257. * source and target node
  258. *
  259. * The figure below shows the hierarchy of the standard ReferenceTypes (arrows
  260. * indicate a ``hasSubType`` relation). Refer to Part 3 of the OPC UA
  261. * specification for the full semantics of each ReferenceType.
  262. *
  263. * .. graphviz::
  264. *
  265. * digraph tree {
  266. *
  267. * node [height=0, shape=box, fillcolor="#E5E5E5", concentrate=true]
  268. *
  269. * references [label="References\n(Abstract, Symmetric)"]
  270. * hierarchical_references [label="HierarchicalReferences\n(Abstract)"]
  271. * references -> hierarchical_references
  272. *
  273. * nonhierarchical_references [label="NonHierarchicalReferences\n(Abstract, Symmetric)"]
  274. * references -> nonhierarchical_references
  275. *
  276. * haschild [label="HasChild\n(Abstract)"]
  277. * hierarchical_references -> haschild
  278. *
  279. * aggregates [label="Aggregates\n(Abstract)"]
  280. * haschild -> aggregates
  281. *
  282. * organizes [label="Organizes"]
  283. * hierarchical_references -> organizes
  284. *
  285. * hascomponent [label="HasComponent"]
  286. * aggregates -> hascomponent
  287. *
  288. * hasorderedcomponent [label="HasOrderedComponent"]
  289. * hascomponent -> hasorderedcomponent
  290. *
  291. * hasproperty [label="HasProperty"]
  292. * aggregates -> hasproperty
  293. *
  294. * hassubtype [label="HasSubtype"]
  295. * haschild -> hassubtype
  296. *
  297. * hasmodellingrule [label="HasModellingRule"]
  298. * nonhierarchical_references -> hasmodellingrule
  299. *
  300. * hastypedefinition [label="HasTypeDefinition"]
  301. * nonhierarchical_references -> hastypedefinition
  302. *
  303. * hasencoding [label="HasEncoding"]
  304. * nonhierarchical_references -> hasencoding
  305. *
  306. * hasdescription [label="HasDescription"]
  307. * nonhierarchical_references -> hasdescription
  308. *
  309. * haseventsource [label="HasEventSource"]
  310. * hierarchical_references -> haseventsource
  311. *
  312. * hasnotifier [label="HasNotifier"]
  313. * hierarchical_references -> hasnotifier
  314. *
  315. * generatesevent [label="GeneratesEvent"]
  316. * nonhierarchical_references -> generatesevent
  317. *
  318. * alwaysgeneratesevent [label="AlwaysGeneratesEvent"]
  319. * generatesevent -> alwaysgeneratesevent
  320. *
  321. * {rank=same hierarchical_references nonhierarchical_references}
  322. * {rank=same generatesevent haseventsource hasmodellingrule
  323. * hasencoding hassubtype}
  324. * {rank=same alwaysgeneratesevent hasproperty}
  325. *
  326. * }
  327. *
  328. * The ReferenceType hierarchy can be extended with user-defined ReferenceTypes.
  329. * Many Companion Specifications for OPC UA define new ReferenceTypes to be used
  330. * in their domain of interest.
  331. *
  332. * For the following example of custom ReferenceTypes, we attempt to model the
  333. * structure of a technical system. For this, we introduce two custom
  334. * ReferenceTypes. First, the hierarchical ``contains`` ReferenceType indicates
  335. * that a system (represented by an OPC UA object) contains a component (or
  336. * subsystem). This gives rise to a tree-structure of containment relations. For
  337. * example, the motor (object) is contained in the car and the crankshaft is
  338. * contained in the motor. Second, the symmetric ``connectedTo`` ReferenceType
  339. * indicates that two components are connected. For example, the motor's
  340. * crankshaft is connected to the gear box. Connections are independent of the
  341. * containment hierarchy and can induce a general graph-structure. Further
  342. * subtypes of ``connectedTo`` could be used to differentiate between physical,
  343. * electrical and information related connections. A client can then learn the
  344. * layout of a (physical) system represented in an OPC UA information model
  345. * based on a common understanding of just two custom reference types. */
  346. typedef struct {
  347. UA_NODE_BASEATTRIBUTES
  348. UA_Boolean isAbstract;
  349. UA_Boolean symmetric;
  350. UA_LocalizedText inverseName;
  351. } UA_ReferenceTypeNode;
  352. /**
  353. * .. _datatypenode:
  354. *
  355. * DataTypeNode
  356. * ------------
  357. *
  358. * DataTypes represent simple and structured data types. DataTypes may contain
  359. * arrays. But they always describe the structure of a single instance. In
  360. * open62541, DataTypeNodes in the information model hierarchy are matched to
  361. * ``UA_DataType`` type descriptions for :ref:`generic-types` via their NodeId.
  362. *
  363. * Abstract DataTypes (e.g. ``Number``) cannot be the type of actual values.
  364. * They are used to constrain values to possible child DataTypes (e.g.
  365. * ``UInt32``). */
  366. typedef struct {
  367. UA_NODE_BASEATTRIBUTES
  368. UA_Boolean isAbstract;
  369. } UA_DataTypeNode;
  370. /**
  371. * ViewNode
  372. * --------
  373. *
  374. * Each View defines a subset of the Nodes in the AddressSpace. Views can be
  375. * used when browsing an information model to focus on a subset of nodes and
  376. * references only. ViewNodes can be created and be interacted with. But their
  377. * use in the :ref:`Browse<view-services>` service is currently unsupported in
  378. * open62541. */
  379. typedef struct {
  380. UA_NODE_BASEATTRIBUTES
  381. UA_Byte eventNotifier;
  382. UA_Boolean containsNoLoops;
  383. } UA_ViewNode;
  384. /**
  385. * Nodestore Plugin API
  386. * --------------------
  387. * The following definitions are used for implementing custom node storage
  388. * backends. **Most users will want to use the default nodestore and don't need
  389. * to work with the nodestore API**.
  390. *
  391. * Outside of custom nodestore implementations, users should not manually edit
  392. * nodes. Please use the OPC UA services for that. Otherwise, all consistency
  393. * checks are omitted. This can crash the application eventually. */
  394. typedef void (*UA_NodestoreVisitor)(void *visitorContext, const UA_Node *node);
  395. typedef struct {
  396. /* Nodestore context and lifecycle */
  397. void *context;
  398. void (*deleteNodestore)(void *nodestoreContext);
  399. /* For non-multithreaded access, some nodestores allow that nodes are edited
  400. * without a copy/replace. This is not possible when the node is only an
  401. * intermediate representation and stored e.g. in a database backend. */
  402. UA_Boolean inPlaceEditAllowed;
  403. /* The following definitions are used to create empty nodes of the different
  404. * node types. The memory is managed by the nodestore. Therefore, the node
  405. * has to be removed via a special deleteNode function. (If the new node is
  406. * not added to the nodestore.) */
  407. UA_Node * (*newNode)(void *nodestoreContext, UA_NodeClass nodeClass);
  408. void (*deleteNode)(void *nodestoreContext, UA_Node *node);
  409. /* ``Get`` returns a pointer to an immutable node. ``Release`` indicates
  410. * that the pointer is no longer accessed afterwards. */
  411. const UA_Node * (*getNode)(void *nodestoreContext, const UA_NodeId *nodeId);
  412. void (*releaseNode)(void *nodestoreContext, const UA_Node *node);
  413. /* Returns an editable copy of a node (needs to be deleted with the
  414. * deleteNode function or inserted / replaced into the nodestore). */
  415. UA_StatusCode (*getNodeCopy)(void *nodestoreContext, const UA_NodeId *nodeId,
  416. UA_Node **outNode);
  417. /* Inserts a new node into the nodestore. If the NodeId is zero, then a
  418. * fresh numeric NodeId is assigned. If insertion fails, the node is
  419. * deleted. */
  420. UA_StatusCode (*insertNode)(void *nodestoreContext, UA_Node *node,
  421. UA_NodeId *addedNodeId);
  422. /* To replace a node, get an editable copy of the node, edit and replace
  423. * with this function. If the node was already replaced since the copy was
  424. * made, UA_STATUSCODE_BADINTERNALERROR is returned. If the NodeId is not
  425. * found, UA_STATUSCODE_BADNODEIDUNKNOWN is returned. In both error cases,
  426. * the editable node is deleted. */
  427. UA_StatusCode (*replaceNode)(void *nodestoreContext, UA_Node *node);
  428. /* Removes a node from the nodestore. */
  429. UA_StatusCode (*removeNode)(void *nodestoreContext, const UA_NodeId *nodeId);
  430. /* Execute a callback for every node in the nodestore. */
  431. void (*iterate)(void *nodestoreContext, void* visitorContext,
  432. UA_NodestoreVisitor visitor);
  433. } UA_Nodestore;
  434. /**
  435. * The following methods specialize internally for the different node classes
  436. * (distinguished by the nodeClass member) */
  437. /* Attributes must be of a matching type (VariableAttributes, ObjectAttributes,
  438. * and so on). The attributes are copied. Note that the attributes structs do
  439. * not contain NodeId, NodeClass and BrowseName. The NodeClass of the node needs
  440. * to be correctly set before calling this method. UA_Node_deleteMembers is
  441. * called on the node when an error occurs internally. */
  442. UA_StatusCode UA_EXPORT
  443. UA_Node_setAttributes(UA_Node *node, const void *attributes,
  444. const UA_DataType *attributeType);
  445. /* Reset the destination node and copy the content of the source */
  446. UA_StatusCode UA_EXPORT
  447. UA_Node_copy(const UA_Node *src, UA_Node *dst);
  448. /* Allocate new node and copy the values from src */
  449. UA_EXPORT UA_Node *
  450. UA_Node_copy_alloc(const UA_Node *src);
  451. /* Add a single reference to the node */
  452. UA_StatusCode UA_EXPORT
  453. UA_Node_addReference(UA_Node *node, const UA_AddReferencesItem *item);
  454. /* Delete a single reference from the node */
  455. UA_StatusCode UA_EXPORT
  456. UA_Node_deleteReference(UA_Node *node, const UA_DeleteReferencesItem *item);
  457. /* Delete all references of the node */
  458. void UA_EXPORT
  459. UA_Node_deleteReferences(UA_Node *node);
  460. /* Remove all malloc'ed members of the node */
  461. void UA_EXPORT
  462. UA_Node_deleteMembers(UA_Node *node);
  463. #ifdef __cplusplus
  464. } // extern "C"
  465. #endif
  466. #endif /* UA_SERVER_NODES_H_ */