ua_client.h 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501
  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(UA_ClientConfig config);
  52. /* Creates a new secure client with the required configuration, certificate
  53. * privatekey, trustlist and revocation list.
  54. *
  55. * @param config new secure configuration for client
  56. * @param certificate client certificate
  57. * @param privateKey client's private key
  58. * @param remoteCertificate server certificate form the endpoints
  59. * @param trustList list of trustable certificate
  60. * @param trustListSize count of trustList
  61. * @param revocationList list of revoked digital certificate
  62. * @param revocationListSize count of revocationList
  63. * @param securityPolicyFunction securityPolicy function
  64. * @return Returns a client configuration for secure channel */
  65. UA_Client UA_EXPORT *
  66. UA_Client_secure_new(UA_ClientConfig config, UA_ByteString certificate,
  67. UA_ByteString privateKey, const UA_ByteString *remoteCertificate,
  68. const UA_ByteString *trustList, size_t trustListSize,
  69. const UA_ByteString *revocationList, size_t revocationListSize,
  70. UA_SecurityPolicy_Func securityPolicyFunction);
  71. /* Get the client connection status */
  72. UA_ClientState UA_EXPORT
  73. UA_Client_getState(UA_Client *client);
  74. /* Get the client configuration */
  75. UA_EXPORT UA_ClientConfig *
  76. UA_Client_getConfig(UA_Client *client);
  77. /* Get the client context */
  78. static UA_INLINE void *
  79. UA_Client_getContext(UA_Client *client) {
  80. UA_ClientConfig *config = UA_Client_getConfig(client);
  81. if(!config)
  82. return NULL;
  83. return config->clientContext;
  84. }
  85. /* Reset a client */
  86. void UA_EXPORT
  87. UA_Client_reset(UA_Client *client);
  88. /* Delete a client */
  89. void UA_EXPORT
  90. UA_Client_delete(UA_Client *client);
  91. /**
  92. * Connect to a Server
  93. * ------------------- */
  94. typedef void (*UA_ClientAsyncServiceCallback)(UA_Client *client, void *userdata,
  95. UA_UInt32 requestId, void *response);
  96. /* Connect to the server
  97. *
  98. * @param client to use
  99. * @param endpointURL to connect (for example "opc.tcp://localhost:4840")
  100. * @return Indicates whether the operation succeeded or returns an error code */
  101. UA_StatusCode UA_EXPORT
  102. UA_Client_connect(UA_Client *client, const char *endpointUrl);
  103. UA_StatusCode UA_EXPORT
  104. UA_Client_connect_async (UA_Client *client, const char *endpointUrl,
  105. UA_ClientAsyncServiceCallback callback,
  106. void *connected);
  107. /* Connect to the server without creating a session
  108. *
  109. * @param client to use
  110. * @param endpointURL to connect (for example "opc.tcp://localhost:4840")
  111. * @return Indicates whether the operation succeeded or returns an error code */
  112. UA_StatusCode UA_EXPORT
  113. UA_Client_connect_noSession(UA_Client *client, const char *endpointUrl);
  114. /* Connect to the selected server with the given username and password
  115. *
  116. * @param client to use
  117. * @param endpointURL to connect (for example "opc.tcp://localhost:4840")
  118. * @param username
  119. * @param password
  120. * @return Indicates whether the operation succeeded or returns an error code */
  121. UA_StatusCode UA_EXPORT
  122. UA_Client_connect_username(UA_Client *client, const char *endpointUrl,
  123. const char *username, const char *password);
  124. /* Disconnect and close a connection to the selected server */
  125. UA_StatusCode UA_EXPORT
  126. UA_Client_disconnect(UA_Client *client);
  127. UA_StatusCode UA_EXPORT
  128. UA_Client_disconnect_async(UA_Client *client, UA_UInt32 *requestId);
  129. /* Close a connection to the selected server */
  130. UA_DEPRECATED static UA_INLINE UA_StatusCode
  131. UA_Client_close(UA_Client *client) {
  132. return UA_Client_disconnect(client);
  133. }
  134. /**
  135. * Discovery
  136. * --------- */
  137. /* Gets a list of endpoints of a server
  138. *
  139. * @param client to use. Must be connected to the same endpoint given in
  140. * serverUrl or otherwise in disconnected state.
  141. * @param serverUrl url to connect (for example "opc.tcp://localhost:4840")
  142. * @param endpointDescriptionsSize size of the array of endpoint descriptions
  143. * @param endpointDescriptions array of endpoint descriptions that is allocated
  144. * by the function (you need to free manually)
  145. * @return Indicates whether the operation succeeded or returns an error code */
  146. UA_StatusCode UA_EXPORT
  147. UA_Client_getEndpoints(UA_Client *client, const char *serverUrl,
  148. size_t* endpointDescriptionsSize,
  149. UA_EndpointDescription** endpointDescriptions);
  150. /* Gets a list of all registered servers at the given server.
  151. *
  152. * You can pass an optional filter for serverUris. If the given server is not registered,
  153. * an empty array will be returned. If the server is registered, only that application
  154. * description will be returned.
  155. *
  156. * Additionally you can optionally indicate which locale you want for the server name
  157. * in the returned application description. The array indicates the order of preference.
  158. * A server may have localized names.
  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 serverUrisSize Optional filter for specific server uris
  164. * @param serverUris Optional filter for specific server uris
  165. * @param localeIdsSize Optional indication which locale you prefer
  166. * @param localeIds Optional indication which locale you prefer
  167. * @param registeredServersSize size of returned array, i.e., number of found/registered servers
  168. * @param registeredServers array containing found/registered servers
  169. * @return Indicates whether the operation succeeded or returns an error code */
  170. UA_StatusCode UA_EXPORT
  171. UA_Client_findServers(UA_Client *client, const char *serverUrl,
  172. size_t serverUrisSize, UA_String *serverUris,
  173. size_t localeIdsSize, UA_String *localeIds,
  174. size_t *registeredServersSize,
  175. UA_ApplicationDescription **registeredServers);
  176. #ifdef UA_ENABLE_DISCOVERY
  177. /* Get a list of all known server in the network. Only supported by LDS servers.
  178. *
  179. * @param client to use. Must be connected to the same endpoint given in
  180. * serverUrl or otherwise in disconnected state.
  181. * @param serverUrl url to connect (for example "opc.tcp://localhost:4840")
  182. * @param startingRecordId optional. Only return the records with an ID higher
  183. * or equal the given. Can be used for pagination to only get a subset of
  184. * the full list
  185. * @param maxRecordsToReturn optional. Only return this number of records
  186. * @param serverCapabilityFilterSize optional. Filter the returned list to only
  187. * get servers with given capabilities, e.g. "LDS"
  188. * @param serverCapabilityFilter optional. Filter the returned list to only get
  189. * servers with given capabilities, e.g. "LDS"
  190. * @param serverOnNetworkSize size of returned array, i.e., number of
  191. * known/registered servers
  192. * @param serverOnNetwork array containing known/registered servers
  193. * @return Indicates whether the operation succeeded or returns an error code */
  194. UA_StatusCode UA_EXPORT
  195. UA_Client_findServersOnNetwork(UA_Client *client, const char *serverUrl,
  196. UA_UInt32 startingRecordId, UA_UInt32 maxRecordsToReturn,
  197. size_t serverCapabilityFilterSize, UA_String *serverCapabilityFilter,
  198. size_t *serverOnNetworkSize, UA_ServerOnNetwork **serverOnNetwork);
  199. #endif
  200. /**
  201. * .. _client-services:
  202. *
  203. * Services
  204. * --------
  205. *
  206. * The raw OPC UA services are exposed to the client. But most of them time, it
  207. * is better to use the convenience functions from ``ua_client_highlevel.h``
  208. * that wrap the raw services. */
  209. /* Don't use this function. Use the type versions below instead. */
  210. void UA_EXPORT
  211. __UA_Client_Service(UA_Client *client, const void *request,
  212. const UA_DataType *requestType, void *response,
  213. const UA_DataType *responseType);
  214. /*
  215. * Attribute Service Set
  216. * ^^^^^^^^^^^^^^^^^^^^^ */
  217. static UA_INLINE UA_ReadResponse
  218. UA_Client_Service_read(UA_Client *client, const UA_ReadRequest request) {
  219. UA_ReadResponse response;
  220. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_READREQUEST],
  221. &response, &UA_TYPES[UA_TYPES_READRESPONSE]);
  222. return response;
  223. }
  224. static UA_INLINE UA_WriteResponse
  225. UA_Client_Service_write(UA_Client *client, const UA_WriteRequest request) {
  226. UA_WriteResponse response;
  227. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_WRITEREQUEST],
  228. &response, &UA_TYPES[UA_TYPES_WRITERESPONSE]);
  229. return response;
  230. }
  231. /*
  232. * Method Service Set
  233. * ^^^^^^^^^^^^^^^^^^ */
  234. #ifdef UA_ENABLE_METHODCALLS
  235. static UA_INLINE UA_CallResponse
  236. UA_Client_Service_call(UA_Client *client, const UA_CallRequest request) {
  237. UA_CallResponse response;
  238. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_CALLREQUEST],
  239. &response, &UA_TYPES[UA_TYPES_CALLRESPONSE]);
  240. return response;
  241. }
  242. #endif
  243. /*
  244. * NodeManagement Service Set
  245. * ^^^^^^^^^^^^^^^^^^^^^^^^^^ */
  246. static UA_INLINE UA_AddNodesResponse
  247. UA_Client_Service_addNodes(UA_Client *client, const UA_AddNodesRequest request) {
  248. UA_AddNodesResponse response;
  249. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_ADDNODESREQUEST],
  250. &response, &UA_TYPES[UA_TYPES_ADDNODESRESPONSE]);
  251. return response;
  252. }
  253. static UA_INLINE UA_AddReferencesResponse
  254. UA_Client_Service_addReferences(UA_Client *client,
  255. const UA_AddReferencesRequest request) {
  256. UA_AddReferencesResponse response;
  257. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_ADDREFERENCESREQUEST],
  258. &response, &UA_TYPES[UA_TYPES_ADDREFERENCESRESPONSE]);
  259. return response;
  260. }
  261. static UA_INLINE UA_DeleteNodesResponse
  262. UA_Client_Service_deleteNodes(UA_Client *client,
  263. const UA_DeleteNodesRequest request) {
  264. UA_DeleteNodesResponse response;
  265. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_DELETENODESREQUEST],
  266. &response, &UA_TYPES[UA_TYPES_DELETENODESRESPONSE]);
  267. return response;
  268. }
  269. static UA_INLINE UA_DeleteReferencesResponse
  270. UA_Client_Service_deleteReferences(UA_Client *client,
  271. const UA_DeleteReferencesRequest request) {
  272. UA_DeleteReferencesResponse response;
  273. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_DELETEREFERENCESREQUEST],
  274. &response, &UA_TYPES[UA_TYPES_DELETEREFERENCESRESPONSE]);
  275. return response;
  276. }
  277. /*
  278. * View Service Set
  279. * ^^^^^^^^^^^^^^^^ */
  280. static UA_INLINE UA_BrowseResponse
  281. UA_Client_Service_browse(UA_Client *client, const UA_BrowseRequest request) {
  282. UA_BrowseResponse response;
  283. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_BROWSEREQUEST],
  284. &response, &UA_TYPES[UA_TYPES_BROWSERESPONSE]);
  285. return response;
  286. }
  287. static UA_INLINE UA_BrowseNextResponse
  288. UA_Client_Service_browseNext(UA_Client *client,
  289. const UA_BrowseNextRequest request) {
  290. UA_BrowseNextResponse response;
  291. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_BROWSENEXTREQUEST],
  292. &response, &UA_TYPES[UA_TYPES_BROWSENEXTRESPONSE]);
  293. return response;
  294. }
  295. static UA_INLINE UA_TranslateBrowsePathsToNodeIdsResponse
  296. UA_Client_Service_translateBrowsePathsToNodeIds(UA_Client *client,
  297. const UA_TranslateBrowsePathsToNodeIdsRequest request) {
  298. UA_TranslateBrowsePathsToNodeIdsResponse response;
  299. __UA_Client_Service(client, &request,
  300. &UA_TYPES[UA_TYPES_TRANSLATEBROWSEPATHSTONODEIDSREQUEST],
  301. &response,
  302. &UA_TYPES[UA_TYPES_TRANSLATEBROWSEPATHSTONODEIDSRESPONSE]);
  303. return response;
  304. }
  305. static UA_INLINE UA_RegisterNodesResponse
  306. UA_Client_Service_registerNodes(UA_Client *client,
  307. const UA_RegisterNodesRequest request) {
  308. UA_RegisterNodesResponse response;
  309. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_REGISTERNODESREQUEST],
  310. &response, &UA_TYPES[UA_TYPES_REGISTERNODESRESPONSE]);
  311. return response;
  312. }
  313. static UA_INLINE UA_UnregisterNodesResponse
  314. UA_Client_Service_unregisterNodes(UA_Client *client,
  315. const UA_UnregisterNodesRequest request) {
  316. UA_UnregisterNodesResponse response;
  317. __UA_Client_Service(client, &request,
  318. &UA_TYPES[UA_TYPES_UNREGISTERNODESREQUEST],
  319. &response, &UA_TYPES[UA_TYPES_UNREGISTERNODESRESPONSE]);
  320. return response;
  321. }
  322. /*
  323. * Query Service Set
  324. * ^^^^^^^^^^^^^^^^^ */
  325. #ifdef UA_ENABLE_QUERY
  326. static UA_INLINE UA_QueryFirstResponse
  327. UA_Client_Service_queryFirst(UA_Client *client,
  328. const UA_QueryFirstRequest request) {
  329. UA_QueryFirstResponse response;
  330. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_QUERYFIRSTREQUEST],
  331. &response, &UA_TYPES[UA_TYPES_QUERYFIRSTRESPONSE]);
  332. return response;
  333. }
  334. static UA_INLINE UA_QueryNextResponse
  335. UA_Client_Service_queryNext(UA_Client *client,
  336. const UA_QueryNextRequest request) {
  337. UA_QueryNextResponse response;
  338. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_QUERYFIRSTREQUEST],
  339. &response, &UA_TYPES[UA_TYPES_QUERYFIRSTRESPONSE]);
  340. return response;
  341. }
  342. #endif
  343. /**
  344. * .. _client-async-services:
  345. *
  346. * Asynchronous Services
  347. * ---------------------
  348. * All OPC UA services are asynchronous in nature. So several service calls can
  349. * be made without waiting for a response first. Responess may come in a
  350. * different ordering. */
  351. /* Use the type versions of this method. See below. However, the general
  352. * mechanism of async service calls is explained here.
  353. *
  354. * We say that an async service call has been dispatched once this method
  355. * returns UA_STATUSCODE_GOOD. If there is an error after an async service has
  356. * been dispatched, the callback is called with an "empty" response where the
  357. * statusCode has been set accordingly. This is also done if the client is
  358. * shutting down and the list of dispatched async services is emptied.
  359. *
  360. * The statusCode received when the client is shutting down is
  361. * UA_STATUSCODE_BADSHUTDOWN.
  362. *
  363. * The statusCode received when the client don't receive response
  364. * after specified config->timeout (in ms) is
  365. * UA_STATUSCODE_BADTIMEOUT.
  366. *
  367. * Instead, you can use __UA_Client_AsyncServiceEx to specify
  368. * a custom timeout
  369. *
  370. * The userdata and requestId arguments can be NULL. */
  371. UA_StatusCode UA_EXPORT
  372. __UA_Client_AsyncService(UA_Client *client, const void *request,
  373. const UA_DataType *requestType,
  374. UA_ClientAsyncServiceCallback callback,
  375. const UA_DataType *responseType,
  376. void *userdata, UA_UInt32 *requestId);
  377. UA_StatusCode UA_EXPORT
  378. UA_Client_sendAsyncRequest(UA_Client *client, const void *request,
  379. const UA_DataType *requestType, UA_ClientAsyncServiceCallback callback,
  380. const UA_DataType *responseType, void *userdata, UA_UInt32 *requestId);
  381. /* Listen on the network and process arriving asynchronous responses in the
  382. * background. Internal housekeeping, renewal of SecureChannels and subscription
  383. * management is done as well. */
  384. UA_StatusCode UA_EXPORT
  385. UA_Client_run_iterate(UA_Client *client, UA_UInt16 timeout);
  386. UA_DEPRECATED static UA_INLINE UA_StatusCode
  387. UA_Client_runAsync(UA_Client *client, UA_UInt16 timeout) {
  388. return UA_Client_run_iterate(client, timeout);
  389. }
  390. UA_DEPRECATED static UA_INLINE UA_StatusCode
  391. UA_Client_manuallyRenewSecureChannel(UA_Client *client) {
  392. return UA_Client_run_iterate(client, 0);
  393. }
  394. /* Use the type versions of this method. See below. However, the general
  395. * mechanism of async service calls is explained here.
  396. *
  397. * We say that an async service call has been dispatched once this method
  398. * returns UA_STATUSCODE_GOOD. If there is an error after an async service has
  399. * been dispatched, the callback is called with an "empty" response where the
  400. * statusCode has been set accordingly. This is also done if the client is
  401. * shutting down and the list of dispatched async services is emptied.
  402. *
  403. * The statusCode received when the client is shutting down is
  404. * UA_STATUSCODE_BADSHUTDOWN.
  405. *
  406. * The statusCode received when the client don't receive response
  407. * after specified timeout (in ms) is
  408. * UA_STATUSCODE_BADTIMEOUT.
  409. *
  410. * The timeout can be disabled by setting timeout to 0
  411. *
  412. * The userdata and requestId arguments can be NULL. */
  413. UA_StatusCode UA_EXPORT
  414. __UA_Client_AsyncServiceEx(UA_Client *client, const void *request,
  415. const UA_DataType *requestType,
  416. UA_ClientAsyncServiceCallback callback,
  417. const UA_DataType *responseType,
  418. void *userdata, UA_UInt32 *requestId,
  419. UA_UInt32 timeout);
  420. /**
  421. * Repeated Callbacks
  422. * ------------------
  423. * Repeated callbacks can be attached to a client and will be executed in the
  424. * defined interval. */
  425. typedef void (*UA_ClientCallback)(UA_Client *client, void *data);
  426. UA_StatusCode
  427. UA_Client_addRepeatedCallback(UA_Client *client,
  428. UA_ClientCallback callback,
  429. void *data, UA_UInt32 interval,
  430. UA_UInt64 *callbackId);
  431. UA_StatusCode
  432. UA_Client_changeRepeatedCallbackInterval(UA_Client *client,
  433. UA_UInt64 callbackId,
  434. UA_UInt32 interval);
  435. UA_StatusCode UA_Client_removeRepeatedCallback(UA_Client *client,
  436. UA_UInt64 callbackId);
  437. /**
  438. * .. toctree::
  439. *
  440. * client_highlevel
  441. * client_subscriptions */
  442. _UA_END_DECLS
  443. #endif /* UA_CLIENT_H_ */