ua_plugin_nodestore.h 20 KB

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