sphinx documentation for the client

doc/CMakeLists.txt

@@ -15,6 +15,7 @@ generate_rst(${PROJECT_SOURCE_DIR}/include/ua_types.h ${PROJECT_BINARY_DIR}/doc_
 generate_rst(${PROJECT_SOURCE_DIR}/include/ua_constants.h ${PROJECT_BINARY_DIR}/doc_src/constants.rst)
 generate_rst(${PROJECT_BINARY_DIR}/src_generated/ua_types_generated.h ${PROJECT_BINARY_DIR}/doc_src/types_generated.rst)
 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}/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)
 
@@ -24,6 +25,7 @@ add_custom_target(doc_latex ${SPHINX_EXECUTABLE}
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/constants.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/types_generated.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/server.rst
+  DEPENDS ${PROJECT_BINARY_DIR}/doc_src/client.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")
@@ -36,6 +38,7 @@ add_custom_target(doc ${SPHINX_EXECUTABLE}
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/constants.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/types_generated.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/server.rst
+  DEPENDS ${PROJECT_BINARY_DIR}/doc_src/client.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/services.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/nodestore.rst
   COMMENT "Building HTML documentation with Sphinx")

doc/index.rst

@@ -26,5 +26,6 @@ standard.
    types
    constants
    server
+   client
    internal
 

include/ua_client.h

@@ -1,3 +1,18 @@
+/*
+ * Copyright (C) 2014 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
+ * Public License, version 3 (as published by the Free Software Foundation) with
+ * a static linking exception as stated in the LICENSE file provided with
+ * open62541.
+ *
+ * open62541 is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ * A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ */
+
 #ifndef UA_CLIENT_H_
 #define UA_CLIENT_H_
 
@@ -11,14 +26,24 @@ extern "C" {
 #include "ua_log.h"
 #include "ua_types_generated.h"
 
+/**
+ * Client
+ * ======
+ *
+ * Client Lifecycle
+ * ---------------- */
 struct UA_Client;
 typedef struct UA_Client UA_Client;
 
 typedef enum {
-  UA_CLIENTSTATE_READY,
-  UA_CLIENTSTATE_CONNECTED,
-  UA_CLIENTSTATE_FAULTED,
-  UA_CLIENTSTATE_ERRORED
+     UA_CLIENTSTATE_READY,     /* The client is not connected but initialized and ready to use. */
+     UA_CLIENTSTATE_CONNECTED, /* The client is connected to a server. */
+     UA_CLIENTSTATE_FAULTED,   /* An error has occured that might have influenced the connection
+                                  state. A successfull service call or renewal of the secure channel
+                                  will reset the state to CONNECTED. */
+     UA_CLIENTSTATE_ERRORED    /* A non-recoverable error has occured and the connection is no
+                                  longer reliable. The client needs to be disconnected and
+                                  reinitialized to recover into a CONNECTED state. */
 } UA_Client_State;
 
 typedef struct UA_ClientConfig {
@@ -29,127 +54,112 @@ typedef struct UA_ClientConfig {
 
 extern UA_EXPORT const UA_ClientConfig UA_ClientConfig_standard;
 
-/**
- * Creates and initialize a Client object
+/* Creates a new client
  *
  * @param config for the new client. You can use UA_ClientConfig_standard which has sane defaults
- * @param logger function pointer to a logger function. See examples/logger_stdout.c for a simple implementation
- * @return return the new Client object
- */
+ * @param logger function pointer to a logger function. See examples/logger_stdout.c for a simple
+ *               implementation
+ * @return return the new Client object */
 UA_Client UA_EXPORT * UA_Client_new(UA_ClientConfig config, UA_Logger logger);
 
-/**
- * resets a Client object
- *
- * @param client to reset
- * @return Void
- */
+/* Reset a client */
 void UA_EXPORT UA_Client_reset(UA_Client* client);
 
-/**
- * delete a Client object
- *
- * @param client to delete
- * @return Void
- */
+/* Delete a client */
 void UA_EXPORT UA_Client_delete(UA_Client* client);
 
-/*************************/
-/* Manage the Connection */
-/*************************/
-
+/**
+ * Manage the Connection
+ * --------------------- */
 typedef UA_Connection (*UA_ConnectClientConnection)(UA_ConnectionConfig localConf, const char *endpointUrl,
                                                     UA_Logger logger);
 
-/**
- * Gets a list of endpoints of a server
+/* Gets a list of endpoints of a server
+ *
  * @param client to use
  * @param connection function. You can use ClientNetworkLayerTCP_connect from examples/networklayer_tcp.h
  * @param server url to connect (for example "opc.tcp://localhost:16664")
  * @param endpointDescriptionsSize size of the array of endpoint descriptions
  * @param endpointDescriptions array of endpoint descriptions that is allocated by the function (you need to free manually)
- * @return Indicates whether the operation succeeded or returns an error code
- */
+ * @return Indicates whether the operation succeeded or returns an error code */
 UA_StatusCode UA_EXPORT
 UA_Client_getEndpoints(UA_Client *client, UA_ConnectClientConnection connectFunc,
                        const char *serverUrl, size_t* endpointDescriptionsSize,
                        UA_EndpointDescription** endpointDescriptions);
-/**
- * start a connection to the selected server
+
+/* Connect to the selected server
  *
  * @param client to use
  * @param connection function. You can use ClientNetworkLayerTCP_connect from examples/networklayer_tcp.h
  * @param endpointURL to connect (for example "opc.tcp://localhost:16664")
- * @return Indicates whether the operation succeeded or returns an error code
- */
+ * @return Indicates whether the operation succeeded or returns an error code */
 UA_StatusCode UA_EXPORT
 UA_Client_connect(UA_Client *client, UA_ConnectClientConnection connFunc, const char *endpointUrl);
 
-/**
- * start a connection to the selected server
+/* Connect to the selected server with the given username and password
  *
  * @param client to use
  * @param connection function. You can use ClientNetworkLayerTCP_connect from examples/networklayer_tcp.h
  * @param endpointURL to connect (for example "opc.tcp://localhost:16664")
  * @param username
  * @param password
- * @return Indicates whether the operation succeeded or returns an error code
- */
+ * @return Indicates whether the operation succeeded or returns an error code */
 UA_StatusCode UA_EXPORT
-UA_Client_connect_username(UA_Client *client, UA_ConnectClientConnection connFunc, const char *endpointUrl, const char *username, const char *password);
+UA_Client_connect_username(UA_Client *client, UA_ConnectClientConnection connFunc,
+                           const char *endpointUrl, const char *username, const char *password);
 
-/**
- * close a connection to the selected server
- *
- * @param client to use
- * @return Indicates whether the operation succeeded or returns an error code
- */
+/* Close a connection to the selected server */
 UA_StatusCode UA_EXPORT UA_Client_disconnect(UA_Client *client);
 
-/**
- * renew a secure channel if needed
- *
- * @param client to use
- * @return Indicates whether the operation succeeded or returns an error code
- */
+/* Renew the underlying secure channel */
 UA_StatusCode UA_EXPORT UA_Client_manuallyRenewSecureChannel(UA_Client *client);
 
 
-/**
- * @brief Get the client connection status
- * 
- * Returns the client connection status, being one of the following:
- * - UA_CLIENTSTATE_READY:     The client is not connected but initialized and ready to use.
- * - UA_CLIENTSTATE_CONNECTED: The client is connected to a server.
- * - UA_CLIENTSTATE_FAULTED:   An error has occured that might have influenced the connection state.
- *                             A successfull service call or renewal of the secure channel will 
- *                             reset the state to CONNECTED.
- * - UA_CLIENTSTATE_ERRORED:   A non-recoverable error has occured and the connection is no longer
- *                             reliable. The client needs to be disconnected and reinitialized to 
- *                             recover into a CONNECTED state.
- * @param client to use.
- * @return Current state of the client.
- */
+/* Get the client connection status */
 UA_Client_State UA_EXPORT UA_Client_getState(UA_Client *client);
 
-/****************/
-/* Raw Services */
-/****************/
-
-/* Don't use this function. There are typed versions. */
+/**
+ * Raw Services
+ * ------------
+ *
+ * The raw OPC UA services are exposed to the client. But most of them time, it is better to use the
+ * convenience functions from `ua_client_highlevel.h` that wrap the raw services. See the Section
+ * :ref:`services` for a detailed description of each service. */
+/* Don't use this function. Use the type versions below instead. */
 void UA_EXPORT
 __UA_Client_Service(UA_Client *client, const void *request, const UA_DataType *requestType,
                     void *response, const UA_DataType *responseType);
 
-/* NodeManagement Service Set */
+/**
+ * Attribute Service Set
+ * ^^^^^^^^^^^^^^^^^^^^^ */
+static UA_INLINE UA_ReadResponse
+UA_Client_Service_read(UA_Client *client, const UA_ReadRequest request) {
+    UA_ReadResponse response;
+    __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_READREQUEST],
+                        &response, &UA_TYPES[UA_TYPES_READRESPONSE]);
+    return response; }
+
+static UA_INLINE UA_WriteResponse
+UA_Client_Service_write(UA_Client *client, const UA_WriteRequest request) {
+    UA_WriteResponse response;
+    __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_WRITEREQUEST],
+                        &response, &UA_TYPES[UA_TYPES_WRITERESPONSE]);
+    return response; }
 
 /**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
+ * Method Service Set
+ * ^^^^^^^^^^^^^^^^^^ */
+static UA_INLINE UA_CallResponse
+UA_Client_Service_call(UA_Client *client, const UA_CallRequest request) {
+    UA_CallResponse response;
+    __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_CALLREQUEST],
+                        &response, &UA_TYPES[UA_TYPES_CALLRESPONSE]);
+    return response; }
+
+/**
+ * NodeManagement Service Set
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^ */
 static UA_INLINE UA_AddNodesResponse
 UA_Client_Service_addNodes(UA_Client *client, const UA_AddNodesRequest request) {
     UA_AddNodesResponse response;
@@ -157,13 +167,6 @@ UA_Client_Service_addNodes(UA_Client *client, const UA_AddNodesRequest request)
                         &response, &UA_TYPES[UA_TYPES_ADDNODESRESPONSE]);
     return response; }
 
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
 static UA_INLINE UA_AddReferencesResponse
 UA_Client_Service_addReferences(UA_Client *client, const UA_AddReferencesRequest request) {
     UA_AddReferencesResponse response;
@@ -171,13 +174,6 @@ UA_Client_Service_addReferences(UA_Client *client, const UA_AddReferencesRequest
                         &response, &UA_TYPES[UA_TYPES_ADDNODESRESPONSE]);
     return response; }
 
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
 static UA_INLINE UA_DeleteNodesResponse
 UA_Client_Service_deleteNodes(UA_Client *client, const UA_DeleteNodesRequest request) {
     UA_DeleteNodesResponse response;
@@ -185,13 +181,6 @@ UA_Client_Service_deleteNodes(UA_Client *client, const UA_DeleteNodesRequest req
                         &response, &UA_TYPES[UA_TYPES_DELETENODESRESPONSE]);
     return response; }
 
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
 static UA_INLINE UA_DeleteReferencesResponse
 UA_Client_Service_deleteReferences(UA_Client *client, const UA_DeleteReferencesRequest request) {
     UA_DeleteReferencesResponse response;
@@ -199,15 +188,9 @@ UA_Client_Service_deleteReferences(UA_Client *client, const UA_DeleteReferencesR
                         &response, &UA_TYPES[UA_TYPES_DELETENODESRESPONSE]);
     return response; }
 
-/* View Service Set */
-
 /**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
+ * View Service Set
+ * ^^^^^^^^^^^^^^^^ */
 static UA_INLINE UA_BrowseResponse
 UA_Client_Service_browse(UA_Client *client, const UA_BrowseRequest request) {
     UA_BrowseResponse response;
@@ -215,13 +198,6 @@ UA_Client_Service_browse(UA_Client *client, const UA_BrowseRequest request) {
                         &response, &UA_TYPES[UA_TYPES_BROWSERESPONSE]);
     return response; }
 
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
 static UA_INLINE UA_BrowseNextResponse
 UA_Client_Service_browseNext(UA_Client *client, const UA_BrowseNextRequest request) {
     UA_BrowseNextResponse response;
@@ -229,13 +205,6 @@ UA_Client_Service_browseNext(UA_Client *client, const UA_BrowseNextRequest reque
                         &response, &UA_TYPES[UA_TYPES_BROWSENEXTRESPONSE]);
     return response; }
 
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
 static UA_INLINE UA_TranslateBrowsePathsToNodeIdsResponse
 UA_Client_Service_translateBrowsePathsToNodeIds(UA_Client *client,
                                                 const UA_TranslateBrowsePathsToNodeIdsRequest request) {
@@ -244,13 +213,6 @@ UA_Client_Service_translateBrowsePathsToNodeIds(UA_Client *client,
                         &response, &UA_TYPES[UA_TYPES_TRANSLATEBROWSEPATHSTONODEIDSRESPONSE]);
     return response; }
 
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
 static UA_INLINE UA_RegisterNodesResponse
 UA_Client_Service_registerNodes(UA_Client *client, const UA_RegisterNodesRequest request) {
     UA_RegisterNodesResponse response;
@@ -258,13 +220,6 @@ UA_Client_Service_registerNodes(UA_Client *client, const UA_RegisterNodesRequest
                         &response, &UA_TYPES[UA_TYPES_REGISTERNODESRESPONSE]);
     return response; }
 
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
 static UA_INLINE UA_UnregisterNodesResponse
 UA_Client_Service_unregisterNodes(UA_Client *client, const UA_UnregisterNodesRequest request) {
     UA_UnregisterNodesResponse response;
@@ -272,15 +227,9 @@ UA_Client_Service_unregisterNodes(UA_Client *client, const UA_UnregisterNodesReq
                         &response, &UA_TYPES[UA_TYPES_UNREGISTERNODESRESPONSE]);
     return response; }
 
-/* Query Service Set */
-
 /**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
+ * Query Service Set
+ * ^^^^^^^^^^^^^^^^^ */
 static UA_INLINE UA_QueryFirstResponse
 UA_Client_Service_queryFirst(UA_Client *client, const UA_QueryFirstRequest request) {
     UA_QueryFirstResponse response;
@@ -288,13 +237,6 @@ UA_Client_Service_queryFirst(UA_Client *client, const UA_QueryFirstRequest reque
                         &response, &UA_TYPES[UA_TYPES_QUERYFIRSTRESPONSE]);
     return response; }
 
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
 static UA_INLINE UA_QueryNextResponse
 UA_Client_Service_queryNext(UA_Client *client, const UA_QueryNextRequest request) {
     UA_QueryNextResponse response;
@@ -302,62 +244,11 @@ UA_Client_Service_queryNext(UA_Client *client, const UA_QueryNextRequest request
                         &response, &UA_TYPES[UA_TYPES_QUERYFIRSTRESPONSE]);
     return response; }
 
-/* Attribute Service Set */
-
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
-static UA_INLINE UA_ReadResponse
-UA_Client_Service_read(UA_Client *client, const UA_ReadRequest request) {
-    UA_ReadResponse response;
-    __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_READREQUEST],
-                        &response, &UA_TYPES[UA_TYPES_READRESPONSE]);
-    return response; }
-
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
-static UA_INLINE UA_WriteResponse
-UA_Client_Service_write(UA_Client *client, const UA_WriteRequest request) {
-    UA_WriteResponse response;
-    __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_WRITEREQUEST],
-                        &response, &UA_TYPES[UA_TYPES_WRITERESPONSE]);
-    return response; }
-
-/* Method Service Set */
-
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
-static UA_INLINE UA_CallResponse
-UA_Client_Service_call(UA_Client *client, const UA_CallRequest request) {
-    UA_CallResponse response;
-    __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_CALLREQUEST],
-                        &response, &UA_TYPES[UA_TYPES_CALLRESPONSE]);
-    return response; }
-
 #ifdef UA_ENABLE_SUBSCRIPTIONS
-/* MonitoredItem Service Set */
 
 /**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
+ * MonitoredItem Service Set
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^ */
 static UA_INLINE UA_CreateMonitoredItemsResponse
 UA_Client_Service_createMonitoredItems(UA_Client *client, const UA_CreateMonitoredItemsRequest request) {
     UA_CreateMonitoredItemsResponse response;
@@ -365,13 +256,6 @@ UA_Client_Service_createMonitoredItems(UA_Client *client, const UA_CreateMonitor
                         &response, &UA_TYPES[UA_TYPES_CREATEMONITOREDITEMSRESPONSE]);
     return response; }
 
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
 static UA_INLINE UA_DeleteMonitoredItemsResponse
 UA_Client_Service_deleteMonitoredItems(UA_Client *client, const UA_DeleteMonitoredItemsRequest request) {
     UA_DeleteMonitoredItemsResponse response;
@@ -379,15 +263,9 @@ UA_Client_Service_deleteMonitoredItems(UA_Client *client, const UA_DeleteMonitor
                         &response, &UA_TYPES[UA_TYPES_DELETEMONITOREDITEMSRESPONSE]);
     return response; }
 
-/* Subscription Service Set */
-
 /**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
+ * Subscription Service Set
+ * ^^^^^^^^^^^^^^^^^^^^^^^^ */
 static UA_INLINE UA_CreateSubscriptionResponse
 UA_Client_Service_createSubscription(UA_Client *client, const UA_CreateSubscriptionRequest request) {
     UA_CreateSubscriptionResponse response;
@@ -395,13 +273,6 @@ UA_Client_Service_createSubscription(UA_Client *client, const UA_CreateSubscript
                         &response, &UA_TYPES[UA_TYPES_CREATESUBSCRIPTIONRESPONSE]);
     return response; }
 
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
 static UA_INLINE UA_ModifySubscriptionResponse
 UA_Client_Service_modifySubscription(UA_Client *client, const UA_ModifySubscriptionRequest request) {
     UA_ModifySubscriptionResponse response;
@@ -409,13 +280,6 @@ UA_Client_Service_modifySubscription(UA_Client *client, const UA_ModifySubscript
                         &response, &UA_TYPES[UA_TYPES_MODIFYSUBSCRIPTIONRESPONSE]);
     return response; }
 
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
 static UA_INLINE UA_DeleteSubscriptionsResponse
 UA_Client_Service_deleteSubscriptions(UA_Client *client, const UA_DeleteSubscriptionsRequest request) {
     UA_DeleteSubscriptionsResponse response;
@@ -423,19 +287,13 @@ UA_Client_Service_deleteSubscriptions(UA_Client *client, const UA_DeleteSubscrip
                         &response, &UA_TYPES[UA_TYPES_DELETESUBSCRIPTIONSRESPONSE]);
     return response; }
 
-/**
- * performs a service
- *
- * @param client to use
- * @param request to use
- * @return returns the response which has the UA_StatusCode in a UA_ResponseHeader
- */
 static UA_INLINE UA_PublishResponse
 UA_Client_Service_publish(UA_Client *client, const UA_PublishRequest request) {
     UA_PublishResponse response;
     __UA_Client_Service(client, &request, &UA_TYPES[UA_TYPES_PUBLISHREQUEST],
                         &response, &UA_TYPES[UA_TYPES_PUBLISHRESPONSE]);
     return response; }
+
 #endif
 
 #ifdef __cplusplus

src/server/ua_services.h

@@ -13,6 +13,8 @@ extern "C" {
 #include "ua_nodes.h"
 
 /**
+ * .. _services:
+ *
  * Services
  * ========
  * The services defined in the OPC UA standard. */