ua_server_pubsub.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367
  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 struct {
  98. UA_String name;
  99. UA_Boolean enabled;
  100. union { /* std: valid types UInt or String */
  101. UA_UInt32 numeric;
  102. UA_String string;
  103. } publisherId;
  104. UA_String transportProfileUri;
  105. UA_Variant address;
  106. size_t connectionPropertiesSize;
  107. UA_KeyValuePair *connectionProperties;
  108. UA_Variant connectionTransportSettings;
  109. } UA_PubSubConnectionConfig;
  110. UA_StatusCode
  111. UA_Server_addPubSubConnection(UA_Server *server,
  112. const UA_PubSubConnectionConfig *connectionConfig,
  113. UA_NodeId *connectionIdentifier);
  114. /* Returns a deep copy of the config */
  115. UA_StatusCode
  116. UA_Server_getPubSubConnectionConfig(UA_Server *server,
  117. const UA_NodeId connection,
  118. UA_PubSubConnectionConfig *config);
  119. /* Remove Connection, identified by the NodeId. Deletion of Connection
  120. * removes all contained WriterGroups and Writers. */
  121. UA_StatusCode
  122. UA_Server_removePubSubConnection(UA_Server *server, const UA_NodeId connection);
  123. /**
  124. * PublishedDataSets
  125. * -----------------
  126. * The PublishedDataSets (PDS) are containers for the published information. The
  127. * PDS contain the published variables and meta informations. The metadata is
  128. * commonly autogenerated or given as constant argument as part of the template
  129. * functions. The template functions are standard defined and intended for
  130. * configuration tools. You should normally create a empty PDS and call the
  131. * functions to add new fields. */
  132. /* The UA_PUBSUB_DATASET_PUBLISHEDITEMS has currently no additional members and
  133. * thus no dedicated config structure. */
  134. typedef enum {
  135. UA_PUBSUB_DATASET_PUBLISHEDITEMS,
  136. UA_PUBSUB_DATASET_PUBLISHEDEVENTS,
  137. UA_PUBSUB_DATASET_PUBLISHEDITEMS_TEMPLATE,
  138. UA_PUBSUB_DATASET_PUBLISHEDEVENTS_TEMPLATE,
  139. } UA_PublishedDataSetType;
  140. typedef struct {
  141. UA_DataSetMetaDataType metaData;
  142. size_t variablesToAddSize;
  143. UA_PublishedVariableDataType *variablesToAdd;
  144. } UA_PublishedDataItemsTemplateConfig;
  145. typedef struct {
  146. UA_NodeId eventNotfier;
  147. UA_ContentFilter filter;
  148. } UA_PublishedEventConfig;
  149. typedef struct {
  150. UA_DataSetMetaDataType metaData;
  151. UA_NodeId eventNotfier;
  152. size_t selectedFieldsSize;
  153. UA_SimpleAttributeOperand *selectedFields;
  154. UA_ContentFilter filter;
  155. } UA_PublishedEventTemplateConfig;
  156. /* Configuration structure for PublishedDataSet */
  157. typedef struct {
  158. UA_String name;
  159. UA_PublishedDataSetType publishedDataSetType;
  160. union {
  161. /* The UA_PUBSUB_DATASET_PUBLISHEDITEMS has currently no additional members
  162. * and thus no dedicated config structure.*/
  163. UA_PublishedDataItemsTemplateConfig itemsTemplate;
  164. UA_PublishedEventConfig event;
  165. UA_PublishedEventTemplateConfig eventTemplate;
  166. } config;
  167. } UA_PublishedDataSetConfig;
  168. void
  169. UA_PublishedDataSetConfig_deleteMembers(UA_PublishedDataSetConfig *pdsConfig);
  170. typedef struct {
  171. UA_StatusCode addResult;
  172. size_t fieldAddResultsSize;
  173. UA_StatusCode *fieldAddResults;
  174. UA_ConfigurationVersionDataType configurationVersion;
  175. } UA_AddPublishedDataSetResult;
  176. UA_AddPublishedDataSetResult
  177. UA_Server_addPublishedDataSet(UA_Server *server,
  178. const UA_PublishedDataSetConfig *publishedDataSetConfig,
  179. UA_NodeId *pdsIdentifier);
  180. /* Returns a deep copy of the config */
  181. UA_StatusCode
  182. UA_Server_getPublishedDataSetConfig(UA_Server *server, const UA_NodeId pds,
  183. UA_PublishedDataSetConfig *config);
  184. /* Remove PublishedDataSet, identified by the NodeId. Deletion of PDS removes
  185. * all contained and linked PDS Fields. Connected WriterGroups will be also
  186. * removed. */
  187. UA_StatusCode
  188. UA_Server_removePublishedDataSet(UA_Server *server, const UA_NodeId pds);
  189. /**
  190. * DataSetFields
  191. * -------------
  192. * The description of published variables is named DataSetField. Each
  193. * DataSetField contains the selection of one information model node. The
  194. * DataSetField has additional parameters for the publishing, sampling and error
  195. * handling process. */
  196. typedef struct{
  197. UA_ConfigurationVersionDataType configurationVersion;
  198. UA_String fieldNameAlias;
  199. UA_Boolean promotedField;
  200. UA_PublishedVariableDataType publishParameters;
  201. } UA_DataSetVariableConfig;
  202. typedef enum {
  203. UA_PUBSUB_DATASETFIELD_VARIABLE,
  204. UA_PUBSUB_DATASETFIELD_EVENT
  205. } UA_DataSetFieldType;
  206. typedef struct {
  207. UA_DataSetFieldType dataSetFieldType;
  208. union {
  209. UA_DataSetVariableConfig variable;
  210. //events need other config later
  211. } field;
  212. } UA_DataSetFieldConfig;
  213. void
  214. UA_DataSetFieldConfig_deleteMembers(UA_DataSetFieldConfig *dataSetFieldConfig);
  215. typedef struct {
  216. UA_StatusCode result;
  217. UA_ConfigurationVersionDataType configurationVersion;
  218. } UA_DataSetFieldResult;
  219. UA_DataSetFieldResult
  220. UA_Server_addDataSetField(UA_Server *server,
  221. const UA_NodeId publishedDataSet,
  222. const UA_DataSetFieldConfig *fieldConfig,
  223. UA_NodeId *fieldIdentifier);
  224. /* Returns a deep copy of the config */
  225. UA_StatusCode
  226. UA_Server_getDataSetFieldConfig(UA_Server *server, const UA_NodeId dsf,
  227. UA_DataSetFieldConfig *config);
  228. UA_DataSetFieldResult
  229. UA_Server_removeDataSetField(UA_Server *server, const UA_NodeId dsf);
  230. /**
  231. * WriterGroup
  232. * -----------
  233. * All WriterGroups are created within a PubSubConnection and automatically
  234. * deleted if the connection is removed. The WriterGroup is primary used as
  235. * container for :ref:`dsw` and network message settings. The WriterGroup can be
  236. * imagined as producer of the network messages. The creation of network
  237. * messages is controlled by parameters like the publish interval, which is e.g.
  238. * contained in the WriterGroup. */
  239. typedef enum {
  240. UA_PUBSUB_ENCODING_BINARY,
  241. UA_PUBSUB_ENCODING_JSON,
  242. UA_PUBSUB_ENCODING_UADP
  243. } UA_PubSubEncodingType;
  244. typedef struct {
  245. UA_String name;
  246. UA_Boolean enabled;
  247. UA_UInt16 writerGroupId;
  248. UA_Duration publishingInterval;
  249. UA_Double keepAliveTime;
  250. UA_Byte priority;
  251. UA_MessageSecurityMode securityMode;
  252. UA_ExtensionObject transportSettings;
  253. UA_ExtensionObject messageSettings;
  254. size_t groupPropertiesSize;
  255. UA_KeyValuePair *groupProperties;
  256. UA_PubSubEncodingType encodingMimeType;
  257. /* non std. config parameter. maximum count of embedded DataSetMessage in
  258. * one NetworkMessage */
  259. UA_UInt16 maxEncapsulatedDataSetMessageCount;
  260. } UA_WriterGroupConfig;
  261. void
  262. UA_WriterGroupConfig_deleteMembers(UA_WriterGroupConfig *writerGroupConfig);
  263. /* Add a new WriterGroup to an existing Connection */
  264. UA_StatusCode
  265. UA_Server_addWriterGroup(UA_Server *server, const UA_NodeId connection,
  266. const UA_WriterGroupConfig *writerGroupConfig,
  267. UA_NodeId *writerGroupIdentifier);
  268. /* Returns a deep copy of the config */
  269. UA_StatusCode
  270. UA_Server_getWriterGroupConfig(UA_Server *server, const UA_NodeId writerGroup,
  271. UA_WriterGroupConfig *config);
  272. UA_StatusCode
  273. UA_Server_updateWriterGroupConfig(UA_Server *server, UA_NodeId writerGroupIdentifier,
  274. const UA_WriterGroupConfig *config);
  275. UA_StatusCode
  276. UA_Server_removeWriterGroup(UA_Server *server, const UA_NodeId writerGroup);
  277. /**
  278. * .. _dsw:
  279. *
  280. * DataSetWriter
  281. * -------------
  282. * The DataSetWriters are the glue between the WriterGroups and the
  283. * PublishedDataSets. The DataSetWriter contain configuration parameters and
  284. * flags which influence the creation of DataSet messages. These messages are
  285. * encapsulated inside the network message. The DataSetWriter must be linked
  286. * with an existing PublishedDataSet and be contained within a WriterGroup. */
  287. typedef struct {
  288. UA_String name;
  289. UA_UInt16 dataSetWriterId;
  290. UA_DataSetFieldContentMask dataSetFieldContentMask;
  291. UA_UInt32 keyFrameCount;
  292. UA_ExtensionObject messageSettings;
  293. UA_String dataSetName;
  294. size_t dataSetWriterPropertiesSize;
  295. UA_KeyValuePair *dataSetWriterProperties;
  296. } UA_DataSetWriterConfig;
  297. void
  298. UA_DataSetWriterConfig_deleteMembers(UA_DataSetWriterConfig *pdsConfig);
  299. /* Add a new DataSetWriter to a existing WriterGroup. The DataSetWriter must be
  300. * coupled with a PublishedDataSet on creation.
  301. *
  302. * Part 14, 7.1.5.2.1 defines: The link between the PublishedDataSet and
  303. * DataSetWriter shall be created when an instance of the DataSetWriterType is
  304. * created. */
  305. UA_StatusCode
  306. UA_Server_addDataSetWriter(UA_Server *server,
  307. const UA_NodeId writerGroup, const UA_NodeId dataSet,
  308. const UA_DataSetWriterConfig *dataSetWriterConfig,
  309. UA_NodeId *writerIdentifier);
  310. /* Returns a deep copy of the config */
  311. UA_StatusCode
  312. UA_Server_getDataSetWriterConfig(UA_Server *server, const UA_NodeId dsw,
  313. UA_DataSetWriterConfig *config);
  314. UA_StatusCode
  315. UA_Server_removeDataSetWriter(UA_Server *server, const UA_NodeId dsw);
  316. #endif /* UA_ENABLE_PUBSUB */
  317. _UA_END_DECLS
  318. #endif /* UA_SERVER_PUBSUB_H */