ua_plugin_network.h 8.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207
  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 2017 (c) Fraunhofer IOSB (Author: Julius Pfrommer)
  6. * Copyright 2017 (c) Stefan Profanter, fortiss GmbH
  7. */
  8. #ifndef UA_PLUGIN_NETWORK_H_
  9. #define UA_PLUGIN_NETWORK_H_
  10. #include "ua_server.h"
  11. #include "ua_plugin_log.h"
  12. _UA_BEGIN_DECLS
  13. /* Forward declarations */
  14. struct UA_Connection;
  15. typedef struct UA_Connection UA_Connection;
  16. struct UA_SecureChannel;
  17. typedef struct UA_SecureChannel UA_SecureChannel;
  18. struct UA_ServerNetworkLayer;
  19. typedef struct UA_ServerNetworkLayer UA_ServerNetworkLayer;
  20. /**
  21. * .. _networking:
  22. *
  23. * Networking Plugin API
  24. * =====================
  25. *
  26. * Connection
  27. * ----------
  28. * Client-server connections are represented by a `UA_Connection`. The
  29. * connection is stateful and stores partially received messages, and so on. In
  30. * addition, the connection contains function pointers to the underlying
  31. * networking implementation. An example for this is the `send` function. So the
  32. * connection encapsulates all the required networking functionality. This lets
  33. * users on embedded (or otherwise exotic) systems implement their own
  34. * networking plugins with a clear interface to the main open62541 library. */
  35. typedef struct {
  36. UA_UInt32 protocolVersion;
  37. UA_UInt32 recvBufferSize;
  38. UA_UInt32 sendBufferSize;
  39. UA_UInt32 maxMessageSize; /* Indicated by the remote side (0 = unbounded) */
  40. UA_UInt32 maxChunkCount; /* Indicated by the remote side (0 = unbounded) */
  41. } UA_ConnectionConfig;
  42. typedef enum {
  43. UA_CONNECTION_CLOSED, /* The socket has been closed and the connection
  44. * will be deleted */
  45. UA_CONNECTION_OPENING, /* The socket is open, but the HEL/ACK handshake
  46. * is not done */
  47. UA_CONNECTION_ESTABLISHED /* The socket is open and the connection
  48. * configured */
  49. } UA_ConnectionState;
  50. struct UA_Connection {
  51. UA_ConnectionState state;
  52. UA_ConnectionConfig config;
  53. UA_SecureChannel *channel; /* The securechannel that is attached to
  54. * this connection */
  55. UA_SOCKET sockfd; /* Most connectivity solutions run on
  56. * sockets. Having the socket id here
  57. * simplifies the design. */
  58. UA_DateTime openingDate; /* The date the connection was created */
  59. void *handle; /* A pointer to internal data */
  60. UA_ByteString incompleteChunk; /* A half-received chunk (TCP is a
  61. * streaming protocol) is stored here */
  62. UA_UInt64 connectCallbackID; /* Callback Id, for the connect-loop */
  63. /* Get a buffer for sending */
  64. UA_StatusCode (*getSendBuffer)(UA_Connection *connection, size_t length,
  65. UA_ByteString *buf);
  66. /* Release the send buffer manually */
  67. void (*releaseSendBuffer)(UA_Connection *connection, UA_ByteString *buf);
  68. /* Sends a message over the connection. The message buffer is always freed,
  69. * even if sending fails.
  70. *
  71. * @param connection The connection
  72. * @param buf The message buffer
  73. * @return Returns an error code or UA_STATUSCODE_GOOD. */
  74. UA_StatusCode (*send)(UA_Connection *connection, UA_ByteString *buf);
  75. /* Receive a message from the remote connection
  76. *
  77. * @param connection The connection
  78. * @param response The response string. It is allocated by the connection
  79. * and needs to be freed with connection->releaseBuffer
  80. * @param timeout Timeout of the recv operation in milliseconds
  81. * @return Returns UA_STATUSCODE_BADCOMMUNICATIONERROR if the recv operation
  82. * can be repeated, UA_STATUSCODE_GOOD if it succeeded and
  83. * UA_STATUSCODE_BADCONNECTIONCLOSED if the connection was
  84. * closed. */
  85. UA_StatusCode (*recv)(UA_Connection *connection, UA_ByteString *response,
  86. UA_UInt32 timeout);
  87. /* Release the buffer of a received message */
  88. void (*releaseRecvBuffer)(UA_Connection *connection, UA_ByteString *buf);
  89. /* Close the connection. The network layer closes the socket. This is picked
  90. * up during the next 'listen' and the connection is freed in the network
  91. * layer. */
  92. void (*close)(UA_Connection *connection);
  93. /* To be called only from within the server (and not the network layer).
  94. * Frees up the connection's memory. */
  95. void (*free)(UA_Connection *connection);
  96. };
  97. /* Cleans up half-received messages, and so on. Called from connection->free. */
  98. void UA_EXPORT
  99. UA_Connection_deleteMembers(UA_Connection *connection);
  100. /**
  101. * Server Network Layer
  102. * --------------------
  103. * The server exposes two functions to interact with remote clients:
  104. * `processBinaryMessage` and `removeConnection`. These functions are called by
  105. * the server network layer.
  106. *
  107. * It is the job of the server network layer to listen on a TCP socket, to
  108. * accept new connections, to call the server with received messages and to
  109. * signal closed connections to the server.
  110. *
  111. * The network layer is part of the server config. So users can provide a custom
  112. * implementation if the provided example does not fit their architecture. The
  113. * network layer is invoked only from the server's main loop. So the network
  114. * layer does not need to be thread-safe. If the networklayer receives a
  115. * positive duration for blocking listening, the server's main loop will block
  116. * until a message is received or the duration times out. */
  117. /* Process a binary message (TCP packet). The message can contain partial
  118. * chunks. (TCP is a streaming protocol and packets may be split/merge during
  119. * transport.) After processing, the message is freed with
  120. * connection->releaseRecvBuffer. */
  121. void UA_EXPORT
  122. UA_Server_processBinaryMessage(UA_Server *server, UA_Connection *connection,
  123. UA_ByteString *message);
  124. /* The server internally cleans up the connection and then calls
  125. * connection->free. */
  126. void UA_EXPORT
  127. UA_Server_removeConnection(UA_Server *server, UA_Connection *connection);
  128. struct UA_ServerNetworkLayer {
  129. void *handle; /* Internal data */
  130. UA_String discoveryUrl;
  131. UA_ConnectionConfig localConnectionConfig;
  132. /* Start listening on the networklayer.
  133. *
  134. * @param nl The network layer
  135. * @return Returns UA_STATUSCODE_GOOD or an error code. */
  136. UA_StatusCode (*start)(UA_ServerNetworkLayer *nl, const UA_String *customHostname);
  137. /* Listen for new and closed connections and arriving packets. Calls
  138. * UA_Server_processBinaryMessage for the arriving packets. Closed
  139. * connections are picked up here and forwarded to
  140. * UA_Server_removeConnection where they are cleaned up and freed.
  141. *
  142. * @param nl The network layer
  143. * @param server The server for processing the incoming packets and for
  144. * closing connections.
  145. * @param timeout The timeout during which an event must arrive in
  146. * milliseconds
  147. * @return A statuscode for the status of the network layer. */
  148. UA_StatusCode (*listen)(UA_ServerNetworkLayer *nl, UA_Server *server,
  149. UA_UInt16 timeout);
  150. /* Close the network socket and all open connections. Afterwards, the
  151. * network layer can be safely deleted.
  152. *
  153. * @param nl The network layer
  154. * @param server The server that processes the incoming packets and for
  155. * closing connections before deleting them.
  156. * @return A statuscode for the status of the closing operation. */
  157. void (*stop)(UA_ServerNetworkLayer *nl, UA_Server *server);
  158. /* Deletes the network layer context. Call only after stopping. */
  159. void (*deleteMembers)(UA_ServerNetworkLayer *nl);
  160. };
  161. /**
  162. * Client Network Layer
  163. * --------------------
  164. * The client has only a single connection used for sending and receiving binary
  165. * messages. */
  166. /* @param config the connection config for this client
  167. * @param endpointUrl to where to connect
  168. * @param timeout in ms until the connection try times out if remote not reachable
  169. * @param logger the logger to use */
  170. typedef UA_Connection
  171. (*UA_ConnectClientConnection)(UA_ConnectionConfig config, const char *endpointUrl,
  172. const UA_UInt32 timeout, UA_Logger logger);
  173. _UA_END_DECLS
  174. #endif /* UA_PLUGIN_NETWORK_H_ */