ua_client.h 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526
  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) Fraunhofer IOSB (Author: Julius Pfrommer)
  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, Blue Time Concept SA
  14. * Copyright 2018 (c) Kalycito Infotech Private Limited
  15. */
  16. #ifndef UA_CLIENT_H_
  17. #define UA_CLIENT_H_
  18. #include "ua_types.h"
  19. #include "ua_types_generated.h"
  20. #include "ua_types_generated_handling.h"
  21. #include "ua_plugin_securitypolicy.h"
  22. #include "ua_plugin_network.h"
  23. #include "ua_plugin_log.h"
  24. #include "ua_client_config.h"
  25. #include "ua_nodeids.h"
  26. _UA_BEGIN_DECLS
  27. /**
  28. * .. _client:
  29. *
  30. * Client
  31. * ======
  32. *
  33. * The client implementation allows remote access to all OPC UA services. For
  34. * convenience, some functionality has been wrapped in :ref:`high-level
  35. * abstractions <client-highlevel>`.
  36. *
  37. * **However**: At this time, the client does not yet contain its own thread or
  38. * event-driven main-loop. So the client will not perform any actions
  39. * automatically in the background. This is especially relevant for
  40. * subscriptions. The user will have to periodically call
  41. * `UA_Client_Subscriptions_manuallySendPublishRequest`. See also :ref:`here
  42. * <client-subscriptions>`.
  43. *
  44. *
  45. * .. include:: client_config.rst
  46. *
  47. * Client Lifecycle
  48. * ---------------- */
  49. /* Create a new client */
  50. UA_Client UA_EXPORT *
  51. UA_Client_new(void);
  52. /* Get the client connection status */
  53. UA_ClientState UA_EXPORT
  54. UA_Client_getState(UA_Client *client);
  55. /* Get the client configuration */
  56. UA_EXPORT UA_ClientConfig *
  57. UA_Client_getConfig(UA_Client *client);
  58. /* Get the client context */
  59. static UA_INLINE void *
  60. UA_Client_getContext(UA_Client *client) {
  61. UA_ClientConfig *config = UA_Client_getConfig(client);
  62. if(!config)
  63. return NULL;
  64. return config->clientContext;
  65. }
  66. /* Reset a client */
  67. void UA_EXPORT
  68. UA_Client_reset(UA_Client *client);
  69. /* Delete a client */
  70. void UA_EXPORT
  71. UA_Client_delete(UA_Client *client);
  72. /**
  73. * Connect to a Server
  74. * ------------------- */
  75. typedef void (*UA_ClientAsyncServiceCallback)(UA_Client *client, void *userdata,
  76. UA_UInt32 requestId, void *response);
  77. /* Connect to the server
  78. *
  79. * @param client to use
  80. * @param endpointURL to connect (for example "opc.tcp://localhost:4840")
  81. * @return Indicates whether the operation succeeded or returns an error code */
  82. UA_StatusCode UA_EXPORT
  83. UA_Client_connect(UA_Client *client, const char *endpointUrl);
  84. UA_StatusCode UA_EXPORT
  85. UA_Client_connect_async(UA_Client *client, const char *endpointUrl,
  86. UA_ClientAsyncServiceCallback callback,
  87. void *connected);
  88. /* Connect to the server without creating a session
  89. *
  90. * @param client to use
  91. * @param endpointURL to connect (for example "opc.tcp://localhost:4840")
  92. * @return Indicates whether the operation succeeded or returns an error code */
  93. UA_StatusCode UA_EXPORT
  94. UA_Client_connect_noSession(UA_Client *client, const char *endpointUrl);
  95. /* Connect to the selected server with the given username and password
  96. *
  97. * @param client to use
  98. * @param endpointURL to connect (for example "opc.tcp://localhost:4840")
  99. * @param username
  100. * @param password
  101. * @return Indicates whether the operation succeeded or returns an error code */
  102. UA_StatusCode UA_EXPORT
  103. UA_Client_connect_username(UA_Client *client, const char *endpointUrl,
  104. const char *username, const char *password);
  105. /* Disconnect and close a connection to the selected server */
  106. UA_StatusCode UA_EXPORT
  107. UA_Client_disconnect(UA_Client *client);
  108. UA_StatusCode UA_EXPORT
  109. UA_Client_disconnect_async(UA_Client *client, UA_UInt32 *requestId);
  110. /* Close a connection to the selected server */
  111. UA_DEPRECATED static UA_INLINE UA_StatusCode
  112. UA_Client_close(UA_Client *client) {
  113. return UA_Client_disconnect(client);
  114. }
  115. /**
  116. * Discovery
  117. * --------- */
  118. /* Gets a list of endpoints of a server
  119. *
  120. * @param client to use. Must be connected to the same endpoint given in
  121. * serverUrl or otherwise in disconnected state.
  122. * @param serverUrl url to connect (for example "opc.tcp://localhost:4840")
  123. * @param endpointDescriptionsSize size of the array of endpoint descriptions
  124. * @param endpointDescriptions array of endpoint descriptions that is allocated
  125. * by the function (you need to free manually)
  126. * @return Indicates whether the operation succeeded or returns an error code */
  127. UA_StatusCode UA_EXPORT
  128. UA_Client_getEndpoints(UA_Client *client, const char *serverUrl,
  129. size_t* endpointDescriptionsSize,
  130. UA_EndpointDescription** endpointDescriptions);
  131. /* Gets a list of all registered servers at the given server.
  132. *
  133. * You can pass an optional filter for serverUris. If the given server is not registered,
  134. * an empty array will be returned. If the server is registered, only that application
  135. * description will be returned.
  136. *
  137. * Additionally you can optionally indicate which locale you want for the server name
  138. * in the returned application description. The array indicates the order of preference.
  139. * A server may have localized names.
  140. *
  141. * @param client to use. Must be connected to the same endpoint given in
  142. * serverUrl or otherwise in disconnected state.
  143. * @param serverUrl url to connect (for example "opc.tcp://localhost:4840")
  144. * @param serverUrisSize Optional filter for specific server uris
  145. * @param serverUris Optional filter for specific server uris
  146. * @param localeIdsSize Optional indication which locale you prefer
  147. * @param localeIds Optional indication which locale you prefer
  148. * @param registeredServersSize size of returned array, i.e., number of found/registered servers
  149. * @param registeredServers array containing found/registered servers
  150. * @return Indicates whether the operation succeeded or returns an error code */
  151. UA_StatusCode UA_EXPORT
  152. UA_Client_findServers(UA_Client *client, const char *serverUrl,
  153. size_t serverUrisSize, UA_String *serverUris,
  154. size_t localeIdsSize, UA_String *localeIds,
  155. size_t *registeredServersSize,
  156. UA_ApplicationDescription **registeredServers);
  157. #ifdef UA_ENABLE_DISCOVERY
  158. /* Get a list of all known server in the network. Only supported by LDS servers.
  159. *
  160. * @param client to use. Must be connected to the same endpoint given in
  161. * serverUrl or otherwise in disconnected state.
  162. * @param serverUrl url to connect (for example "opc.tcp://localhost:4840")
  163. * @param startingRecordId optional. Only return the records with an ID higher
  164. * or equal the given. Can be used for pagination to only get a subset of
  165. * the full list
  166. * @param maxRecordsToReturn optional. Only return this number of records
  167. * @param serverCapabilityFilterSize optional. Filter the returned list to only
  168. * get servers with given capabilities, e.g. "LDS"
  169. * @param serverCapabilityFilter optional. Filter the returned list to only get
  170. * servers with given capabilities, e.g. "LDS"
  171. * @param serverOnNetworkSize size of returned array, i.e., number of
  172. * known/registered servers
  173. * @param serverOnNetwork array containing known/registered servers
  174. * @return Indicates whether the operation succeeded or returns an error code */
  175. UA_StatusCode UA_EXPORT
  176. UA_Client_findServersOnNetwork(UA_Client *client, const char *serverUrl,
  177. UA_UInt32 startingRecordId, UA_UInt32 maxRecordsToReturn,
  178. size_t serverCapabilityFilterSize, UA_String *serverCapabilityFilter,
  179. size_t *serverOnNetworkSize, UA_ServerOnNetwork **serverOnNetwork);
  180. #endif
  181. /**
  182. * .. _client-services:
  183. *
  184. * Services
  185. * --------
  186. *
  187. * The raw OPC UA services are exposed to the client. But most of them time, it
  188. * is better to use the convenience functions from ``ua_client_highlevel.h``
  189. * that wrap the raw services. */
  190. /* Don't use this function. Use the type versions below instead. */
  191. void UA_EXPORT
  192. __UA_Client_Service(UA_Client *client, const void *request,
  193. const UA_DataType *requestType, void *response,
  194. const UA_DataType *responseType);
  195. /*
  196. * Attribute Service Set
  197. * ^^^^^^^^^^^^^^^^^^^^^ */
  198. static UA_INLINE UA_ReadResponse
  199. UA_Client_Service_read(UA_Client *client, const UA_ReadRequest request) {
  200. UA_ReadResponse response;
  201. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_READREQUEST],
  202. &response, &UA_TYPES[UA_TYPES_READRESPONSE]);
  203. return response;
  204. }
  205. static UA_INLINE UA_WriteResponse
  206. UA_Client_Service_write(UA_Client *client, const UA_WriteRequest request) {
  207. UA_WriteResponse response;
  208. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_WRITEREQUEST],
  209. &response, &UA_TYPES[UA_TYPES_WRITERESPONSE]);
  210. return response;
  211. }
  212. /*
  213. * Historical Access Service Set
  214. * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ */
  215. #ifdef UA_ENABLE_HISTORIZING
  216. static UA_INLINE UA_HistoryReadResponse
  217. UA_Client_Service_historyRead(UA_Client *client, const UA_HistoryReadRequest request) {
  218. UA_HistoryReadResponse response;
  219. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_HISTORYREADREQUEST],
  220. &response, &UA_TYPES[UA_TYPES_HISTORYREADRESPONSE]);
  221. return response;
  222. }
  223. #endif
  224. /*
  225. * Method Service Set
  226. * ^^^^^^^^^^^^^^^^^^ */
  227. #ifdef UA_ENABLE_METHODCALLS
  228. static UA_INLINE UA_CallResponse
  229. UA_Client_Service_call(UA_Client *client, const UA_CallRequest request) {
  230. UA_CallResponse response;
  231. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_CALLREQUEST],
  232. &response, &UA_TYPES[UA_TYPES_CALLRESPONSE]);
  233. return response;
  234. }
  235. #endif
  236. /*
  237. * NodeManagement Service Set
  238. * ^^^^^^^^^^^^^^^^^^^^^^^^^^ */
  239. static UA_INLINE UA_AddNodesResponse
  240. UA_Client_Service_addNodes(UA_Client *client, const UA_AddNodesRequest request) {
  241. UA_AddNodesResponse response;
  242. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_ADDNODESREQUEST],
  243. &response, &UA_TYPES[UA_TYPES_ADDNODESRESPONSE]);
  244. return response;
  245. }
  246. static UA_INLINE UA_AddReferencesResponse
  247. UA_Client_Service_addReferences(UA_Client *client,
  248. const UA_AddReferencesRequest request) {
  249. UA_AddReferencesResponse response;
  250. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_ADDREFERENCESREQUEST],
  251. &response, &UA_TYPES[UA_TYPES_ADDREFERENCESRESPONSE]);
  252. return response;
  253. }
  254. static UA_INLINE UA_DeleteNodesResponse
  255. UA_Client_Service_deleteNodes(UA_Client *client,
  256. const UA_DeleteNodesRequest request) {
  257. UA_DeleteNodesResponse response;
  258. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_DELETENODESREQUEST],
  259. &response, &UA_TYPES[UA_TYPES_DELETENODESRESPONSE]);
  260. return response;
  261. }
  262. static UA_INLINE UA_DeleteReferencesResponse
  263. UA_Client_Service_deleteReferences(UA_Client *client,
  264. const UA_DeleteReferencesRequest request) {
  265. UA_DeleteReferencesResponse response;
  266. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_DELETEREFERENCESREQUEST],
  267. &response, &UA_TYPES[UA_TYPES_DELETEREFERENCESRESPONSE]);
  268. return response;
  269. }
  270. /*
  271. * View Service Set
  272. * ^^^^^^^^^^^^^^^^ */
  273. static UA_INLINE UA_BrowseResponse
  274. UA_Client_Service_browse(UA_Client *client, const UA_BrowseRequest request) {
  275. UA_BrowseResponse response;
  276. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_BROWSEREQUEST],
  277. &response, &UA_TYPES[UA_TYPES_BROWSERESPONSE]);
  278. return response;
  279. }
  280. static UA_INLINE UA_BrowseNextResponse
  281. UA_Client_Service_browseNext(UA_Client *client,
  282. const UA_BrowseNextRequest request) {
  283. UA_BrowseNextResponse response;
  284. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_BROWSENEXTREQUEST],
  285. &response, &UA_TYPES[UA_TYPES_BROWSENEXTRESPONSE]);
  286. return response;
  287. }
  288. static UA_INLINE UA_TranslateBrowsePathsToNodeIdsResponse
  289. UA_Client_Service_translateBrowsePathsToNodeIds(UA_Client *client,
  290. const UA_TranslateBrowsePathsToNodeIdsRequest request) {
  291. UA_TranslateBrowsePathsToNodeIdsResponse response;
  292. __UA_Client_Service(client, &request,
  293. &UA_TYPES[UA_TYPES_TRANSLATEBROWSEPATHSTONODEIDSREQUEST],
  294. &response,
  295. &UA_TYPES[UA_TYPES_TRANSLATEBROWSEPATHSTONODEIDSRESPONSE]);
  296. return response;
  297. }
  298. static UA_INLINE UA_RegisterNodesResponse
  299. UA_Client_Service_registerNodes(UA_Client *client,
  300. const UA_RegisterNodesRequest request) {
  301. UA_RegisterNodesResponse response;
  302. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_REGISTERNODESREQUEST],
  303. &response, &UA_TYPES[UA_TYPES_REGISTERNODESRESPONSE]);
  304. return response;
  305. }
  306. static UA_INLINE UA_UnregisterNodesResponse
  307. UA_Client_Service_unregisterNodes(UA_Client *client,
  308. const UA_UnregisterNodesRequest request) {
  309. UA_UnregisterNodesResponse response;
  310. __UA_Client_Service(client, &request,
  311. &UA_TYPES[UA_TYPES_UNREGISTERNODESREQUEST],
  312. &response, &UA_TYPES[UA_TYPES_UNREGISTERNODESRESPONSE]);
  313. return response;
  314. }
  315. /*
  316. * Query Service Set
  317. * ^^^^^^^^^^^^^^^^^ */
  318. #ifdef UA_ENABLE_QUERY
  319. static UA_INLINE UA_QueryFirstResponse
  320. UA_Client_Service_queryFirst(UA_Client *client,
  321. const UA_QueryFirstRequest request) {
  322. UA_QueryFirstResponse response;
  323. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_QUERYFIRSTREQUEST],
  324. &response, &UA_TYPES[UA_TYPES_QUERYFIRSTRESPONSE]);
  325. return response;
  326. }
  327. static UA_INLINE UA_QueryNextResponse
  328. UA_Client_Service_queryNext(UA_Client *client,
  329. const UA_QueryNextRequest request) {
  330. UA_QueryNextResponse response;
  331. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_QUERYFIRSTREQUEST],
  332. &response, &UA_TYPES[UA_TYPES_QUERYFIRSTRESPONSE]);
  333. return response;
  334. }
  335. #endif
  336. /**
  337. * .. _client-async-services:
  338. *
  339. * Asynchronous Services
  340. * ---------------------
  341. * All OPC UA services are asynchronous in nature. So several service calls can
  342. * be made without waiting for a response first. Responess may come in a
  343. * different ordering. */
  344. /* Use the type versions of this method. See below. However, the general
  345. * mechanism of async service calls is explained here.
  346. *
  347. * We say that an async service call has been dispatched once this method
  348. * returns UA_STATUSCODE_GOOD. If there is an error after an async service has
  349. * been dispatched, the callback is called with an "empty" response where the
  350. * statusCode has been set accordingly. This is also done if the client is
  351. * shutting down and the list of dispatched async services is emptied.
  352. *
  353. * The statusCode received when the client is shutting down is
  354. * UA_STATUSCODE_BADSHUTDOWN.
  355. *
  356. * The statusCode received when the client don't receive response
  357. * after specified config->timeout (in ms) is
  358. * UA_STATUSCODE_BADTIMEOUT.
  359. *
  360. * Instead, you can use __UA_Client_AsyncServiceEx to specify
  361. * a custom timeout
  362. *
  363. * The userdata and requestId arguments can be NULL. */
  364. UA_StatusCode UA_EXPORT
  365. __UA_Client_AsyncService(UA_Client *client, const void *request,
  366. const UA_DataType *requestType,
  367. UA_ClientAsyncServiceCallback callback,
  368. const UA_DataType *responseType,
  369. void *userdata, UA_UInt32 *requestId);
  370. UA_StatusCode UA_EXPORT
  371. UA_Client_sendAsyncRequest(UA_Client *client, const void *request,
  372. const UA_DataType *requestType, UA_ClientAsyncServiceCallback callback,
  373. const UA_DataType *responseType, void *userdata, UA_UInt32 *requestId);
  374. /* Listen on the network and process arriving asynchronous responses in the
  375. * background. Internal housekeeping, renewal of SecureChannels and subscription
  376. * management is done as well. */
  377. UA_StatusCode UA_EXPORT
  378. UA_Client_run_iterate(UA_Client *client, UA_UInt16 timeout);
  379. UA_DEPRECATED static UA_INLINE UA_StatusCode
  380. UA_Client_runAsync(UA_Client *client, UA_UInt16 timeout) {
  381. return UA_Client_run_iterate(client, timeout);
  382. }
  383. UA_DEPRECATED static UA_INLINE UA_StatusCode
  384. UA_Client_manuallyRenewSecureChannel(UA_Client *client) {
  385. return UA_Client_run_iterate(client, 0);
  386. }
  387. /* Use the type versions of this method. See below. However, the general
  388. * mechanism of async service calls is explained here.
  389. *
  390. * We say that an async service call has been dispatched once this method
  391. * returns UA_STATUSCODE_GOOD. If there is an error after an async service has
  392. * been dispatched, the callback is called with an "empty" response where the
  393. * statusCode has been set accordingly. This is also done if the client is
  394. * shutting down and the list of dispatched async services is emptied.
  395. *
  396. * The statusCode received when the client is shutting down is
  397. * UA_STATUSCODE_BADSHUTDOWN.
  398. *
  399. * The statusCode received when the client don't receive response
  400. * after specified timeout (in ms) is
  401. * UA_STATUSCODE_BADTIMEOUT.
  402. *
  403. * The timeout can be disabled by setting timeout to 0
  404. *
  405. * The userdata and requestId arguments can be NULL. */
  406. UA_StatusCode UA_EXPORT
  407. __UA_Client_AsyncServiceEx(UA_Client *client, const void *request,
  408. const UA_DataType *requestType,
  409. UA_ClientAsyncServiceCallback callback,
  410. const UA_DataType *responseType,
  411. void *userdata, UA_UInt32 *requestId,
  412. UA_UInt32 timeout);
  413. /**
  414. * Timed Callbacks
  415. * ---------------
  416. * Repeated callbacks can be attached to a client and will be executed in the
  417. * defined interval. */
  418. typedef void (*UA_ClientCallback)(UA_Client *client, void *data);
  419. /* Add a callback for execution at a specified time. If the indicated time lies
  420. * in the past, then the callback is executed at the next iteration of the
  421. * server's main loop.
  422. *
  423. * @param client The client object.
  424. * @param callback The callback that shall be added.
  425. * @param data Data that is forwarded to the callback.
  426. * @param date The timestamp for the execution time.
  427. * @param callbackId Set to the identifier of the repeated callback . This can
  428. * be used to cancel the callback later on. If the pointer is null, the
  429. * identifier is not set.
  430. * @return Upon success, UA_STATUSCODE_GOOD is returned. An error code
  431. * otherwise. */
  432. UA_StatusCode UA_EXPORT
  433. UA_Client_addTimedCallback(UA_Client *client, UA_ClientCallback callback,
  434. void *data, UA_DateTime date, UA_UInt64 *callbackId);
  435. /* Add a callback for cyclic repetition to the client.
  436. *
  437. * @param client The client object.
  438. * @param callback The callback that shall be added.
  439. * @param data Data that is forwarded to the callback.
  440. * @param interval_ms The callback shall be repeatedly executed with the given
  441. * interval (in ms). The interval must be positive. The first execution
  442. * occurs at now() + interval at the latest.
  443. * @param callbackId Set to the identifier of the repeated callback . This can
  444. * be used to cancel the callback later on. If the pointer is null, the
  445. * identifier is not set.
  446. * @return Upon success, UA_STATUSCODE_GOOD is returned. An error code
  447. * otherwise. */
  448. UA_StatusCode UA_EXPORT
  449. UA_Client_addRepeatedCallback(UA_Client *client, UA_ClientCallback callback,
  450. void *data, UA_Double interval_ms,
  451. UA_UInt64 *callbackId);
  452. UA_StatusCode UA_EXPORT
  453. UA_Client_changeRepeatedCallbackInterval(UA_Client *client,
  454. UA_UInt64 callbackId,
  455. UA_Double interval_ms);
  456. void UA_EXPORT
  457. UA_Client_removeCallback(UA_Client *client, UA_UInt64 callbackId);
  458. #define UA_Client_removeRepeatedCallback(client, callbackId) \
  459. UA_Client_removeCallback(client, callbackId)
  460. /**
  461. * .. toctree::
  462. *
  463. * client_highlevel
  464. * client_subscriptions */
  465. _UA_END_DECLS
  466. #endif /* UA_CLIENT_H_ */