ua_client.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467
  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. #ifdef __cplusplus
  19. extern "C" {
  20. #endif
  21. #include "ua_types.h"
  22. #include "ua_types_generated.h"
  23. #include "ua_types_generated_handling.h"
  24. #include "ua_plugin_securitypolicy.h"
  25. #include "ua_plugin_network.h"
  26. #include "ua_plugin_log.h"
  27. #include "ua_client_config.h"
  28. #include "ua_nodeids.h"
  29. /**
  30. * .. _client:
  31. *
  32. * Client
  33. * ======
  34. *
  35. * The client implementation allows remote access to all OPC UA services. For
  36. * convenience, some functionality has been wrapped in :ref:`high-level
  37. * abstractions <client-highlevel>`.
  38. *
  39. * **However**: At this time, the client does not yet contain its own thread or
  40. * event-driven main-loop. So the client will not perform any actions
  41. * automatically in the background. This is especially relevant for
  42. * subscriptions. The user will have to periodically call
  43. * `UA_Client_Subscriptions_manuallySendPublishRequest`. See also :ref:`here
  44. * <client-subscriptions>`.
  45. *
  46. *
  47. * .. include:: client_config.rst
  48. *
  49. * Client Lifecycle
  50. * ---------------- */
  51. /* Create a new client */
  52. UA_Client UA_EXPORT *
  53. UA_Client_new(UA_ClientConfig config);
  54. /* Creates a new secure client with the required configuration, certificate
  55. * privatekey, trustlist and revocation list.
  56. *
  57. * @param config new secure configuration for client
  58. * @param certificate client certificate
  59. * @param privateKey client's private key
  60. * @param remoteCertificate server certificate form the endpoints
  61. * @param trustList list of trustable certificate
  62. * @param trustListSize count of trustList
  63. * @param revocationList list of revoked digital certificate
  64. * @param revocationListSize count of revocationList
  65. * @param securityPolicyFunction securityPolicy function
  66. * @return Returns a client configuration for secure channel */
  67. UA_Client UA_EXPORT *
  68. UA_Client_secure_new(UA_ClientConfig config, UA_ByteString certificate,
  69. UA_ByteString privateKey, const UA_ByteString *remoteCertificate,
  70. const UA_ByteString *trustList, size_t trustListSize,
  71. const UA_ByteString *revocationList, size_t revocationListSize,
  72. UA_SecurityPolicy_Func securityPolicyFunction);
  73. /* Get the client connection status */
  74. UA_ClientState UA_EXPORT
  75. UA_Client_getState(UA_Client *client);
  76. /* Get the client context */
  77. void UA_EXPORT *
  78. UA_Client_getContext(UA_Client *client);
  79. /* Reset a client */
  80. void UA_EXPORT
  81. UA_Client_reset(UA_Client *client);
  82. /* Delete a client */
  83. void UA_EXPORT
  84. UA_Client_delete(UA_Client *client);
  85. /**
  86. * Connect to a Server
  87. * ------------------- */
  88. /* Connect to the server
  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(UA_Client *client, const char *endpointUrl);
  95. UA_StatusCode UA_EXPORT
  96. UA_Client_connect_async (UA_Client *client, const char *endpointUrl,
  97. UA_ClientAsyncServiceCallback callback,
  98. void *connected);
  99. /* Connect to the server without creating a session
  100. *
  101. * @param client to use
  102. * @param endpointURL to connect (for example "opc.tcp://localhost:4840")
  103. * @return Indicates whether the operation succeeded or returns an error code */
  104. UA_StatusCode UA_EXPORT
  105. UA_Client_connect_noSession(UA_Client *client, const char *endpointUrl);
  106. /* Connect to the selected server with the given username and password
  107. *
  108. * @param client to use
  109. * @param endpointURL to connect (for example "opc.tcp://localhost:4840")
  110. * @param username
  111. * @param password
  112. * @return Indicates whether the operation succeeded or returns an error code */
  113. UA_StatusCode UA_EXPORT
  114. UA_Client_connect_username(UA_Client *client, const char *endpointUrl,
  115. const char *username, const char *password);
  116. /* Disconnect and close a connection to the selected server */
  117. UA_StatusCode UA_EXPORT
  118. UA_Client_disconnect(UA_Client *client);
  119. UA_StatusCode UA_EXPORT
  120. UA_Client_disconnect_async(UA_Client *client, UA_UInt32 *requestId);
  121. /* Close a connection to the selected server */
  122. UA_StatusCode UA_EXPORT
  123. UA_Client_close(UA_Client *client);
  124. /* Renew the underlying secure channel */
  125. UA_StatusCode UA_EXPORT
  126. UA_Client_manuallyRenewSecureChannel(UA_Client *client);
  127. /**
  128. * Discovery
  129. * --------- */
  130. /* Gets a list of endpoints of a server
  131. *
  132. * @param client to use. Must be connected to the same endpoint given in
  133. * serverUrl or otherwise in disconnected state.
  134. * @param serverUrl url to connect (for example "opc.tcp://localhost:4840")
  135. * @param endpointDescriptionsSize size of the array of endpoint descriptions
  136. * @param endpointDescriptions array of endpoint descriptions that is allocated
  137. * by the function (you need to free manually)
  138. * @return Indicates whether the operation succeeded or returns an error code */
  139. UA_StatusCode UA_EXPORT
  140. UA_Client_getEndpoints(UA_Client *client, const char *serverUrl,
  141. size_t* endpointDescriptionsSize,
  142. UA_EndpointDescription** endpointDescriptions);
  143. /* Gets a list of all registered servers at the given server.
  144. *
  145. * You can pass an optional filter for serverUris. If the given server is not registered,
  146. * an empty array will be returned. If the server is registered, only that application
  147. * description will be returned.
  148. *
  149. * Additionally you can optionally indicate which locale you want for the server name
  150. * in the returned application description. The array indicates the order of preference.
  151. * A server may have localized names.
  152. *
  153. * @param client to use. Must be connected to the same endpoint given in
  154. * serverUrl or otherwise in disconnected state.
  155. * @param serverUrl url to connect (for example "opc.tcp://localhost:4840")
  156. * @param serverUrisSize Optional filter for specific server uris
  157. * @param serverUris Optional filter for specific server uris
  158. * @param localeIdsSize Optional indication which locale you prefer
  159. * @param localeIds Optional indication which locale you prefer
  160. * @param registeredServersSize size of returned array, i.e., number of found/registered servers
  161. * @param registeredServers array containing found/registered servers
  162. * @return Indicates whether the operation succeeded or returns an error code */
  163. UA_StatusCode UA_EXPORT
  164. UA_Client_findServers(UA_Client *client, const char *serverUrl,
  165. size_t serverUrisSize, UA_String *serverUris,
  166. size_t localeIdsSize, UA_String *localeIds,
  167. size_t *registeredServersSize,
  168. UA_ApplicationDescription **registeredServers);
  169. #ifdef UA_ENABLE_DISCOVERY
  170. /* Get a list of all known server in the network. Only supported by LDS servers.
  171. *
  172. * @param client to use. Must be connected to the same endpoint given in
  173. * serverUrl or otherwise in disconnected state.
  174. * @param serverUrl url to connect (for example "opc.tcp://localhost:4840")
  175. * @param startingRecordId optional. Only return the records with an ID higher
  176. * or equal the given. Can be used for pagination to only get a subset of
  177. * the full list
  178. * @param maxRecordsToReturn optional. Only return this number of records
  179. * @param serverCapabilityFilterSize optional. Filter the returned list to only
  180. * get servers with given capabilities, e.g. "LDS"
  181. * @param serverCapabilityFilter optional. Filter the returned list to only get
  182. * servers with given capabilities, e.g. "LDS"
  183. * @param serverOnNetworkSize size of returned array, i.e., number of
  184. * known/registered servers
  185. * @param serverOnNetwork array containing known/registered servers
  186. * @return Indicates whether the operation succeeded or returns an error code */
  187. UA_StatusCode UA_EXPORT
  188. UA_Client_findServersOnNetwork(UA_Client *client, const char *serverUrl,
  189. UA_UInt32 startingRecordId, UA_UInt32 maxRecordsToReturn,
  190. size_t serverCapabilityFilterSize, UA_String *serverCapabilityFilter,
  191. size_t *serverOnNetworkSize, UA_ServerOnNetwork **serverOnNetwork);
  192. #endif
  193. /**
  194. * .. _client-services:
  195. *
  196. * Services
  197. * --------
  198. *
  199. * The raw OPC UA services are exposed to the client. But most of them time, it
  200. * is better to use the convenience functions from ``ua_client_highlevel.h``
  201. * that wrap the raw services. */
  202. /* Don't use this function. Use the type versions below instead. */
  203. void UA_EXPORT
  204. __UA_Client_Service(UA_Client *client, const void *request,
  205. const UA_DataType *requestType, void *response,
  206. const UA_DataType *responseType);
  207. /*
  208. * Attribute Service Set
  209. * ^^^^^^^^^^^^^^^^^^^^^ */
  210. static UA_INLINE UA_ReadResponse
  211. UA_Client_Service_read(UA_Client *client, const UA_ReadRequest request) {
  212. UA_ReadResponse response;
  213. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_READREQUEST],
  214. &response, &UA_TYPES[UA_TYPES_READRESPONSE]);
  215. return response;
  216. }
  217. static UA_INLINE UA_WriteResponse
  218. UA_Client_Service_write(UA_Client *client, const UA_WriteRequest request) {
  219. UA_WriteResponse response;
  220. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_WRITEREQUEST],
  221. &response, &UA_TYPES[UA_TYPES_WRITERESPONSE]);
  222. return response;
  223. }
  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. static UA_INLINE UA_QueryFirstResponse
  319. UA_Client_Service_queryFirst(UA_Client *client,
  320. const UA_QueryFirstRequest request) {
  321. UA_QueryFirstResponse response;
  322. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_QUERYFIRSTREQUEST],
  323. &response, &UA_TYPES[UA_TYPES_QUERYFIRSTRESPONSE]);
  324. return response;
  325. }
  326. static UA_INLINE UA_QueryNextResponse
  327. UA_Client_Service_queryNext(UA_Client *client,
  328. const UA_QueryNextRequest request) {
  329. UA_QueryNextResponse response;
  330. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_QUERYFIRSTREQUEST],
  331. &response, &UA_TYPES[UA_TYPES_QUERYFIRSTRESPONSE]);
  332. return response;
  333. }
  334. /**
  335. * .. _client-async-services:
  336. *
  337. * Asynchronous Services
  338. * ---------------------
  339. * All OPC UA services are asynchronous in nature. So several service calls can
  340. * be made without waiting for a response first. Responess may come in a
  341. * different ordering. */
  342. /* Listen on the network and process arriving asynchronous responses in the
  343. * background. Internal housekeeping and subscription management is done as
  344. * well. */
  345. /*UA_StatusCode UA_EXPORT
  346. UA_Client_runAsync(UA_Client *client, UA_UInt16 timeout);*/
  347. /* Use the type versions of this method. See below. However, the general
  348. * mechanism of async service calls is explained here.
  349. *
  350. * We say that an async service call has been dispatched once this method
  351. * returns UA_STATUSCODE_GOOD. If there is an error after an async service has
  352. * been dispatched, the callback is called with an "empty" response where the
  353. * statusCode has been set accordingly. This is also done if the client is
  354. * shutting down and the list of dispatched async services is emptied.
  355. *
  356. * The statusCode received when the client is shutting down is
  357. * UA_STATUSCODE_BADSHUTDOWN.
  358. *
  359. * The statusCode received when the client don't receive response
  360. * after specified config->timeout (in ms) is
  361. * UA_STATUSCODE_BADTIMEOUT.
  362. *
  363. * Instead, you can use __UA_Client_AsyncServiceEx to specify
  364. * a custom timeout
  365. *
  366. * The userdata and requestId arguments can be NULL. */
  367. UA_StatusCode UA_EXPORT
  368. __UA_Client_AsyncService(UA_Client *client, const void *request,
  369. const UA_DataType *requestType,
  370. UA_ClientAsyncServiceCallback callback,
  371. const UA_DataType *responseType,
  372. void *userdata, UA_UInt32 *requestId);
  373. /* For async connecting
  374. * */
  375. UA_StatusCode UA_EXPORT
  376. UA_Client_sendAsyncRequest(UA_Client *client, const void *request,
  377. const UA_DataType *requestType, UA_ClientAsyncServiceCallback callback,
  378. const UA_DataType *responseType, void *userdata, UA_UInt32 *requestId);
  379. UA_StatusCode UA_EXPORT
  380. UA_Client_run_iterate(UA_Client *client, UA_UInt16 timeout);
  381. /* Use the type versions of this method. See below. However, the general
  382. * mechanism of async service calls is explained here.
  383. *
  384. * We say that an async service call has been dispatched once this method
  385. * returns UA_STATUSCODE_GOOD. If there is an error after an async service has
  386. * been dispatched, the callback is called with an "empty" response where the
  387. * statusCode has been set accordingly. This is also done if the client is
  388. * shutting down and the list of dispatched async services is emptied.
  389. *
  390. * The statusCode received when the client is shutting down is
  391. * UA_STATUSCODE_BADSHUTDOWN.
  392. *
  393. * The statusCode received when the client don't receive response
  394. * after specified timeout (in ms) is
  395. * UA_STATUSCODE_BADTIMEOUT.
  396. *
  397. * The timeout can be disabled by setting timeout to 0
  398. *
  399. * The userdata and requestId arguments can be NULL. */
  400. UA_StatusCode UA_EXPORT
  401. __UA_Client_AsyncServiceEx(UA_Client *client, const void *request,
  402. const UA_DataType *requestType,
  403. UA_ClientAsyncServiceCallback callback,
  404. const UA_DataType *responseType,
  405. void *userdata, UA_UInt32 *requestId,
  406. UA_UInt32 timeout);
  407. /**
  408. * .. toctree::
  409. *
  410. * client_highlevel
  411. * client_subscriptions */
  412. #ifdef __cplusplus
  413. } // extern "C"
  414. #endif
  415. #endif /* UA_CLIENT_H_ */