ua_client.h 17 KB

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