ua_services.h 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500
  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 2014-2017 (c) Fraunhofer IOSB (Author: Julius Pfrommer)
  6. * Copyright 2014-2017 (c) Florian Palm
  7. * Copyright 2015 (c) Sten Grüner
  8. * Copyright 2014 (c) LEvertz
  9. * Copyright 2015 (c) Chris Iatrou
  10. * Copyright 2015 (c) Christian Fimmers
  11. * Copyright 2015-2016 (c) Oleksiy Vasylyev
  12. * Copyright 2017 (c) Stefan Profanter, fortiss GmbH
  13. */
  14. #ifndef UA_SERVICES_H_
  15. #define UA_SERVICES_H_
  16. #include <open62541/server.h>
  17. #include "ua_session.h"
  18. _UA_BEGIN_DECLS
  19. /**
  20. * .. _services:
  21. *
  22. * Services
  23. * ========
  24. *
  25. * In OPC UA, all communication is based on service calls, each consisting of a
  26. * request and a response message. These messages are defined as data structures
  27. * with a binary encoding and listed in :ref:`generated-types`. Since all
  28. * Services are pre-defined in the standard, they cannot be modified by the
  29. * user. But you can use the :ref:`Call <method-services>` service to invoke
  30. * user-defined methods on the server.
  31. *
  32. * The following service signatures are internal and *not visible to users*.
  33. * Still, we present them here for an overview of the capabilities of OPC UA.
  34. * Please refer to the :ref:`client` and :ref:`server` API where the services
  35. * are exposed to end users. Please see part 4 of the OPC UA standard for the
  36. * authoritative definition of the service and their behaviour.
  37. *
  38. * Most services take as input the server, the current session and pointers to
  39. * the request and response structures. Possible error codes are returned as
  40. * part of the response. */
  41. typedef void (*UA_Service)(UA_Server*, UA_Session*,
  42. const void *request, void *response);
  43. typedef UA_StatusCode (*UA_InSituService)(UA_Server*, UA_Session*, UA_MessageContext *mc,
  44. const void *request, UA_ResponseHeader *rh);
  45. /**
  46. * Discovery Service Set
  47. * ---------------------
  48. * This Service Set defines Services used to discover the Endpoints implemented
  49. * by a Server and to read the security configuration for those Endpoints.
  50. *
  51. * FindServers Service
  52. * ^^^^^^^^^^^^^^^^^^^
  53. * Returns the Servers known to a Server or Discovery Server. The Client may
  54. * reduce the number of results returned by specifying filter criteria */
  55. void Service_FindServers(UA_Server *server, UA_Session *session,
  56. const UA_FindServersRequest *request,
  57. UA_FindServersResponse *response);
  58. /**
  59. * GetEndpoints Service
  60. * ^^^^^^^^^^^^^^^^^^^^
  61. * Returns the Endpoints supported by a Server and all of the configuration
  62. * information required to establish a SecureChannel and a Session. */
  63. void Service_GetEndpoints(UA_Server *server, UA_Session *session,
  64. const UA_GetEndpointsRequest *request,
  65. UA_GetEndpointsResponse *response);
  66. #ifdef UA_ENABLE_DISCOVERY
  67. # ifdef UA_ENABLE_DISCOVERY_MULTICAST
  68. /**
  69. * FindServersOnNetwork Service
  70. * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  71. * Returns the Servers known to a Discovery Server. Unlike FindServer,
  72. * this Service is only implemented by Discovery Servers. It additionally
  73. * Returns servery which may have been detected trough Multicast */
  74. void Service_FindServersOnNetwork(UA_Server *server, UA_Session *session,
  75. const UA_FindServersOnNetworkRequest *request,
  76. UA_FindServersOnNetworkResponse *response);
  77. # endif /* UA_ENABLE_DISCOVERY_MULTICAST */
  78. /**
  79. * RegisterServer
  80. * ^^^^^^^^^^^^^^
  81. * Registers a remote server in the local discovery service. */
  82. void Service_RegisterServer(UA_Server *server, UA_Session *session,
  83. const UA_RegisterServerRequest *request,
  84. UA_RegisterServerResponse *response);
  85. /**
  86. * RegisterServer2
  87. * ^^^^^^^^^^^^^^^
  88. * This Service allows a Server to register its DiscoveryUrls and capabilities
  89. * with a Discovery Server. It extends the registration information from
  90. * RegisterServer with information necessary for FindServersOnNetwork. */
  91. void Service_RegisterServer2(UA_Server *server, UA_Session *session,
  92. const UA_RegisterServer2Request *request,
  93. UA_RegisterServer2Response *response);
  94. #endif /* UA_ENABLE_DISCOVERY */
  95. /**
  96. * SecureChannel Service Set
  97. * -------------------------
  98. * This Service Set defines Services used to open a communication channel that
  99. * ensures the confidentiality and Integrity of all Messages exchanged with the
  100. * Server.
  101. *
  102. * OpenSecureChannel Service
  103. * ^^^^^^^^^^^^^^^^^^^^^^^^^
  104. * Open or renew a SecureChannel that can be used to ensure Confidentiality and
  105. * Integrity for Message exchange during a Session. */
  106. void Service_OpenSecureChannel(UA_Server *server, UA_SecureChannel* channel,
  107. const UA_OpenSecureChannelRequest *request,
  108. UA_OpenSecureChannelResponse *response);
  109. /**
  110. * CloseSecureChannel Service
  111. * ^^^^^^^^^^^^^^^^^^^^^^^^^^
  112. * Used to terminate a SecureChannel. */
  113. void Service_CloseSecureChannel(UA_Server *server, UA_SecureChannel *channel);
  114. /**
  115. * Session Service Set
  116. * -------------------
  117. * This Service Set defines Services for an application layer connection
  118. * establishment in the context of a Session.
  119. *
  120. * CreateSession Service
  121. * ^^^^^^^^^^^^^^^^^^^^^
  122. * Used by an OPC UA Client to create a Session and the Server returns two
  123. * values which uniquely identify the Session. The first value is the sessionId
  124. * which is used to identify the Session in the audit logs and in the Server's
  125. * address space. The second is the authenticationToken which is used to
  126. * associate an incoming request with a Session. */
  127. void Service_CreateSession(UA_Server *server, UA_SecureChannel *channel,
  128. const UA_CreateSessionRequest *request,
  129. UA_CreateSessionResponse *response);
  130. /**
  131. * ActivateSession
  132. * ^^^^^^^^^^^^^^^
  133. * Used by the Client to submit its SoftwareCertificates to the Server for
  134. * validation and to specify the identity of the user associated with the
  135. * Session. This Service request shall be issued by the Client before it issues
  136. * any other Service request after CreateSession. Failure to do so shall cause
  137. * the Server to close the Session. */
  138. void Service_ActivateSession(UA_Server *server, UA_SecureChannel *channel,
  139. UA_Session *session,
  140. const UA_ActivateSessionRequest *request,
  141. UA_ActivateSessionResponse *response);
  142. /**
  143. * CloseSession
  144. * ^^^^^^^^^^^^
  145. * Used to terminate a Session. */
  146. void Service_CloseSession(UA_Server *server, UA_Session *session,
  147. const UA_CloseSessionRequest *request,
  148. UA_CloseSessionResponse *response);
  149. /**
  150. * Cancel Service
  151. * ^^^^^^^^^^^^^^
  152. * Used to cancel outstanding Service requests. Successfully cancelled service
  153. * requests shall respond with Bad_RequestCancelledByClient. */
  154. /* Not Implemented */
  155. /**
  156. * NodeManagement Service Set
  157. * --------------------------
  158. * This Service Set defines Services to add and delete AddressSpace Nodes and
  159. * References between them. All added Nodes continue to exist in the
  160. * AddressSpace even if the Client that created them disconnects from the
  161. * Server.
  162. *
  163. * AddNodes Service
  164. * ^^^^^^^^^^^^^^^^
  165. * Used to add one or more Nodes into the AddressSpace hierarchy. */
  166. void Service_AddNodes(UA_Server *server, UA_Session *session,
  167. const UA_AddNodesRequest *request,
  168. UA_AddNodesResponse *response);
  169. /**
  170. * AddReferences Service
  171. * ^^^^^^^^^^^^^^^^^^^^^
  172. * Used to add one or more References to one or more Nodes. */
  173. void Service_AddReferences(UA_Server *server, UA_Session *session,
  174. const UA_AddReferencesRequest *request,
  175. UA_AddReferencesResponse *response);
  176. /**
  177. * DeleteNodes Service
  178. * ^^^^^^^^^^^^^^^^^^^
  179. * Used to delete one or more Nodes from the AddressSpace. */
  180. void Service_DeleteNodes(UA_Server *server, UA_Session *session,
  181. const UA_DeleteNodesRequest *request,
  182. UA_DeleteNodesResponse *response);
  183. /**
  184. * DeleteReferences
  185. * ^^^^^^^^^^^^^^^^
  186. * Used to delete one or more References of a Node. */
  187. void Service_DeleteReferences(UA_Server *server, UA_Session *session,
  188. const UA_DeleteReferencesRequest *request,
  189. UA_DeleteReferencesResponse *response);
  190. /**
  191. * .. _view-services:
  192. *
  193. * View Service Set
  194. * ----------------
  195. * Clients use the browse Services of the View Service Set to navigate through
  196. * the AddressSpace or through a View which is a subset of the AddressSpace.
  197. *
  198. * Browse Service
  199. * ^^^^^^^^^^^^^^
  200. * Used to discover the References of a specified Node. The browse can be
  201. * further limited by the use of a View. This Browse Service also supports a
  202. * primitive filtering capability. */
  203. void Service_Browse(UA_Server *server, UA_Session *session,
  204. const UA_BrowseRequest *request,
  205. UA_BrowseResponse *response);
  206. /**
  207. * BrowseNext Service
  208. * ^^^^^^^^^^^^^^^^^^
  209. * Used to request the next set of Browse or BrowseNext response information
  210. * that is too large to be sent in a single response. "Too large" in this
  211. * context means that the Server is not able to return a larger response or that
  212. * the number of results to return exceeds the maximum number of results to
  213. * return that was specified by the Client in the original Browse request. */
  214. void Service_BrowseNext(UA_Server *server, UA_Session *session,
  215. const UA_BrowseNextRequest *request,
  216. UA_BrowseNextResponse *response);
  217. /**
  218. * TranslateBrowsePathsToNodeIds Service
  219. * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  220. * Used to translate textual node paths to their respective ids. */
  221. void Service_TranslateBrowsePathsToNodeIds(UA_Server *server, UA_Session *session,
  222. const UA_TranslateBrowsePathsToNodeIdsRequest *request,
  223. UA_TranslateBrowsePathsToNodeIdsResponse *response);
  224. /**
  225. * RegisterNodes Service
  226. * ^^^^^^^^^^^^^^^^^^^^^
  227. * Used by Clients to register the Nodes that they know they will access
  228. * repeatedly (e.g. Write, Call). It allows Servers to set up anything needed so
  229. * that the access operations will be more efficient. */
  230. void Service_RegisterNodes(UA_Server *server, UA_Session *session,
  231. const UA_RegisterNodesRequest *request,
  232. UA_RegisterNodesResponse *response);
  233. /**
  234. * UnregisterNodes Service
  235. * ^^^^^^^^^^^^^^^^^^^^^^^
  236. * This Service is used to unregister NodeIds that have been obtained via the
  237. * RegisterNodes service. */
  238. void Service_UnregisterNodes(UA_Server *server, UA_Session *session,
  239. const UA_UnregisterNodesRequest *request,
  240. UA_UnregisterNodesResponse *response);
  241. /**
  242. * Query Service Set
  243. * -----------------
  244. * This Service Set is used to issue a Query to a Server. OPC UA Query is
  245. * generic in that it provides an underlying storage mechanism independent Query
  246. * capability that can be used to access a wide variety of OPC UA data stores
  247. * and information management systems. OPC UA Query permits a Client to access
  248. * data maintained by a Server without any knowledge of the logical schema used
  249. * for internal storage of the data. Knowledge of the AddressSpace is
  250. * sufficient.
  251. *
  252. * QueryFirst Service
  253. * ^^^^^^^^^^^^^^^^^^
  254. * This Service is used to issue a Query request to the Server. */
  255. /* Not Implemented */
  256. /**
  257. * QueryNext Service
  258. * ^^^^^^^^^^^^^^^^^
  259. * This Service is used to request the next set of QueryFirst or QueryNext
  260. * response information that is too large to be sent in a single response. */
  261. /* Not Impelemented */
  262. /**
  263. * Attribute Service Set
  264. * ---------------------
  265. * This Service Set provides Services to access Attributes that are part of
  266. * Nodes.
  267. *
  268. * Read Service
  269. * ^^^^^^^^^^^^
  270. * Used to read attributes of nodes. For constructed attribute values whose
  271. * elements are indexed, such as an array, this Service allows Clients to read
  272. * the entire set of indexed values as a composite, to read individual elements
  273. * or to read ranges of elements of the composite. */
  274. UA_StatusCode Service_Read(UA_Server *server, UA_Session *session, UA_MessageContext *mc,
  275. const UA_ReadRequest *request, UA_ResponseHeader *responseHeader);
  276. /**
  277. * Write Service
  278. * ^^^^^^^^^^^^^
  279. * Used to write attributes of nodes. For constructed attribute values whose
  280. * elements are indexed, such as an array, this Service allows Clients to write
  281. * the entire set of indexed values as a composite, to write individual elements
  282. * or to write ranges of elements of the composite. */
  283. void Service_Write(UA_Server *server, UA_Session *session,
  284. const UA_WriteRequest *request,
  285. UA_WriteResponse *response);
  286. /**
  287. * HistoryRead Service
  288. * ^^^^^^^^^^^^^^^^^^^
  289. * Used to read historical values or Events of one or more Nodes. Servers may
  290. * make historical values available to Clients using this Service, although the
  291. * historical values themselves are not visible in the AddressSpace. */
  292. #ifdef UA_ENABLE_HISTORIZING
  293. void Service_HistoryRead(UA_Server *server, UA_Session *session,
  294. const UA_HistoryReadRequest *request,
  295. UA_HistoryReadResponse *response);
  296. /**
  297. * HistoryUpdate Service
  298. * ^^^^^^^^^^^^^^^^^^^^^
  299. * Used to update historical values or Events of one or more Nodes. Several
  300. * request parameters indicate how the Server is to update the historical value
  301. * or Event. Valid actions are Insert, Replace or Delete. */
  302. void
  303. Service_HistoryUpdate(UA_Server *server, UA_Session *session,
  304. const UA_HistoryUpdateRequest *request,
  305. UA_HistoryUpdateResponse *response);
  306. #endif
  307. /**
  308. * .. _method-services:
  309. *
  310. * Method Service Set
  311. * ------------------
  312. * The Method Service Set defines the means to invoke methods. A method shall be
  313. * a component of an Object. See the section on :ref:`MethodNodes <methodnode>`
  314. * for more information.
  315. *
  316. * Call Service
  317. * ^^^^^^^^^^^^
  318. * Used to call (invoke) a methods. Each method call is invoked within the
  319. * context of an existing Session. If the Session is terminated, the results of
  320. * the method's execution cannot be returned to the Client and are discarded. */
  321. #ifdef UA_ENABLE_METHODCALLS
  322. void Service_Call(UA_Server *server, UA_Session *session,
  323. const UA_CallRequest *request,
  324. UA_CallResponse *response);
  325. #endif
  326. #ifdef UA_ENABLE_SUBSCRIPTIONS
  327. /**
  328. * MonitoredItem Service Set
  329. * -------------------------
  330. * Clients define MonitoredItems to subscribe to data and Events. Each
  331. * MonitoredItem identifies the item to be monitored and the Subscription to use
  332. * to send Notifications. The item to be monitored may be any Node Attribute.
  333. *
  334. * CreateMonitoredItems Service
  335. * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  336. * Used to create and add one or more MonitoredItems to a Subscription. A
  337. * MonitoredItem is deleted automatically by the Server when the Subscription is
  338. * deleted. Deleting a MonitoredItem causes its entire set of triggered item
  339. * links to be deleted, but has no effect on the MonitoredItems referenced by
  340. * the triggered items. */
  341. void Service_CreateMonitoredItems(UA_Server *server, UA_Session *session,
  342. const UA_CreateMonitoredItemsRequest *request,
  343. UA_CreateMonitoredItemsResponse *response);
  344. /**
  345. * DeleteMonitoredItems Service
  346. * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  347. * Used to remove one or more MonitoredItems of a Subscription. When a
  348. * MonitoredItem is deleted, its triggered item links are also deleted. */
  349. void Service_DeleteMonitoredItems(UA_Server *server, UA_Session *session,
  350. const UA_DeleteMonitoredItemsRequest *request,
  351. UA_DeleteMonitoredItemsResponse *response);
  352. /**
  353. * ModifyMonitoredItems Service
  354. * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  355. * Used to modify MonitoredItems of a Subscription. Changes to the MonitoredItem
  356. * settings shall be applied immediately by the Server. They take effect as soon
  357. * as practical but not later than twice the new revisedSamplingInterval.
  358. *
  359. * Illegal request values for parameters that can be revised do not generate
  360. * errors. Instead the server will choose default values and indicate them in
  361. * the corresponding revised parameter. */
  362. void Service_ModifyMonitoredItems(UA_Server *server, UA_Session *session,
  363. const UA_ModifyMonitoredItemsRequest *request,
  364. UA_ModifyMonitoredItemsResponse *response);
  365. /**
  366. * SetMonitoringMode Service
  367. * ^^^^^^^^^^^^^^^^^^^^^^^^^
  368. * Used to set the monitoring mode for one or more MonitoredItems of a
  369. * Subscription. */
  370. void Service_SetMonitoringMode(UA_Server *server, UA_Session *session,
  371. const UA_SetMonitoringModeRequest *request,
  372. UA_SetMonitoringModeResponse *response);
  373. /**
  374. * SetTriggering Service
  375. * ^^^^^^^^^^^^^^^^^^^^^
  376. * Used to create and delete triggering links for a triggering item. */
  377. /* Not Implemented */
  378. /**
  379. * Subscription Service Set
  380. * ------------------------
  381. * Subscriptions are used to report Notifications to the Client.
  382. *
  383. * CreateSubscription Service
  384. * ^^^^^^^^^^^^^^^^^^^^^^^^^^
  385. * Used to create a Subscription. Subscriptions monitor a set of MonitoredItems
  386. * for Notifications and return them to the Client in response to Publish
  387. * requests. */
  388. void Service_CreateSubscription(UA_Server *server, UA_Session *session,
  389. const UA_CreateSubscriptionRequest *request,
  390. UA_CreateSubscriptionResponse *response);
  391. /**
  392. * ModifySubscription Service
  393. * ^^^^^^^^^^^^^^^^^^^^^^^^^^
  394. * Used to modify a Subscription. */
  395. void Service_ModifySubscription(UA_Server *server, UA_Session *session,
  396. const UA_ModifySubscriptionRequest *request,
  397. UA_ModifySubscriptionResponse *response);
  398. /**
  399. * SetPublishingMode Service
  400. * ^^^^^^^^^^^^^^^^^^^^^^^^^
  401. * Used to enable sending of Notifications on one or more Subscriptions. */
  402. void Service_SetPublishingMode(UA_Server *server, UA_Session *session,
  403. const UA_SetPublishingModeRequest *request,
  404. UA_SetPublishingModeResponse *response);
  405. /**
  406. * Publish Service
  407. * ^^^^^^^^^^^^^^^
  408. * Used for two purposes. First, it is used to acknowledge the receipt of
  409. * NotificationMessages for one or more Subscriptions. Second, it is used to
  410. * request the Server to return a NotificationMessage or a keep-alive
  411. * Message.
  412. *
  413. * Note that the service signature is an exception and does not contain a
  414. * pointer to a PublishResponse. That is because the service queues up publish
  415. * requests internally and sends responses asynchronously based on timeouts. */
  416. void Service_Publish(UA_Server *server, UA_Session *session,
  417. const UA_PublishRequest *request, UA_UInt32 requestId);
  418. /**
  419. * Republish Service
  420. * ^^^^^^^^^^^^^^^^^
  421. * Requests the Subscription to republish a NotificationMessage from its
  422. * retransmission queue. */
  423. void Service_Republish(UA_Server *server, UA_Session *session,
  424. const UA_RepublishRequest *request,
  425. UA_RepublishResponse *response);
  426. /**
  427. * DeleteSubscriptions Service
  428. * ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  429. * Invoked to delete one or more Subscriptions that belong to the Client's
  430. * Session. */
  431. void Service_DeleteSubscriptions(UA_Server *server, UA_Session *session,
  432. const UA_DeleteSubscriptionsRequest *request,
  433. UA_DeleteSubscriptionsResponse *response);
  434. /**
  435. * TransferSubscription Service
  436. * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  437. * Used to transfer a Subscription and its MonitoredItems from one Session to
  438. * another. For example, a Client may need to reopen a Session and then transfer
  439. * its Subscriptions to that Session. It may also be used by one Client to take
  440. * over a Subscription from another Client by transferring the Subscription to
  441. * its Session. */
  442. /* Not Implemented */
  443. #endif /* UA_ENABLE_SUBSCRIPTIONS */
  444. _UA_END_DECLS
  445. #endif /* UA_SERVICES_H_ */