ua_plugin_nodestore.h 19 KB

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