ua_plugin_network.h 9.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223
  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_PLUGIN_NETWORK_H_
  5. #define UA_PLUGIN_NETWORK_H_
  6. #ifdef __cplusplus
  7. extern "C" {
  8. #endif
  9. #include "ua_types.h"
  10. /* Forward declarations */
  11. struct UA_Connection;
  12. typedef struct UA_Connection UA_Connection;
  13. struct UA_SecureChannel;
  14. typedef struct UA_SecureChannel UA_SecureChannel;
  15. struct UA_Server;
  16. typedef struct UA_Server UA_Server;
  17. struct UA_ServerNetworkLayer;
  18. typedef struct UA_ServerNetworkLayer UA_ServerNetworkLayer;
  19. /**
  20. * .. _networking:
  21. *
  22. * Networking Plugin API
  23. * =====================
  24. *
  25. * Connection
  26. * ----------
  27. * Client-server connections are represented by a `UA_Connection`. The
  28. * connection is stateful and stores partially received messages, and so on. In
  29. * addition, the connection contains function pointers to the underlying
  30. * networking implementation. An example for this is the `send` function. So the
  31. * connection encapsulates all the required networking functionality. This lets
  32. * users on embedded (or otherwise exotic) systems implement their own
  33. * networking plugins with a clear interface to the main open62541 library. */
  34. typedef struct {
  35. UA_UInt32 protocolVersion;
  36. UA_UInt32 sendBufferSize;
  37. UA_UInt32 recvBufferSize;
  38. UA_UInt32 maxMessageSize;
  39. UA_UInt32 maxChunkCount;
  40. } UA_ConnectionConfig;
  41. typedef enum {
  42. UA_CONNECTION_OPENING, /* The socket is open, but the HEL/ACK handshake
  43. * is not done */
  44. UA_CONNECTION_ESTABLISHED, /* The socket is open and the connection
  45. * configured */
  46. UA_CONNECTION_CLOSED /* The socket has been closed and the connection
  47. * will be deleted */
  48. } UA_ConnectionState;
  49. struct UA_Connection {
  50. UA_ConnectionState state;
  51. UA_ConnectionConfig localConf;
  52. UA_ConnectionConfig remoteConf;
  53. UA_SecureChannel *channel; /* The securechannel that is attached to
  54. * this connection */
  55. UA_Int32 sockfd; /* Most connectivity solutions run on
  56. * sockets. Having the socket id here
  57. * simplifies the design. */
  58. void *handle; /* A pointer to internal data */
  59. UA_ByteString incompleteMessage; /* A half-received message (TCP is a
  60. * streaming protocol) is stored here */
  61. /* Get a buffer for sending */
  62. UA_StatusCode (*getSendBuffer)(UA_Connection *connection, size_t length,
  63. UA_ByteString *buf);
  64. /* Release the send buffer manually */
  65. void (*releaseSendBuffer)(UA_Connection *connection, UA_ByteString *buf);
  66. /* Sends a message over the connection. The message buffer is always freed,
  67. * even if sending fails.
  68. *
  69. * @param connection The connection
  70. * @param buf The message buffer
  71. * @return Returns an error code or UA_STATUSCODE_GOOD. */
  72. UA_StatusCode (*send)(UA_Connection *connection, UA_ByteString *buf);
  73. /* Receive a message from the remote connection
  74. *
  75. * @param connection The connection
  76. * @param response The response string. It is allocated by the connection
  77. * and needs to be freed with connection->releaseBuffer
  78. * @param timeout Timeout of the recv operation in milliseconds
  79. * @return Returns UA_STATUSCODE_BADCOMMUNICATIONERROR if the recv operation
  80. * can be repeated, UA_STATUSCODE_GOOD if it succeeded and
  81. * UA_STATUSCODE_BADCONNECTIONCLOSED if the connection was
  82. * closed. */
  83. UA_StatusCode (*recv)(UA_Connection *connection, UA_ByteString *response,
  84. UA_UInt32 timeout);
  85. /* Release the buffer of a received message */
  86. void (*releaseRecvBuffer)(UA_Connection *connection, UA_ByteString *buf);
  87. /* Close the connection. The network layer closes the socket. This is picked
  88. * up during the next 'listen' and the connection is freed in the network
  89. * layer. */
  90. void (*close)(UA_Connection *connection);
  91. /* To be called only from within the server (and not the network layer).
  92. * Frees up the connection's memory. */
  93. void (*free)(UA_Connection *connection);
  94. };
  95. /* Cleans up half-received messages, and so on. Called from connection->free. */
  96. void UA_EXPORT
  97. UA_Connection_deleteMembers(UA_Connection *connection);
  98. /**
  99. * Server Network Layer
  100. * --------------------
  101. * The server exposes two functions to interact with remote clients:
  102. * `processBinaryMessage` and `removeConnection`. These functions are called by
  103. * the server network layer.
  104. *
  105. * It is the job of the server network layer to listen on a TCP socket, to
  106. * accept new connections, to call the server with received messages and to
  107. * signal closed connections to the server.
  108. *
  109. * The network layer is part of the server config. So users can provide a custom
  110. * implementation if the provided example does not fit their architecture. The
  111. * network layer is invoked only from the server's main loop. So the network
  112. * layer does not need to be thread-safe. If the networklayer receives a
  113. * positive duration for blocking listening, the server's main loop will block
  114. * until a message is received or the duration times out. */
  115. /* Process a binary message (TCP packet). The message can contain partial
  116. * chunks. (TCP is a streaming protocol and packets may be split/merge during
  117. * transport.) After processing, the message is freed with
  118. * connection->releaseRecvBuffer. */
  119. void UA_EXPORT
  120. UA_Server_processBinaryMessage(UA_Server *server, UA_Connection *connection,
  121. UA_ByteString *message);
  122. /* The server internally cleans up the connection and then calls
  123. * connection->free. */
  124. void UA_EXPORT
  125. UA_Server_removeConnection(UA_Server *server, UA_Connection *connection);
  126. struct UA_ServerNetworkLayer {
  127. void *handle; /* Internal data */
  128. UA_String discoveryUrl;
  129. /* Start listening on the networklayer.
  130. *
  131. * @param nl The network layer
  132. * @return Returns UA_STATUSCODE_GOOD or an error code. */
  133. UA_StatusCode (*start)(UA_ServerNetworkLayer *nl);
  134. /* Listen for new and closed connections and arriving packets. Calls
  135. * UA_Server_processBinaryMessage for the arriving packets. Closed
  136. * connections are picked up here and forwarded to
  137. * UA_Server_removeConnection where they are cleaned up and freed.
  138. *
  139. * @param nl The network layer
  140. * @param server The server for processing the incoming packets and for
  141. * closing connections.
  142. * @param timeout The timeout during which an event must arrive in
  143. * milliseconds
  144. * @return A statuscode for the status of the network layer. */
  145. UA_StatusCode (*listen)(UA_ServerNetworkLayer *nl, UA_Server *server,
  146. UA_UInt16 timeout);
  147. /* Close the network socket and all open connections. Afterwards, the
  148. * network layer can be safely deleted.
  149. *
  150. * @param nl The network layer
  151. * @param server The server that processes the incoming packets and for
  152. * closing connections before deleting them.
  153. * @return A statuscode for the status of the closing operation. */
  154. void (*stop)(UA_ServerNetworkLayer *nl, UA_Server *server);
  155. /* Deletes the network layer context. Call only after stopping. */
  156. void (*deleteMembers)(UA_ServerNetworkLayer *nl);
  157. };
  158. /**
  159. * Client Network Layer
  160. * --------------------
  161. * The client has only a single connection. The connection is used for both
  162. * sending and receiving binary messages. */
  163. typedef UA_Connection
  164. (*UA_ConnectClientConnection)(UA_ConnectionConfig localConf, const char *endpointUrl);
  165. /**
  166. * Endpoint URL Parser
  167. * -------------------
  168. * The endpoint URL parser is generally useful for the implementation of network
  169. * layer plugins. */
  170. /* Split the given endpoint url into hostname, port and path. All arguments must
  171. * be non-NULL. EndpointUrls have the form "opc.tcp://hostname:port/path", port
  172. * and path may be omitted (together with the prefix colon and slash).
  173. *
  174. * @param endpointUrl The endpoint URL.
  175. * @param outHostname Set to the parsed hostname. The string points into the
  176. * original endpointUrl, so no memory is allocated. If an IPv6 address is
  177. * given, hostname contains e.g. '[2001:0db8:85a3::8a2e:0370:7334]'
  178. * @param outPort Set to the port of the url or left unchanged.
  179. * @param outPath Set to the path if one is present in the endpointUrl.
  180. * Starting or trailing '/' are NOT included in the path. The string
  181. * points into the original endpointUrl, so no memory is allocated.
  182. * @return Returns UA_STATUSCODE_BADTCPENDPOINTURLINVALID if parsing failed. */
  183. UA_StatusCode UA_EXPORT
  184. UA_parseEndpointUrl(const UA_String *endpointUrl, UA_String *outHostname,
  185. UA_UInt16 *outPort, UA_String *outPath);
  186. #ifdef __cplusplus
  187. } // extern "C"
  188. #endif
  189. #endif /* UA_PLUGIN_NETWORK_H_ */