ua_client.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369
  1. /* Copyright (C) 2014-2016 the contributors as stated in the AUTHORS file
  2. *
  3. * This file is part of open62541. open62541 is free software: you can
  4. * redistribute it and/or modify it under the terms of the GNU Lesser General
  5. * Public License, version 3 (as published by the Free Software Foundation) with
  6. * a static linking exception as stated in the LICENSE file provided with
  7. * open62541.
  8. *
  9. * open62541 is distributed in the hope that it will be useful, but WITHOUT ANY
  10. * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  11. * A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
  12. * details. */
  13. #ifndef UA_CLIENT_H_
  14. #define UA_CLIENT_H_
  15. #ifdef __cplusplus
  16. extern "C" {
  17. #endif
  18. #include "ua_config.h"
  19. #include "ua_types.h"
  20. #include "ua_connection.h"
  21. #include "ua_log.h"
  22. #include "ua_types_generated.h"
  23. #include "ua_types_generated_handling.h"
  24. /**
  25. * .. _client:
  26. *
  27. * Client
  28. * ======
  29. *
  30. * The client implementation allows remote access to all OPC UA services. For
  31. * convenience, some functionality has been wrapped in :ref:`high-level
  32. * abstractions <client-highlevel>`.
  33. *
  34. * **However**: At this time, the client does not yet contain its own thread or
  35. * event-driven main-loop. So the client will not perform any actions
  36. * automatically in the background. This is especially relevant for
  37. * subscriptions. The user will have to periodically call
  38. * `UA_Client_Subscriptions_manuallySendPublishRequest`. See also :ref:`here
  39. * <client-subscriptions>`.
  40. *
  41. * Client Configuration
  42. * -------------------- */
  43. typedef UA_Connection
  44. (*UA_ConnectClientConnection)(UA_ConnectionConfig localConf,
  45. const char *endpointUrl, UA_Logger logger);
  46. typedef struct UA_ClientConfig {
  47. UA_UInt32 timeout; /* Sync response timeout */
  48. UA_UInt32 secureChannelLifeTime; /* Lifetime in ms (then the channel needs
  49. to be renewed) */
  50. UA_Logger logger;
  51. UA_ConnectionConfig localConnectionConfig;
  52. UA_ConnectClientConnection connectionFunc;
  53. } UA_ClientConfig;
  54. /**
  55. * Client Lifecycle
  56. * ---------------- */
  57. typedef enum {
  58. UA_CLIENTSTATE_READY, /* The client is not connected but initialized
  59. and ready to use. */
  60. UA_CLIENTSTATE_CONNECTED, /* The client is connected to a server. */
  61. UA_CLIENTSTATE_FAULTED, /* An error has occured that might have
  62. influenced the connection state. A successfull
  63. service call or renewal of the secure channel
  64. will reset the state to CONNECTED. */
  65. UA_CLIENTSTATE_ERRORED /* A non-recoverable error has occured and the
  66. connection is no longer reliable. The client
  67. needs to be disconnected and reinitialized to
  68. recover into a CONNECTED state. */
  69. } UA_ClientState;
  70. struct UA_Client;
  71. typedef struct UA_Client UA_Client;
  72. /* Create a new client
  73. *
  74. * @param config for the new client. You can use UA_ClientConfig_standard
  75. * which has sane defaults
  76. * @param logger function pointer to a logger function. See
  77. * examples/logger_stdout.c for a simple implementation
  78. * @return return the new Client object */
  79. UA_Client UA_EXPORT * UA_Client_new(UA_ClientConfig config);
  80. /* Get the client connection status */
  81. UA_ClientState UA_EXPORT UA_Client_getState(UA_Client *client);
  82. /* Reset a client */
  83. void UA_EXPORT UA_Client_reset(UA_Client *client);
  84. /* Delete a client */
  85. void UA_EXPORT UA_Client_delete(UA_Client *client);
  86. /**
  87. * Manage the Connection
  88. * --------------------- */
  89. /* Gets a list of endpoints of a server
  90. *
  91. * @param client to use
  92. * @param server url to connect (for example "opc.tcp://localhost:16664")
  93. * @param endpointDescriptionsSize size of the array of endpoint descriptions
  94. * @param endpointDescriptions array of endpoint descriptions that is allocated
  95. * by the function (you need to free manually)
  96. * @return Indicates whether the operation succeeded or returns an error code */
  97. UA_StatusCode UA_EXPORT
  98. UA_Client_getEndpoints(UA_Client *client, const char *serverUrl,
  99. size_t* endpointDescriptionsSize,
  100. UA_EndpointDescription** endpointDescriptions);
  101. /* Connect to the selected server
  102. *
  103. * @param client to use
  104. * @param endpointURL to connect (for example "opc.tcp://localhost:16664")
  105. * @return Indicates whether the operation succeeded or returns an error code */
  106. UA_StatusCode UA_EXPORT
  107. UA_Client_connect(UA_Client *client, const char *endpointUrl);
  108. /* Connect to the selected server with the given username and password
  109. *
  110. * @param client to use
  111. * @param endpointURL to connect (for example "opc.tcp://localhost:16664")
  112. * @param username
  113. * @param password
  114. * @return Indicates whether the operation succeeded or returns an error code */
  115. UA_StatusCode UA_EXPORT
  116. UA_Client_connect_username(UA_Client *client, const char *endpointUrl,
  117. const char *username, const char *password);
  118. /* Close a connection to the selected server */
  119. UA_StatusCode UA_EXPORT UA_Client_disconnect(UA_Client *client);
  120. /* Renew the underlying secure channel */
  121. UA_StatusCode UA_EXPORT UA_Client_manuallyRenewSecureChannel(UA_Client *client);
  122. /**
  123. * .. _client-services:
  124. *
  125. * Raw Services
  126. * ------------
  127. * The raw OPC UA services are exposed to the client. But most of them time, it
  128. * is better to use the convenience functions from ``ua_client_highlevel.h``
  129. * that wrap the raw services. */
  130. /* Don't use this function. Use the type versions below instead. */
  131. void UA_EXPORT
  132. __UA_Client_Service(UA_Client *client, const void *request,
  133. const UA_DataType *requestType, void *response,
  134. const UA_DataType *responseType);
  135. /**
  136. * Attribute Service Set
  137. * ^^^^^^^^^^^^^^^^^^^^^ */
  138. static UA_INLINE UA_ReadResponse
  139. UA_Client_Service_read(UA_Client *client, const UA_ReadRequest request) {
  140. UA_ReadResponse response;
  141. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_READREQUEST],
  142. &response, &UA_TYPES[UA_TYPES_READRESPONSE]);
  143. return response;
  144. }
  145. static UA_INLINE UA_WriteResponse
  146. UA_Client_Service_write(UA_Client *client, const UA_WriteRequest request) {
  147. UA_WriteResponse response;
  148. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_WRITEREQUEST],
  149. &response, &UA_TYPES[UA_TYPES_WRITERESPONSE]);
  150. return response;
  151. }
  152. /**
  153. * Method Service Set
  154. * ^^^^^^^^^^^^^^^^^^ */
  155. #ifdef UA_ENABLE_METHODCALLS
  156. static UA_INLINE UA_CallResponse
  157. UA_Client_Service_call(UA_Client *client, const UA_CallRequest request) {
  158. UA_CallResponse response;
  159. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_CALLREQUEST],
  160. &response, &UA_TYPES[UA_TYPES_CALLRESPONSE]);
  161. return response;
  162. }
  163. #endif
  164. /**
  165. * NodeManagement Service Set
  166. * ^^^^^^^^^^^^^^^^^^^^^^^^^^ */
  167. static UA_INLINE UA_AddNodesResponse
  168. UA_Client_Service_addNodes(UA_Client *client, const UA_AddNodesRequest request) {
  169. UA_AddNodesResponse response;
  170. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_ADDNODESREQUEST],
  171. &response, &UA_TYPES[UA_TYPES_ADDNODESRESPONSE]);
  172. return response;
  173. }
  174. static UA_INLINE UA_AddReferencesResponse
  175. UA_Client_Service_addReferences(UA_Client *client,
  176. const UA_AddReferencesRequest request) {
  177. UA_AddReferencesResponse response;
  178. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_ADDNODESREQUEST],
  179. &response, &UA_TYPES[UA_TYPES_ADDNODESRESPONSE]);
  180. return response;
  181. }
  182. static UA_INLINE UA_DeleteNodesResponse
  183. UA_Client_Service_deleteNodes(UA_Client *client,
  184. const UA_DeleteNodesRequest request) {
  185. UA_DeleteNodesResponse response;
  186. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_DELETENODESREQUEST],
  187. &response, &UA_TYPES[UA_TYPES_DELETENODESRESPONSE]);
  188. return response;
  189. }
  190. static UA_INLINE UA_DeleteReferencesResponse
  191. UA_Client_Service_deleteReferences(UA_Client *client,
  192. const UA_DeleteReferencesRequest request) {
  193. UA_DeleteReferencesResponse response;
  194. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_DELETENODESREQUEST],
  195. &response, &UA_TYPES[UA_TYPES_DELETENODESRESPONSE]);
  196. return response;
  197. }
  198. /**
  199. * View Service Set
  200. * ^^^^^^^^^^^^^^^^ */
  201. static UA_INLINE UA_BrowseResponse
  202. UA_Client_Service_browse(UA_Client *client, const UA_BrowseRequest request) {
  203. UA_BrowseResponse response;
  204. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_BROWSEREQUEST],
  205. &response, &UA_TYPES[UA_TYPES_BROWSERESPONSE]);
  206. return response;
  207. }
  208. static UA_INLINE UA_BrowseNextResponse
  209. UA_Client_Service_browseNext(UA_Client *client,
  210. const UA_BrowseNextRequest request) {
  211. UA_BrowseNextResponse response;
  212. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_BROWSENEXTREQUEST],
  213. &response, &UA_TYPES[UA_TYPES_BROWSENEXTRESPONSE]);
  214. return response;
  215. }
  216. static UA_INLINE UA_TranslateBrowsePathsToNodeIdsResponse
  217. UA_Client_Service_translateBrowsePathsToNodeIds(UA_Client *client,
  218. const UA_TranslateBrowsePathsToNodeIdsRequest request) {
  219. UA_TranslateBrowsePathsToNodeIdsResponse response;
  220. __UA_Client_Service(client, &request,
  221. &UA_TYPES[UA_TYPES_TRANSLATEBROWSEPATHSTONODEIDSREQUEST],
  222. &response,
  223. &UA_TYPES[UA_TYPES_TRANSLATEBROWSEPATHSTONODEIDSRESPONSE]);
  224. return response;
  225. }
  226. static UA_INLINE UA_RegisterNodesResponse
  227. UA_Client_Service_registerNodes(UA_Client *client,
  228. const UA_RegisterNodesRequest request) {
  229. UA_RegisterNodesResponse response;
  230. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_REGISTERNODESREQUEST],
  231. &response, &UA_TYPES[UA_TYPES_REGISTERNODESRESPONSE]);
  232. return response;
  233. }
  234. static UA_INLINE UA_UnregisterNodesResponse
  235. UA_Client_Service_unregisterNodes(UA_Client *client,
  236. const UA_UnregisterNodesRequest request) {
  237. UA_UnregisterNodesResponse response;
  238. __UA_Client_Service(client, &request,
  239. &UA_TYPES[UA_TYPES_UNREGISTERNODESREQUEST],
  240. &response, &UA_TYPES[UA_TYPES_UNREGISTERNODESRESPONSE]);
  241. return response;
  242. }
  243. /**
  244. * Query Service Set
  245. * ^^^^^^^^^^^^^^^^^ */
  246. static UA_INLINE UA_QueryFirstResponse
  247. UA_Client_Service_queryFirst(UA_Client *client,
  248. const UA_QueryFirstRequest request) {
  249. UA_QueryFirstResponse response;
  250. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_QUERYFIRSTREQUEST],
  251. &response, &UA_TYPES[UA_TYPES_QUERYFIRSTRESPONSE]);
  252. return response;
  253. }
  254. static UA_INLINE UA_QueryNextResponse
  255. UA_Client_Service_queryNext(UA_Client *client,
  256. const UA_QueryNextRequest request) {
  257. UA_QueryNextResponse response;
  258. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_QUERYFIRSTREQUEST],
  259. &response, &UA_TYPES[UA_TYPES_QUERYFIRSTRESPONSE]);
  260. return response;
  261. }
  262. #ifdef UA_ENABLE_SUBSCRIPTIONS
  263. /**
  264. * MonitoredItem Service Set
  265. * ^^^^^^^^^^^^^^^^^^^^^^^^^ */
  266. static UA_INLINE UA_CreateMonitoredItemsResponse
  267. UA_Client_Service_createMonitoredItems(UA_Client *client,
  268. const UA_CreateMonitoredItemsRequest request) {
  269. UA_CreateMonitoredItemsResponse response;
  270. __UA_Client_Service(client, &request,
  271. &UA_TYPES[UA_TYPES_CREATEMONITOREDITEMSREQUEST], &response,
  272. &UA_TYPES[UA_TYPES_CREATEMONITOREDITEMSRESPONSE]);
  273. return response;
  274. }
  275. static UA_INLINE UA_DeleteMonitoredItemsResponse
  276. UA_Client_Service_deleteMonitoredItems(UA_Client *client,
  277. const UA_DeleteMonitoredItemsRequest request) {
  278. UA_DeleteMonitoredItemsResponse response;
  279. __UA_Client_Service(client, &request,
  280. &UA_TYPES[UA_TYPES_DELETEMONITOREDITEMSREQUEST], &response,
  281. &UA_TYPES[UA_TYPES_DELETEMONITOREDITEMSRESPONSE]);
  282. return response;
  283. }
  284. /**
  285. * Subscription Service Set
  286. * ^^^^^^^^^^^^^^^^^^^^^^^^ */
  287. static UA_INLINE UA_CreateSubscriptionResponse
  288. UA_Client_Service_createSubscription(UA_Client *client,
  289. const UA_CreateSubscriptionRequest request) {
  290. UA_CreateSubscriptionResponse response;
  291. __UA_Client_Service(client, &request,
  292. &UA_TYPES[UA_TYPES_CREATESUBSCRIPTIONREQUEST], &response,
  293. &UA_TYPES[UA_TYPES_CREATESUBSCRIPTIONRESPONSE]);
  294. return response;
  295. }
  296. static UA_INLINE UA_ModifySubscriptionResponse
  297. UA_Client_Service_modifySubscription(UA_Client *client,
  298. const UA_ModifySubscriptionRequest request) {
  299. UA_ModifySubscriptionResponse response;
  300. __UA_Client_Service(client, &request,
  301. &UA_TYPES[UA_TYPES_MODIFYSUBSCRIPTIONREQUEST], &response,
  302. &UA_TYPES[UA_TYPES_MODIFYSUBSCRIPTIONRESPONSE]);
  303. return response;
  304. }
  305. static UA_INLINE UA_DeleteSubscriptionsResponse
  306. UA_Client_Service_deleteSubscriptions(UA_Client *client,
  307. const UA_DeleteSubscriptionsRequest request) {
  308. UA_DeleteSubscriptionsResponse response;
  309. __UA_Client_Service(client, &request,
  310. &UA_TYPES[UA_TYPES_DELETESUBSCRIPTIONSREQUEST], &response,
  311. &UA_TYPES[UA_TYPES_DELETESUBSCRIPTIONSRESPONSE]);
  312. return response;
  313. }
  314. static UA_INLINE UA_PublishResponse
  315. UA_Client_Service_publish(UA_Client *client, const UA_PublishRequest request) {
  316. UA_PublishResponse response;
  317. __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_PUBLISHREQUEST],
  318. &response, &UA_TYPES[UA_TYPES_PUBLISHRESPONSE]);
  319. return response;
  320. }
  321. #endif
  322. /** .. include:: client_highlevel.rst */
  323. #ifdef __cplusplus
  324. } // extern "C"
  325. #endif
  326. #endif /* UA_CLIENT_H_ */