ua_client.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474
  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. /**
  26. * .. _client:
  27. *
  28. * Client
  29. * ======
  30. *
  31. * The client implementation allows remote access to all OPC UA services. For
  32. * convenience, some functionality has been wrapped in :ref:`high-level
  33. * abstractions <client-highlevel>`.
  34. *
  35. * **However**: At this time, the client does not yet contain its own thread or
  36. * event-driven main-loop. So the client will not perform any actions
  37. * automatically in the background. This is especially relevant for
  38. * subscriptions. The user will have to periodically call
  39. * `UA_Client_Subscriptions_manuallySendPublishRequest`. See also :ref:`here
  40. * <client-subscriptions>`.
  41. *
  42. * Client Lifecycle
  43. * ---------------- */
  44. typedef enum {
  45. UA_CLIENTSTATE_DISCONNECTED, /* The client is disconnected */
  46. UA_CLIENTSTATE_CONNECTED, /* A TCP connection to the server is open */
  47. UA_CLIENTSTATE_SECURECHANNEL, /* A SecureChannel to the server is open */
  48. UA_CLIENTSTATE_SESSION, /* A session with the server is open */
  49. UA_CLIENTSTATE_SESSION_RENEWED /* A session with the server is open (renewed) */
  50. } UA_ClientState;
  51. struct UA_Client;
  52. typedef struct UA_Client UA_Client;
  53. /**
  54. * Client Lifecycle callback
  55. * ------------------------- */
  56. typedef void (*UA_ClientStateCallback)(UA_Client *client, UA_ClientState clientState);
  57. /**
  58. * Subscription Inactivity callback
  59. * ------------------------- */
  60. #ifdef UA_ENABLE_SUBSCRIPTIONS
  61. typedef void (*UA_SubscriptionInactivityCallback)(UA_Client *client, UA_UInt32 subscriptionId, void *subContext);
  62. #endif
  63. /**
  64. * Client Configuration
  65. * -------------------- */
  66. typedef struct UA_ClientConfig {
  67. UA_UInt32 timeout; /* Sync response timeout in ms */
  68. UA_UInt32 secureChannelLifeTime; /* Lifetime in ms (then the channel needs
  69. to be renewed) */
  70. UA_Logger logger;
  71. UA_ConnectionConfig localConnectionConfig;
  72. UA_ConnectClientConnection connectionFunc;
  73. /* Custom DataTypes */
  74. size_t customDataTypesSize;
  75. const UA_DataType *customDataTypes;
  76. /* Callback function */
  77. UA_ClientStateCallback stateCallback;
  78. #ifdef UA_ENABLE_SUBSCRIPTIONS
  79. UA_SubscriptionInactivityCallback subscriptionInactivityCallback;
  80. #endif
  81. void *clientContext;
  82. /* number of PublishResponse standing in the sever */
  83. /* 0 = background task disabled */
  84. UA_UInt16 outStandingPublishRequests;
  85. } UA_ClientConfig;
  86. /* Create a new client */
  87. UA_Client UA_EXPORT *
  88. UA_Client_new(UA_ClientConfig config);
  89. /* Get the client connection status */
  90. UA_ClientState UA_EXPORT
  91. UA_Client_getState(UA_Client *client);
  92. /* Get the client context */
  93. void UA_EXPORT *
  94. UA_Client_getContext(UA_Client *client);
  95. /* Reset a client */
  96. void UA_EXPORT
  97. UA_Client_reset(UA_Client *client);
  98. /* Delete a client */
  99. void UA_EXPORT
  100. UA_Client_delete(UA_Client *client);
  101. /**
  102. * Connect to a Server
  103. * ------------------- */
  104. /* Connect to the server
  105. *
  106. * @param client to use
  107. * @param endpointURL to connect (for example "opc.tcp://localhost:16664")
  108. * @return Indicates whether the operation succeeded or returns an error code */
  109. UA_StatusCode UA_EXPORT
  110. UA_Client_connect(UA_Client *client, const char *endpointUrl);
  111. /* Connect to the selected server with the given username and password
  112. *
  113. * @param client to use
  114. * @param endpointURL to connect (for example "opc.tcp://localhost:16664")
  115. * @param username
  116. * @param password
  117. * @return Indicates whether the operation succeeded or returns an error code */
  118. UA_StatusCode UA_EXPORT
  119. UA_Client_connect_username(UA_Client *client, const char *endpointUrl,
  120. const char *username, const char *password);
  121. /* Disconnect and close a connection to the selected server */
  122. UA_StatusCode UA_EXPORT
  123. UA_Client_disconnect(UA_Client *client);
  124. /* Close a connection to the selected server */
  125. UA_StatusCode UA_EXPORT
  126. UA_Client_close(UA_Client *client);
  127. /* Renew the underlying secure channel */
  128. UA_StatusCode UA_EXPORT
  129. UA_Client_manuallyRenewSecureChannel(UA_Client *client);
  130. /**
  131. * Discovery
  132. * --------- */
  133. /* Gets a list of endpoints of a server
  134. *
  135. * @param client to use. Must be connected to the same endpoint given in
  136. * serverUrl or otherwise in disconnected state.
  137. * @param serverUrl url to connect (for example "opc.tcp://localhost:16664")
  138. * @param endpointDescriptionsSize size of the array of endpoint descriptions
  139. * @param endpointDescriptions array of endpoint descriptions that is allocated
  140. * by the function (you need to free manually)
  141. * @return Indicates whether the operation succeeded or returns an error code */
  142. UA_StatusCode UA_EXPORT
  143. UA_Client_getEndpoints(UA_Client *client, const char *serverUrl,
  144. size_t* endpointDescriptionsSize,
  145. UA_EndpointDescription** endpointDescriptions);
  146. /* Gets a list of all registered servers at the given server.
  147. *
  148. * You can pass an optional filter for serverUris. If the given server is not registered,
  149. * an empty array will be returned. If the server is registered, only that application
  150. * description will be returned.
  151. *
  152. * Additionally you can optionally indicate which locale you want for the server name
  153. * in the returned application description. The array indicates the order of preference.
  154. * A server may have localized names.
  155. *
  156. * @param client to use. Must be connected to the same endpoint given in
  157. * serverUrl or otherwise in disconnected state.
  158. * @param serverUrl url to connect (for example "opc.tcp://localhost:16664")
  159. * @param serverUrisSize Optional filter for specific server uris
  160. * @param serverUris Optional filter for specific server uris
  161. * @param localeIdsSize Optional indication which locale you prefer
  162. * @param localeIds Optional indication which locale you prefer
  163. * @param registeredServersSize size of returned array, i.e., number of found/registered servers
  164. * @param registeredServers array containing found/registered servers
  165. * @return Indicates whether the operation succeeded or returns an error code */
  166. UA_StatusCode UA_EXPORT
  167. UA_Client_findServers(UA_Client *client, const char *serverUrl,
  168. size_t serverUrisSize, UA_String *serverUris,
  169. size_t localeIdsSize, UA_String *localeIds,
  170. size_t *registeredServersSize,
  171. UA_ApplicationDescription **registeredServers);
  172. /* Get a list of all known server in the network. Only supported by LDS servers.
  173. *
  174. * @param client to use. Must be connected to the same endpoint given in
  175. * serverUrl or otherwise in disconnected state.
  176. * @param serverUrl url to connect (for example "opc.tcp://localhost:16664")
  177. * @param startingRecordId optional. Only return the records with an ID higher
  178. * or equal the given. Can be used for pagination to only get a subset of
  179. * the full list
  180. * @param maxRecordsToReturn optional. Only return this number of records
  181. * @param serverCapabilityFilterSize optional. Filter the returned list to only
  182. * get servers with given capabilities, e.g. "LDS"
  183. * @param serverCapabilityFilter optional. Filter the returned list to only get
  184. * servers with given capabilities, e.g. "LDS"
  185. * @param serverOnNetworkSize size of returned array, i.e., number of
  186. * known/registered servers
  187. * @param serverOnNetwork array containing known/registered servers
  188. * @return Indicates whether the operation succeeded or returns an error code */
  189. UA_StatusCode UA_EXPORT
  190. UA_Client_findServersOnNetwork(UA_Client *client, const char *serverUrl,
  191. UA_UInt32 startingRecordId, UA_UInt32 maxRecordsToReturn,
  192. size_t serverCapabilityFilterSize, UA_String *serverCapabilityFilter,
  193. size_t *serverOnNetworkSize, UA_ServerOnNetwork **serverOnNetwork);
  194. /**
  195. * .. _client-services:
  196. *
  197. * Services
  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. typedef void
  348. (*UA_ClientAsyncServiceCallback)(UA_Client *client, void *userdata,
  349. UA_UInt32 requestId, void *response,
  350. const UA_DataType *responseType);
  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 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. static UA_INLINE UA_StatusCode
  371. UA_Client_AsyncService_read(UA_Client *client, const UA_ReadRequest *request,
  372. UA_ClientAsyncServiceCallback callback,
  373. void *userdata, UA_UInt32 *requestId) {
  374. return __UA_Client_AsyncService(client, (const void*)request,
  375. &UA_TYPES[UA_TYPES_READREQUEST], callback,
  376. &UA_TYPES[UA_TYPES_READRESPONSE],
  377. userdata, requestId);
  378. }
  379. static UA_INLINE UA_StatusCode
  380. UA_Client_AsyncService_write(UA_Client *client, const UA_WriteRequest *request,
  381. UA_ClientAsyncServiceCallback callback,
  382. void *userdata, UA_UInt32 *requestId) {
  383. return __UA_Client_AsyncService(client, (const void*)request,
  384. &UA_TYPES[UA_TYPES_WRITEREQUEST], callback,
  385. &UA_TYPES[UA_TYPES_WRITERESPONSE],
  386. userdata, requestId);
  387. }
  388. static UA_INLINE UA_StatusCode
  389. UA_Client_AsyncService_call(UA_Client *client, const UA_CallRequest *request,
  390. UA_ClientAsyncServiceCallback callback,
  391. void *userdata, UA_UInt32 *requestId) {
  392. return __UA_Client_AsyncService(client, (const void*)request,
  393. &UA_TYPES[UA_TYPES_CALLREQUEST], callback,
  394. &UA_TYPES[UA_TYPES_CALLRESPONSE],
  395. userdata, requestId);
  396. }
  397. static UA_INLINE UA_StatusCode
  398. UA_Client_AsyncService_browse(UA_Client *client, const UA_BrowseRequest *request,
  399. UA_ClientAsyncServiceCallback callback,
  400. void *userdata, UA_UInt32 *requestId) {
  401. return __UA_Client_AsyncService(client, (const void*)request,
  402. &UA_TYPES[UA_TYPES_BROWSEREQUEST], callback,
  403. &UA_TYPES[UA_TYPES_BROWSERESPONSE],
  404. userdata, requestId);
  405. }
  406. /**
  407. * .. toctree::
  408. *
  409. * client_highlevel
  410. * client_subscriptions */
  411. #ifdef __cplusplus
  412. } // extern "C"
  413. #endif
  414. #endif /* UA_CLIENT_H_ */