/* This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ #ifndef UA_PLUGIN_NETWORK_H_ #define UA_PLUGIN_NETWORK_H_ #ifdef __cplusplus extern "C" { #endif #include "ua_server.h" /* Forward declarations */ struct UA_Connection; typedef struct UA_Connection UA_Connection; struct UA_SecureChannel; typedef struct UA_SecureChannel UA_SecureChannel; struct UA_ServerNetworkLayer; typedef struct UA_ServerNetworkLayer UA_ServerNetworkLayer; /** * .. _networking: * * Networking Plugin API * ===================== * * Connection * ---------- * Client-server connections are represented by a `UA_Connection`. The * connection is stateful and stores partially received messages, and so on. In * addition, the connection contains function pointers to the underlying * networking implementation. An example for this is the `send` function. So the * connection encapsulates all the required networking functionality. This lets * users on embedded (or otherwise exotic) systems implement their own * networking plugins with a clear interface to the main open62541 library. */ typedef struct { UA_UInt32 protocolVersion; UA_UInt32 sendBufferSize; UA_UInt32 recvBufferSize; UA_UInt32 maxMessageSize; UA_UInt32 maxChunkCount; } UA_ConnectionConfig; typedef enum { UA_CONNECTION_OPENING, /* The socket is open, but the HEL/ACK handshake * is not done */ UA_CONNECTION_ESTABLISHED, /* The socket is open and the connection * configured */ UA_CONNECTION_CLOSED /* The socket has been closed and the connection * will be deleted */ } UA_ConnectionState; struct UA_Connection { UA_ConnectionState state; UA_ConnectionConfig localConf; UA_ConnectionConfig remoteConf; UA_SecureChannel *channel; /* The securechannel that is attached to * this connection */ UA_Int32 sockfd; /* Most connectivity solutions run on * sockets. Having the socket id here * simplifies the design. */ void *handle; /* A pointer to internal data */ UA_ByteString incompleteMessage; /* A half-received message (TCP is a * streaming protocol) is stored here */ /* Get a buffer for sending */ UA_StatusCode (*getSendBuffer)(UA_Connection *connection, size_t length, UA_ByteString *buf); /* Release the send buffer manually */ void (*releaseSendBuffer)(UA_Connection *connection, UA_ByteString *buf); /* Sends a message over the connection. The message buffer is always freed, * even if sending fails. * * @param connection The connection * @param buf The message buffer * @return Returns an error code or UA_STATUSCODE_GOOD. */ UA_StatusCode (*send)(UA_Connection *connection, UA_ByteString *buf); /* Receive a message from the remote connection * * @param connection The connection * @param response The response string. It is allocated by the connection * and needs to be freed with connection->releaseBuffer * @param timeout Timeout of the recv operation in milliseconds * @return Returns UA_STATUSCODE_BADCOMMUNICATIONERROR if the recv operation * can be repeated, UA_STATUSCODE_GOOD if it succeeded and * UA_STATUSCODE_BADCONNECTIONCLOSED if the connection was * closed. */ UA_StatusCode (*recv)(UA_Connection *connection, UA_ByteString *response, UA_UInt32 timeout); /* Release the buffer of a received message */ void (*releaseRecvBuffer)(UA_Connection *connection, UA_ByteString *buf); /* Close the connection. The network layer closes the socket. This is picked * up during the next 'listen' and the connection is freed in the network * layer. */ void (*close)(UA_Connection *connection); /* To be called only from within the server (and not the network layer). * Frees up the connection's memory. */ void (*free)(UA_Connection *connection); }; /* Cleans up half-received messages, and so on. Called from connection->free. */ void UA_EXPORT UA_Connection_deleteMembers(UA_Connection *connection); /** * Server Network Layer * -------------------- * The server exposes two functions to interact with remote clients: * `processBinaryMessage` and `removeConnection`. These functions are called by * the server network layer. * * It is the job of the server network layer to listen on a TCP socket, to * accept new connections, to call the server with received messages and to * signal closed connections to the server. * * The network layer is part of the server config. So users can provide a custom * implementation if the provided example does not fit their architecture. The * network layer is invoked only from the server's main loop. So the network * layer does not need to be thread-safe. If the networklayer receives a * positive duration for blocking listening, the server's main loop will block * until a message is received or the duration times out. */ /* Process a binary message (TCP packet). The message can contain partial * chunks. (TCP is a streaming protocol and packets may be split/merge during * transport.) After processing, the message is freed with * connection->releaseRecvBuffer. */ void UA_EXPORT UA_Server_processBinaryMessage(UA_Server *server, UA_Connection *connection, UA_ByteString *message); /* The server internally cleans up the connection and then calls * connection->free. */ void UA_EXPORT UA_Server_removeConnection(UA_Server *server, UA_Connection *connection); struct UA_ServerNetworkLayer { void *handle; /* Internal data */ UA_String discoveryUrl; /* Start listening on the networklayer. * * @param nl The network layer * @return Returns UA_STATUSCODE_GOOD or an error code. */ UA_StatusCode (*start)(UA_ServerNetworkLayer *nl); /* Listen for new and closed connections and arriving packets. Calls * UA_Server_processBinaryMessage for the arriving packets. Closed * connections are picked up here and forwarded to * UA_Server_removeConnection where they are cleaned up and freed. * * @param nl The network layer * @param server The server for processing the incoming packets and for * closing connections. * @param timeout The timeout during which an event must arrive in * milliseconds * @return A statuscode for the status of the network layer. */ UA_StatusCode (*listen)(UA_ServerNetworkLayer *nl, UA_Server *server, UA_UInt16 timeout); /* Close the network socket and all open connections. Afterwards, the * network layer can be safely deleted. * * @param nl The network layer * @param server The server that processes the incoming packets and for * closing connections before deleting them. * @return A statuscode for the status of the closing operation. */ void (*stop)(UA_ServerNetworkLayer *nl, UA_Server *server); /* Deletes the network layer context. Call only after stopping. */ void (*deleteMembers)(UA_ServerNetworkLayer *nl); }; /** * Client Network Layer * -------------------- * The client has only a single connection. The connection is used for both * sending and receiving binary messages. * @param localConf the connection config for this client * @param endpointUrl to where to connect * @param timeout in ms until the connection try times out if remote not reachable * */ typedef UA_Connection (*UA_ConnectClientConnection)(UA_ConnectionConfig localConf, const char *endpointUrl, const UA_UInt32 timeout); /** * Endpoint URL Parser * ------------------- * The endpoint URL parser is generally useful for the implementation of network * layer plugins. */ /* Split the given endpoint url into hostname, port and path. All arguments must * be non-NULL. EndpointUrls have the form "opc.tcp://hostname:port/path", port * and path may be omitted (together with the prefix colon and slash). * * @param endpointUrl The endpoint URL. * @param outHostname Set to the parsed hostname. The string points into the * original endpointUrl, so no memory is allocated. If an IPv6 address is * given, hostname contains e.g. '[2001:0db8:85a3::8a2e:0370:7334]' * @param outPort Set to the port of the url or left unchanged. * @param outPath Set to the path if one is present in the endpointUrl. * Starting or trailing '/' are NOT included in the path. The string * points into the original endpointUrl, so no memory is allocated. * @return Returns UA_STATUSCODE_BADTCPENDPOINTURLINVALID if parsing failed. */ UA_StatusCode UA_EXPORT UA_parseEndpointUrl(const UA_String *endpointUrl, UA_String *outHostname, UA_UInt16 *outPort, UA_String *outPath); #ifdef __cplusplus } // extern "C" #endif #endif /* UA_PLUGIN_NETWORK_H_ */