ua_client.h 17 KB

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