generate documentation for networking

doc/CMakeLists.txt

@@ -17,6 +17,7 @@ generate_rst(${PROJECT_BINARY_DIR}/src_generated/ua_types_generated.h ${PROJECT_
 generate_rst(${PROJECT_SOURCE_DIR}/include/ua_server.h ${PROJECT_BINARY_DIR}/doc_src/server.rst)
 generate_rst(${PROJECT_SOURCE_DIR}/include/ua_client.h ${PROJECT_BINARY_DIR}/doc_src/client.rst)
 generate_rst(${PROJECT_SOURCE_DIR}/include/ua_log.h ${PROJECT_BINARY_DIR}/doc_src/log.rst)
+generate_rst(${PROJECT_SOURCE_DIR}/include/ua_connection.h ${PROJECT_BINARY_DIR}/doc_src/connection.rst)
 generate_rst(${PROJECT_SOURCE_DIR}/src/server/ua_services.h ${PROJECT_BINARY_DIR}/doc_src/services.rst)
 generate_rst(${PROJECT_SOURCE_DIR}/src/server/ua_nodestore.h ${PROJECT_BINARY_DIR}/doc_src/nodestore.rst)
 
@@ -28,6 +29,7 @@ add_custom_target(doc_latex ${SPHINX_EXECUTABLE}
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/server.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/client.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/log.rst
+  DEPENDS ${PROJECT_BINARY_DIR}/doc_src/connection.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/services.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/nodestore.rst
   COMMENT "Building LaTeX sources for documentation with Sphinx")
@@ -42,6 +44,7 @@ add_custom_target(doc ${SPHINX_EXECUTABLE}
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/server.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/client.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/log.rst
+  DEPENDS ${PROJECT_BINARY_DIR}/doc_src/connection.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/services.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/nodestore.rst
   COMMENT "Building HTML documentation with Sphinx")

doc/internal.rst

@@ -5,4 +5,5 @@ Internals
    services
    nodestore
    types_generated
+   connection
    log

include/ua_connection.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 the contributors as stated in the AUTHORS file
+ * Copyright (C) 2014-2016 the contributors as stated in the AUTHORS file
  *
  * This file is part of open62541. open62541 is free software: you can
  * redistribute it and/or modify it under the terms of the GNU Lesser General
@@ -22,10 +22,30 @@ extern "C" {
 
 #include "ua_types.h"
 
-/* Forward declaration */
+/* Forward declarations */
+struct UA_Connection;
+typedef struct UA_Connection UA_Connection;
+
 struct UA_SecureChannel;
 typedef struct UA_SecureChannel UA_SecureChannel;
 
+/**
+ * Networking
+ * ----------
+ * Client-server connection is represented by a `UA_Connection` structure. In
+ * order to allow for different operating systems and connection types. For
+ * this, `UA_Connection` stores a pointer to user-defined data and
+ * function-pointers to interact with the underlying networking implementation.
+ *
+ * An example networklayer for TCP communication is contained in the plugins
+ * folder. The networklayer forwards messages with `UA_Connection` structures to
+ * the main open62541 library. The library can then return messages vie TCP
+ * without being aware of the underlying transport technology.
+ *
+ * Connection Config
+ * =================
+ **/
+
 typedef struct UA_ConnectionConfig {
     UA_UInt32 protocolVersion;
     UA_UInt32 sendBufferSize;
@@ -36,39 +56,41 @@ typedef struct UA_ConnectionConfig {
 
 extern const UA_EXPORT UA_ConnectionConfig UA_ConnectionConfig_standard;
 
+/**
+ * Connection Structure
+ * ====================
+ */
 typedef enum UA_ConnectionState {
-    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_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;
-typedef struct UA_Connection UA_Connection;
-
-/**
- * The connection to a single client (or server). The connection is defined independent of the
- * underlying network layer implementation. This allows a plugging-in custom implementations (e.g.
- * an embedded TCP stack)
- */
 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. */
+    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 the networklayer */
-    UA_ByteString incompleteMessage; /* A half-received message (TCP is a streaming protocol) is
-                                        stored here */
+    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);
+    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.
+    /* 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
@@ -78,12 +100,13 @@ struct UA_Connection {
     /* 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 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. */
+     * @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 */

include/ua_log.h

@@ -28,6 +28,10 @@ extern "C" {
  * Servers and clients may contain a logger. Every logger needs to implement the
  * `UA_Logger` signature. An example logger that writes to stdout is provided in
  * the plugins folder.
+ *
+ * Every log-message consists of a log-level, a log-category and a string
+ * message content. The timestamp of the log-message is created within the
+ * logger.
  */
 
 typedef enum {
@@ -48,10 +52,12 @@ typedef enum {
     UA_LOGCATEGORY_USERLAND
 } UA_LogCategory;
     
-/* The signature of the logger. The msg string and following varargs are used to
-   include variable data similar to printf. Do not use the logger directly but
-   make use of the following macros that take the minimum log-level defined in
-   ua_config.h into account. */
+/**
+ * The signature of the logger. The msg string and following varargs are
+ * formatted according to the rules of the printf command.
+ *
+ * Do not use the logger directly but make use of the following macros that take
+ * the minimum log-level defined in ua_config.h into account. */
 typedef void (*UA_Logger)(UA_LogLevel level, UA_LogCategory category, const char *msg, ...);
 
 #if UA_LOGLEVEL <= 100