ua_server_pubsub.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373
  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 (c) 2017-2018 Fraunhofer IOSB (Author: Andreas Ebner)
  6. */
  7. #ifndef UA_SERVER_PUBSUB_H
  8. #define UA_SERVER_PUBSUB_H
  9. #include "ua_server.h"
  10. _UA_BEGIN_DECLS
  11. #ifdef UA_ENABLE_PUBSUB
  12. /**
  13. * .. _pubsub:
  14. *
  15. * Publish/Subscribe
  16. * =================
  17. *
  18. * Work in progress!
  19. * This part will be a new chapter later.
  20. *
  21. * TODO: write general PubSub introduction
  22. *
  23. * The Publish/Subscribe (PubSub) extension for OPC UA enables fast and efficient
  24. * 1:m communication. The PubSub extension is protocol agnostic and can be used
  25. * with broker based protocols like MQTT and AMQP or brokerless implementations like UDP-Multicasting.
  26. *
  27. * The PubSub API uses the following scheme:
  28. *
  29. * 1. Create a configuration for the needed PubSub element.
  30. *
  31. * 2. Call the add[element] function and pass in the configuration.
  32. *
  33. * 3. The add[element] function returns the unique nodeId of the internally created element.
  34. *
  35. * Take a look on the PubSub Tutorials for mor details about the API usage.::
  36. *
  37. * +-----------+
  38. * | UA_Server |
  39. * +-----------+
  40. * | |
  41. * | |
  42. * | |
  43. * | | +----------------------+
  44. * | +--> UA_PubSubConnection | UA_Server_addPubSubConnection
  45. * | +----------------------+
  46. * | | |
  47. * | | | +----------------+
  48. * | | +----> UA_WriterGroup | UA_PubSubConnection_addWriterGroup
  49. * | | +----------------+
  50. * | | |
  51. * | | | +------------------+
  52. * | | +----> UA_DataSetWriter | UA_WriterGroup_addDataSetWriter +-+
  53. * | | +------------------+ |
  54. * | | |
  55. * | | +----------------+ | r
  56. * | +---------> UA_ReaderGroup | | e
  57. * | +----------------+ | f
  58. * | |
  59. * | +---------------------------+ |
  60. * +-------> UA_PubSubPublishedDataSet | UA_Server_addPublishedDataSet <-+
  61. * +---------------------------+
  62. * |
  63. * | +-----------------+
  64. * +----> UA_DataSetField | UA_PublishedDataSet_addDataSetField
  65. * +-----------------+
  66. * PubSub compile flags
  67. * --------------------
  68. *
  69. * **UA_ENABLE_PUBSUB**
  70. * Enable the experimental OPC UA PubSub support. The option will include the PubSub UDP multicast plugin. Disabled by default.
  71. * **UA_ENABLE_PUBSUB_DELTAFRAMES**
  72. * The PubSub messages differentiate between keyframe (all published values contained) and deltaframe (only changed values contained) messages.
  73. * Deltaframe messages creation consumes some additional ressources and can be disabled with this flag. Disabled by default.
  74. * Compile the human-readable name of the StatusCodes into the binary. Disabled by default.
  75. * **UA_ENABLE_PUBSUB_INFORMATIONMODEL**
  76. * Enable the information model representation of the PubSub configuration. For more details take a look at the following section `PubSub Information Model Representation`. Disabled by default.
  77. *
  78. * PubSub Information Model Representation
  79. * ----------------------------------------
  80. * .. _pubsub_informationmodel:
  81. *
  82. * The complete PubSub configuration is available inside the information model.
  83. * The entry point is the node 'PublishSubscribe, located under the Server node.
  84. * The standard defines for PubSub no new Service set. The configuration can optionally
  85. * done over methods inside the information model. The information model representation
  86. * of the current PubSub configuration is generated automatically. This feature
  87. * can enabled/disable by changing the UA_ENABLE_PUBSUB_INFORMATIONMODEL option.
  88. *
  89. * Connections
  90. * -----------
  91. * The PubSub connections are the abstraction between the concrete transport protocol
  92. * and the PubSub functionality. It is possible to create multiple connections with
  93. * different transport protocols at runtime.
  94. *
  95. * Take a look on the PubSub Tutorials for mor details about the API usage.
  96. */
  97. typedef enum {
  98. UA_PUBSUB_PUBLISHERID_NUMERIC,
  99. UA_PUBSUB_PUBLISHERID_STRING
  100. } UA_PublisherIdType;
  101. typedef struct {
  102. UA_String name;
  103. UA_Boolean enabled;
  104. UA_PublisherIdType publisherIdType;
  105. union { /* std: valid types UInt or String */
  106. UA_UInt32 numeric;
  107. UA_String string;
  108. } publisherId;
  109. UA_String transportProfileUri;
  110. UA_Variant address;
  111. size_t connectionPropertiesSize;
  112. UA_KeyValuePair *connectionProperties;
  113. UA_Variant connectionTransportSettings;
  114. } UA_PubSubConnectionConfig;
  115. UA_StatusCode
  116. UA_Server_addPubSubConnection(UA_Server *server,
  117. const UA_PubSubConnectionConfig *connectionConfig,
  118. UA_NodeId *connectionIdentifier);
  119. /* Returns a deep copy of the config */
  120. UA_StatusCode
  121. UA_Server_getPubSubConnectionConfig(UA_Server *server,
  122. const UA_NodeId connection,
  123. UA_PubSubConnectionConfig *config);
  124. /* Remove Connection, identified by the NodeId. Deletion of Connection
  125. * removes all contained WriterGroups and Writers. */
  126. UA_StatusCode
  127. UA_Server_removePubSubConnection(UA_Server *server, const UA_NodeId connection);
  128. /**
  129. * PublishedDataSets
  130. * -----------------
  131. * The PublishedDataSets (PDS) are containers for the published information. The
  132. * PDS contain the published variables and meta informations. The metadata is
  133. * commonly autogenerated or given as constant argument as part of the template
  134. * functions. The template functions are standard defined and intended for
  135. * configuration tools. You should normally create a empty PDS and call the
  136. * functions to add new fields. */
  137. /* The UA_PUBSUB_DATASET_PUBLISHEDITEMS has currently no additional members and
  138. * thus no dedicated config structure. */
  139. typedef enum {
  140. UA_PUBSUB_DATASET_PUBLISHEDITEMS,
  141. UA_PUBSUB_DATASET_PUBLISHEDEVENTS,
  142. UA_PUBSUB_DATASET_PUBLISHEDITEMS_TEMPLATE,
  143. UA_PUBSUB_DATASET_PUBLISHEDEVENTS_TEMPLATE,
  144. } UA_PublishedDataSetType;
  145. typedef struct {
  146. UA_DataSetMetaDataType metaData;
  147. size_t variablesToAddSize;
  148. UA_PublishedVariableDataType *variablesToAdd;
  149. } UA_PublishedDataItemsTemplateConfig;
  150. typedef struct {
  151. UA_NodeId eventNotfier;
  152. UA_ContentFilter filter;
  153. } UA_PublishedEventConfig;
  154. typedef struct {
  155. UA_DataSetMetaDataType metaData;
  156. UA_NodeId eventNotfier;
  157. size_t selectedFieldsSize;
  158. UA_SimpleAttributeOperand *selectedFields;
  159. UA_ContentFilter filter;
  160. } UA_PublishedEventTemplateConfig;
  161. /* Configuration structure for PublishedDataSet */
  162. typedef struct {
  163. UA_String name;
  164. UA_PublishedDataSetType publishedDataSetType;
  165. union {
  166. /* The UA_PUBSUB_DATASET_PUBLISHEDITEMS has currently no additional members
  167. * and thus no dedicated config structure.*/
  168. UA_PublishedDataItemsTemplateConfig itemsTemplate;
  169. UA_PublishedEventConfig event;
  170. UA_PublishedEventTemplateConfig eventTemplate;
  171. } config;
  172. } UA_PublishedDataSetConfig;
  173. void
  174. UA_PublishedDataSetConfig_deleteMembers(UA_PublishedDataSetConfig *pdsConfig);
  175. typedef struct {
  176. UA_StatusCode addResult;
  177. size_t fieldAddResultsSize;
  178. UA_StatusCode *fieldAddResults;
  179. UA_ConfigurationVersionDataType configurationVersion;
  180. } UA_AddPublishedDataSetResult;
  181. UA_AddPublishedDataSetResult
  182. UA_Server_addPublishedDataSet(UA_Server *server,
  183. const UA_PublishedDataSetConfig *publishedDataSetConfig,
  184. UA_NodeId *pdsIdentifier);
  185. /* Returns a deep copy of the config */
  186. UA_StatusCode
  187. UA_Server_getPublishedDataSetConfig(UA_Server *server, const UA_NodeId pds,
  188. UA_PublishedDataSetConfig *config);
  189. /* Remove PublishedDataSet, identified by the NodeId. Deletion of PDS removes
  190. * all contained and linked PDS Fields. Connected WriterGroups will be also
  191. * removed. */
  192. UA_StatusCode
  193. UA_Server_removePublishedDataSet(UA_Server *server, const UA_NodeId pds);
  194. /**
  195. * DataSetFields
  196. * -------------
  197. * The description of published variables is named DataSetField. Each
  198. * DataSetField contains the selection of one information model node. The
  199. * DataSetField has additional parameters for the publishing, sampling and error
  200. * handling process. */
  201. typedef struct{
  202. UA_ConfigurationVersionDataType configurationVersion;
  203. UA_String fieldNameAlias;
  204. UA_Boolean promotedField;
  205. UA_PublishedVariableDataType publishParameters;
  206. } UA_DataSetVariableConfig;
  207. typedef enum {
  208. UA_PUBSUB_DATASETFIELD_VARIABLE,
  209. UA_PUBSUB_DATASETFIELD_EVENT
  210. } UA_DataSetFieldType;
  211. typedef struct {
  212. UA_DataSetFieldType dataSetFieldType;
  213. union {
  214. UA_DataSetVariableConfig variable;
  215. //events need other config later
  216. } field;
  217. } UA_DataSetFieldConfig;
  218. void
  219. UA_DataSetFieldConfig_deleteMembers(UA_DataSetFieldConfig *dataSetFieldConfig);
  220. typedef struct {
  221. UA_StatusCode result;
  222. UA_ConfigurationVersionDataType configurationVersion;
  223. } UA_DataSetFieldResult;
  224. UA_DataSetFieldResult
  225. UA_Server_addDataSetField(UA_Server *server,
  226. const UA_NodeId publishedDataSet,
  227. const UA_DataSetFieldConfig *fieldConfig,
  228. UA_NodeId *fieldIdentifier);
  229. /* Returns a deep copy of the config */
  230. UA_StatusCode
  231. UA_Server_getDataSetFieldConfig(UA_Server *server, const UA_NodeId dsf,
  232. UA_DataSetFieldConfig *config);
  233. UA_DataSetFieldResult
  234. UA_Server_removeDataSetField(UA_Server *server, const UA_NodeId dsf);
  235. /**
  236. * WriterGroup
  237. * -----------
  238. * All WriterGroups are created within a PubSubConnection and automatically
  239. * deleted if the connection is removed. The WriterGroup is primary used as
  240. * container for :ref:`dsw` and network message settings. The WriterGroup can be
  241. * imagined as producer of the network messages. The creation of network
  242. * messages is controlled by parameters like the publish interval, which is e.g.
  243. * contained in the WriterGroup. */
  244. typedef enum {
  245. UA_PUBSUB_ENCODING_BINARY,
  246. UA_PUBSUB_ENCODING_JSON,
  247. UA_PUBSUB_ENCODING_UADP
  248. } UA_PubSubEncodingType;
  249. typedef struct {
  250. UA_String name;
  251. UA_Boolean enabled;
  252. UA_UInt16 writerGroupId;
  253. UA_Duration publishingInterval;
  254. UA_Double keepAliveTime;
  255. UA_Byte priority;
  256. UA_MessageSecurityMode securityMode;
  257. UA_ExtensionObject transportSettings;
  258. UA_ExtensionObject messageSettings;
  259. size_t groupPropertiesSize;
  260. UA_KeyValuePair *groupProperties;
  261. UA_PubSubEncodingType encodingMimeType;
  262. /* non std. config parameter. maximum count of embedded DataSetMessage in
  263. * one NetworkMessage */
  264. UA_UInt16 maxEncapsulatedDataSetMessageCount;
  265. } UA_WriterGroupConfig;
  266. void
  267. UA_WriterGroupConfig_deleteMembers(UA_WriterGroupConfig *writerGroupConfig);
  268. /* Add a new WriterGroup to an existing Connection */
  269. UA_StatusCode
  270. UA_Server_addWriterGroup(UA_Server *server, const UA_NodeId connection,
  271. const UA_WriterGroupConfig *writerGroupConfig,
  272. UA_NodeId *writerGroupIdentifier);
  273. /* Returns a deep copy of the config */
  274. UA_StatusCode
  275. UA_Server_getWriterGroupConfig(UA_Server *server, const UA_NodeId writerGroup,
  276. UA_WriterGroupConfig *config);
  277. UA_StatusCode
  278. UA_Server_updateWriterGroupConfig(UA_Server *server, UA_NodeId writerGroupIdentifier,
  279. const UA_WriterGroupConfig *config);
  280. UA_StatusCode
  281. UA_Server_removeWriterGroup(UA_Server *server, const UA_NodeId writerGroup);
  282. /**
  283. * .. _dsw:
  284. *
  285. * DataSetWriter
  286. * -------------
  287. * The DataSetWriters are the glue between the WriterGroups and the
  288. * PublishedDataSets. The DataSetWriter contain configuration parameters and
  289. * flags which influence the creation of DataSet messages. These messages are
  290. * encapsulated inside the network message. The DataSetWriter must be linked
  291. * with an existing PublishedDataSet and be contained within a WriterGroup. */
  292. typedef struct {
  293. UA_String name;
  294. UA_UInt16 dataSetWriterId;
  295. UA_DataSetFieldContentMask dataSetFieldContentMask;
  296. UA_UInt32 keyFrameCount;
  297. UA_ExtensionObject messageSettings;
  298. UA_String dataSetName;
  299. size_t dataSetWriterPropertiesSize;
  300. UA_KeyValuePair *dataSetWriterProperties;
  301. } UA_DataSetWriterConfig;
  302. void
  303. UA_DataSetWriterConfig_deleteMembers(UA_DataSetWriterConfig *pdsConfig);
  304. /* Add a new DataSetWriter to a existing WriterGroup. The DataSetWriter must be
  305. * coupled with a PublishedDataSet on creation.
  306. *
  307. * Part 14, 7.1.5.2.1 defines: The link between the PublishedDataSet and
  308. * DataSetWriter shall be created when an instance of the DataSetWriterType is
  309. * created. */
  310. UA_StatusCode
  311. UA_Server_addDataSetWriter(UA_Server *server,
  312. const UA_NodeId writerGroup, const UA_NodeId dataSet,
  313. const UA_DataSetWriterConfig *dataSetWriterConfig,
  314. UA_NodeId *writerIdentifier);
  315. /* Returns a deep copy of the config */
  316. UA_StatusCode
  317. UA_Server_getDataSetWriterConfig(UA_Server *server, const UA_NodeId dsw,
  318. UA_DataSetWriterConfig *config);
  319. UA_StatusCode
  320. UA_Server_removeDataSetWriter(UA_Server *server, const UA_NodeId dsw);
  321. #endif /* UA_ENABLE_PUBSUB */
  322. _UA_END_DECLS
  323. #endif /* UA_SERVER_PUBSUB_H */