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 recvBufferSize;
UA_UInt32 sendBufferSize;
UA_UInt32 maxMessageSize; /* Indicated by the remote side (0 = unbounded) */
UA_UInt32 maxChunkCount; /* Indicated by the remote side (0 = unbounded) */
} UA_ConnectionConfig;
typedef enum {
UA_CONNECTION_CLOSED, /* The socket has been closed and the connection
* will be deleted */
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_ConnectionState;
struct UA_Connection {
UA_ConnectionState state;
UA_ConnectionConfig config;
UA_SecureChannel *channel; /* The securechannel that is attached to
* this connection */
UA_SOCKET sockfd; /* Most connectivity solutions run on
* sockets. Having the socket id here
* simplifies the design. */
UA_DateTime openingDate; /* The date the connection was created */
void *handle; /* A pointer to internal data */
UA_ByteString incompleteChunk; /* A half-received chunk (TCP is a
* streaming protocol) is stored here */
UA_UInt64 connectCallbackID; /* Callback Id, for the connect-loop */
/* 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_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_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_Server_removeConnection(UA_Server *server, UA_Connection *connection);
struct UA_ServerNetworkLayer {
void *handle; /* Internal data */
UA_String discoveryUrl;
UA_ConnectionConfig localConnectionConfig;
/* 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, const UA_String *customHostname);
/* 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 used for sending and receiving binary messages.
/* @param config 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
* @param logger the logger to use */
typedef UA_Connection
(*UA_ConnectClientConnection)(UA_ConnectionConfig config, UA_String endpointUrl,
UA_UInt32 timeout, UA_Logger *logger);