ua_plugin_nodestore.h 19 KB

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