ua_client.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424
  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 2015-2017 (c) Julius Pfrommer, Fraunhofer IOSB
  6. * Copyright 2015-2016 (c) Sten Grüner
  7. * Copyright 2015-2016 (c) Chris Iatrou
  8. * Copyright 2015-2017 (c) Florian Palm
  9. * Copyright 2015 (c) Holger Jeromin
  10. * Copyright 2015 (c) Oleksiy Vasylyev
  11. * Copyright 2017 (c) Stefan Profanter, fortiss GmbH
  12. * Copyright 2017 (c) Mark Giraud, Fraunhofer IOSB
  13. * Copyright 2018 (c) Thomas Stalder
  14. */
  15. #ifndef UA_CLIENT_H_
  16. #define UA_CLIENT_H_
  17. #ifdef __cplusplus
  18. extern "C" {
  19. #endif
  20. #include "ua_types.h"
  21. #include "ua_types_generated.h"
  22. #include "ua_types_generated_handling.h"
  23. #include "ua_plugin_network.h"
  24. #include "ua_plugin_log.h"
  25. #include "ua_client_config.h"
  26. /**
  27. * .. _client:
  28. *
  29. * Client
  30. * ======
  31. *
  32. * The client implementation allows remote access to all OPC UA services. For
  33. * convenience, some functionality has been wrapped in :ref:`high-level
  34. * abstractions <client-highlevel>`.
  35. *
  36. * **However**: At this time, the client does not yet contain its own thread or
  37. * event-driven main-loop. So the client will not perform any actions
  38. * automatically in the background. This is especially relevant for
  39. * subscriptions. The user will have to periodically call
  40. * `UA_Client_Subscriptions_manuallySendPublishRequest`. See also :ref:`here
  41. * <client-subscriptions>`.
  42. *
  43. *
  44. * .. include:: client_config.rst
  45. *
  46. * Client Lifecycle
  47. * ---------------- */
  48. /* Create a new client */
  49. UA_Client UA_EXPORT *
  50. UA_Client_new(UA_ClientConfig config);
  51. /* Get the client connection status */
  52. UA_ClientState UA_EXPORT
  53. UA_Client_getState(UA_Client *client);
  54. /* Get the client context */
  55. void UA_EXPORT *
  56. UA_Client_getContext(UA_Client *client);
  57. /* Reset a client */
  58. void UA_EXPORT
  59. UA_Client_reset(UA_Client *client);
  60. /* Delete a client */
  61. void UA_EXPORT
  62. UA_Client_delete(UA_Client *client);
  63. /**
  64. * Connect to a Server
  65. * ------------------- */
  66. /* Connect to the server
  67. *
  68. * @param client to use
  69. * @param endpointURL to connect (for example "opc.tcp://localhost:4840")
  70. * @return Indicates whether the operation succeeded or returns an error code */
  71. UA_StatusCode UA_EXPORT
  72. UA_Client_connect(UA_Client *client, const char *endpointUrl);
  73. /* Connect to the selected server with the given username and password
  74. *
  75. * @param client to use
  76. * @param endpointURL to connect (for example "opc.tcp://localhost:4840")
  77. * @param username
  78. * @param password
  79. * @return Indicates whether the operation succeeded or returns an error code */
  80. UA_StatusCode UA_EXPORT
  81. UA_Client_connect_username(UA_Client *client, const char *endpointUrl,
  82. const char *username, const char *password);
  83. /* Disconnect and close a connection to the selected server */
  84. UA_StatusCode UA_EXPORT
  85. UA_Client_disconnect(UA_Client *client);
  86. /* Close a connection to the selected server */
  87. UA_StatusCode UA_EXPORT
  88. UA_Client_close(UA_Client *client);
  89. /* Renew the underlying secure channel */
  90. UA_StatusCode UA_EXPORT
  91. UA_Client_manuallyRenewSecureChannel(UA_Client *client);
  92. /**
  93. * Discovery
  94. * --------- */
  95. /* Gets a list of endpoints of a server
  96. *
  97. * @param client to use. Must be connected to the same endpoint given in
  98. * serverUrl or otherwise in disconnected state.
  99. * @param serverUrl url to connect (for example "opc.tcp://localhost:4840")
  100. * @param endpointDescriptionsSize size of the array of endpoint descriptions
  101. * @param endpointDescriptions array of endpoint descriptions that is allocated
  102. * by the function (you need to free manually)
  103. * @return Indicates whether the operation succeeded or returns an error code */
  104. UA_StatusCode UA_EXPORT
  105. UA_Client_getEndpoints(UA_Client *client, const char *serverUrl,
  106. size_t* endpointDescriptionsSize,
  107. UA_EndpointDescription** endpointDescriptions);
  108. /* Gets a list of all registered servers at the given server.
  109. *
  110. * You can pass an optional filter for serverUris. If the given server is not registered,
  111. * an empty array will be returned. If the server is registered, only that application
  112. * description will be returned.
  113. *
  114. * Additionally you can optionally indicate which locale you want for the server name
  115. * in the returned application description. The array indicates the order of preference.
  116. * A server may have localized names.
  117. *
  118. * @param client to use. Must be connected to the same endpoint given in
  119. * serverUrl or otherwise in disconnected state.
  120. * @param serverUrl url to connect (for example "opc.tcp://localhost:4840")
  121. * @param serverUrisSize Optional filter for specific server uris
  122. * @param serverUris Optional filter for specific server uris
  123. * @param localeIdsSize Optional indication which locale you prefer
  124. * @param localeIds Optional indication which locale you prefer
  125. * @param registeredServersSize size of returned array, i.e., number of found/registered servers
  126. * @param registeredServers array containing found/registered servers
  127. * @return Indicates whether the operation succeeded or returns an error code */
  128. UA_StatusCode UA_EXPORT
  129. UA_Client_findServers(UA_Client *client, const char *serverUrl,
  130. size_t serverUrisSize, UA_String *serverUris,
  131. size_t localeIdsSize, UA_String *localeIds,
  132. size_t *registeredServersSize,
  133. UA_ApplicationDescription **registeredServers);
  134. /* Get a list of all known server in the network. Only supported by LDS servers.
  135. *
  136. * @param client to use. Must be connected to the same endpoint given in
  137. * serverUrl or otherwise in disconnected state.
  138. * @param serverUrl url to connect (for example "opc.tcp://localhost:4840")
  139. * @param startingRecordId optional. Only return the records with an ID higher
  140. * or equal the given. Can be used for pagination to only get a subset of
  141. * the full list
  142. * @param maxRecordsToReturn optional. Only return this number of records
  143. * @param serverCapabilityFilterSize optional. Filter the returned list to only
  144. * get servers with given capabilities, e.g. "LDS"
  145. * @param serverCapabilityFilter optional. Filter the returned list to only get
  146. * servers with given capabilities, e.g. "LDS"
  147. * @param serverOnNetworkSize size of returned array, i.e., number of
  148. * known/registered servers
  149. * @param serverOnNetwork array containing known/registered servers
  150. * @return Indicates whether the operation succeeded or returns an error code */
  151. UA_StatusCode UA_EXPORT
  152. UA_Client_findServersOnNetwork(UA_Client *client, const char *serverUrl,
  153. UA_UInt32 startingRecordId, UA_UInt32 maxRecordsToReturn,
  154. size_t serverCapabilityFilterSize, UA_String *serverCapabilityFilter,
  155. size_t *serverOnNetworkSize, UA_ServerOnNetwork **serverOnNetwork);
  156. /**
  157. * .. _client-services:
  158. *
  159. * Services
  160. * --------
  161. *
  162. * The raw OPC UA services are exposed to the client. But most of them time, it
  163. * is better to use the convenience functions from ``ua_client_highlevel.h``
  164. * that wrap the raw services. */
  165. /* Don't use this function. Use the type versions below instead. */
  166. void UA_EXPORT
  167. __UA_Client_Service(UA_Client *client, const void *request,
  168. const UA_DataType *requestType, void *response,
  169. const UA_DataType *responseType);
  170. /*
  171. * Attribute Service Set
  172. * ^^^^^^^^^^^^^^^^^^^^^ */
  173. static UA_INLINE UA_ReadResponse
  174. UA_Client_Service_read(UA_Client *client, const UA_ReadRequest request) {
  175. UA_ReadResponse response;
  176. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_READREQUEST],
  177. &response, &UA_TYPES[UA_TYPES_READRESPONSE]);
  178. return response;
  179. }
  180. static UA_INLINE UA_WriteResponse
  181. UA_Client_Service_write(UA_Client *client, const UA_WriteRequest request) {
  182. UA_WriteResponse response;
  183. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_WRITEREQUEST],
  184. &response, &UA_TYPES[UA_TYPES_WRITERESPONSE]);
  185. return response;
  186. }
  187. /*
  188. * Method Service Set
  189. * ^^^^^^^^^^^^^^^^^^ */
  190. #ifdef UA_ENABLE_METHODCALLS
  191. static UA_INLINE UA_CallResponse
  192. UA_Client_Service_call(UA_Client *client, const UA_CallRequest request) {
  193. UA_CallResponse response;
  194. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_CALLREQUEST],
  195. &response, &UA_TYPES[UA_TYPES_CALLRESPONSE]);
  196. return response;
  197. }
  198. #endif
  199. /*
  200. * NodeManagement Service Set
  201. * ^^^^^^^^^^^^^^^^^^^^^^^^^^ */
  202. static UA_INLINE UA_AddNodesResponse
  203. UA_Client_Service_addNodes(UA_Client *client, const UA_AddNodesRequest request) {
  204. UA_AddNodesResponse response;
  205. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_ADDNODESREQUEST],
  206. &response, &UA_TYPES[UA_TYPES_ADDNODESRESPONSE]);
  207. return response;
  208. }
  209. static UA_INLINE UA_AddReferencesResponse
  210. UA_Client_Service_addReferences(UA_Client *client,
  211. const UA_AddReferencesRequest request) {
  212. UA_AddReferencesResponse response;
  213. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_ADDREFERENCESREQUEST],
  214. &response, &UA_TYPES[UA_TYPES_ADDREFERENCESRESPONSE]);
  215. return response;
  216. }
  217. static UA_INLINE UA_DeleteNodesResponse
  218. UA_Client_Service_deleteNodes(UA_Client *client,
  219. const UA_DeleteNodesRequest request) {
  220. UA_DeleteNodesResponse response;
  221. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_DELETENODESREQUEST],
  222. &response, &UA_TYPES[UA_TYPES_DELETENODESRESPONSE]);
  223. return response;
  224. }
  225. static UA_INLINE UA_DeleteReferencesResponse
  226. UA_Client_Service_deleteReferences(UA_Client *client,
  227. const UA_DeleteReferencesRequest request) {
  228. UA_DeleteReferencesResponse response;
  229. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_DELETEREFERENCESREQUEST],
  230. &response, &UA_TYPES[UA_TYPES_DELETEREFERENCESRESPONSE]);
  231. return response;
  232. }
  233. /*
  234. * View Service Set
  235. * ^^^^^^^^^^^^^^^^ */
  236. static UA_INLINE UA_BrowseResponse
  237. UA_Client_Service_browse(UA_Client *client, const UA_BrowseRequest request) {
  238. UA_BrowseResponse response;
  239. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_BROWSEREQUEST],
  240. &response, &UA_TYPES[UA_TYPES_BROWSERESPONSE]);
  241. return response;
  242. }
  243. static UA_INLINE UA_BrowseNextResponse
  244. UA_Client_Service_browseNext(UA_Client *client,
  245. const UA_BrowseNextRequest request) {
  246. UA_BrowseNextResponse response;
  247. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_BROWSENEXTREQUEST],
  248. &response, &UA_TYPES[UA_TYPES_BROWSENEXTRESPONSE]);
  249. return response;
  250. }
  251. static UA_INLINE UA_TranslateBrowsePathsToNodeIdsResponse
  252. UA_Client_Service_translateBrowsePathsToNodeIds(UA_Client *client,
  253. const UA_TranslateBrowsePathsToNodeIdsRequest request) {
  254. UA_TranslateBrowsePathsToNodeIdsResponse response;
  255. __UA_Client_Service(client, &request,
  256. &UA_TYPES[UA_TYPES_TRANSLATEBROWSEPATHSTONODEIDSREQUEST],
  257. &response,
  258. &UA_TYPES[UA_TYPES_TRANSLATEBROWSEPATHSTONODEIDSRESPONSE]);
  259. return response;
  260. }
  261. static UA_INLINE UA_RegisterNodesResponse
  262. UA_Client_Service_registerNodes(UA_Client *client,
  263. const UA_RegisterNodesRequest request) {
  264. UA_RegisterNodesResponse response;
  265. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_REGISTERNODESREQUEST],
  266. &response, &UA_TYPES[UA_TYPES_REGISTERNODESRESPONSE]);
  267. return response;
  268. }
  269. static UA_INLINE UA_UnregisterNodesResponse
  270. UA_Client_Service_unregisterNodes(UA_Client *client,
  271. const UA_UnregisterNodesRequest request) {
  272. UA_UnregisterNodesResponse response;
  273. __UA_Client_Service(client, &request,
  274. &UA_TYPES[UA_TYPES_UNREGISTERNODESREQUEST],
  275. &response, &UA_TYPES[UA_TYPES_UNREGISTERNODESRESPONSE]);
  276. return response;
  277. }
  278. /*
  279. * Query Service Set
  280. * ^^^^^^^^^^^^^^^^^ */
  281. static UA_INLINE UA_QueryFirstResponse
  282. UA_Client_Service_queryFirst(UA_Client *client,
  283. const UA_QueryFirstRequest request) {
  284. UA_QueryFirstResponse response;
  285. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_QUERYFIRSTREQUEST],
  286. &response, &UA_TYPES[UA_TYPES_QUERYFIRSTRESPONSE]);
  287. return response;
  288. }
  289. static UA_INLINE UA_QueryNextResponse
  290. UA_Client_Service_queryNext(UA_Client *client,
  291. const UA_QueryNextRequest request) {
  292. UA_QueryNextResponse response;
  293. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_QUERYFIRSTREQUEST],
  294. &response, &UA_TYPES[UA_TYPES_QUERYFIRSTRESPONSE]);
  295. return response;
  296. }
  297. /**
  298. * .. _client-async-services:
  299. *
  300. * Asynchronous Services
  301. * ---------------------
  302. * All OPC UA services are asynchronous in nature. So several service calls can
  303. * be made without waiting for a response first. Responess may come in a
  304. * different ordering. */
  305. /* Listen on the network and process arriving asynchronous responses in the
  306. * background. Internal housekeeping and subscription management is done as
  307. * well. */
  308. UA_StatusCode UA_EXPORT
  309. UA_Client_runAsync(UA_Client *client, UA_UInt16 timeout);
  310. typedef void
  311. (*UA_ClientAsyncServiceCallback)(UA_Client *client, void *userdata,
  312. UA_UInt32 requestId, void *response,
  313. const UA_DataType *responseType);
  314. /* Use the type versions of this method. See below. However, the general
  315. * mechanism of async service calls is explained here.
  316. *
  317. * We say that an async service call has been dispatched once this method
  318. * returns UA_STATUSCODE_GOOD. If there is an error after an async service has
  319. * been dispatched, the callback is called with an "empty" response where the
  320. * statusCode has been set accordingly. This is also done if the client is
  321. * shutting down and the list of dispatched async services is emptied.
  322. *
  323. * The statusCode received when the client is shutting down is
  324. * UA_STATUSCODE_BADSHUTDOWN.
  325. *
  326. * The userdata and requestId arguments can be NULL. */
  327. UA_StatusCode UA_EXPORT
  328. __UA_Client_AsyncService(UA_Client *client, const void *request,
  329. const UA_DataType *requestType,
  330. UA_ClientAsyncServiceCallback callback,
  331. const UA_DataType *responseType,
  332. void *userdata, UA_UInt32 *requestId);
  333. static UA_INLINE UA_StatusCode
  334. UA_Client_AsyncService_read(UA_Client *client, const UA_ReadRequest *request,
  335. UA_ClientAsyncServiceCallback callback,
  336. void *userdata, UA_UInt32 *requestId) {
  337. return __UA_Client_AsyncService(client, (const void*)request,
  338. &UA_TYPES[UA_TYPES_READREQUEST], callback,
  339. &UA_TYPES[UA_TYPES_READRESPONSE],
  340. userdata, requestId);
  341. }
  342. static UA_INLINE UA_StatusCode
  343. UA_Client_AsyncService_write(UA_Client *client, const UA_WriteRequest *request,
  344. UA_ClientAsyncServiceCallback callback,
  345. void *userdata, UA_UInt32 *requestId) {
  346. return __UA_Client_AsyncService(client, (const void*)request,
  347. &UA_TYPES[UA_TYPES_WRITEREQUEST], callback,
  348. &UA_TYPES[UA_TYPES_WRITERESPONSE],
  349. userdata, requestId);
  350. }
  351. static UA_INLINE UA_StatusCode
  352. UA_Client_AsyncService_call(UA_Client *client, const UA_CallRequest *request,
  353. UA_ClientAsyncServiceCallback callback,
  354. void *userdata, UA_UInt32 *requestId) {
  355. return __UA_Client_AsyncService(client, (const void*)request,
  356. &UA_TYPES[UA_TYPES_CALLREQUEST], callback,
  357. &UA_TYPES[UA_TYPES_CALLRESPONSE],
  358. userdata, requestId);
  359. }
  360. static UA_INLINE UA_StatusCode
  361. UA_Client_AsyncService_browse(UA_Client *client, const UA_BrowseRequest *request,
  362. UA_ClientAsyncServiceCallback callback,
  363. void *userdata, UA_UInt32 *requestId) {
  364. return __UA_Client_AsyncService(client, (const void*)request,
  365. &UA_TYPES[UA_TYPES_BROWSEREQUEST], callback,
  366. &UA_TYPES[UA_TYPES_BROWSERESPONSE],
  367. userdata, requestId);
  368. }
  369. /**
  370. * .. toctree::
  371. *
  372. * client_highlevel
  373. * client_subscriptions */
  374. #ifdef __cplusplus
  375. } // extern "C"
  376. #endif
  377. #endif /* UA_CLIENT_H_ */