improve documentation of the service signatures

src/server/ua_services.h

@@ -29,10 +29,12 @@ extern "C" {
  * Still, we present them here for an overview of the capabilities of OPC UA.
  * Please refer to the :ref:`client` and :ref:`server` API where the services
  * are exposed to end users. Please see part 4 of the OPC UA standard for the
- * authoritative definition of the service and their behaviour. */
-/* Most services take as input the server, the current session and pointers to
+ * authoritative definition of the service and their behaviour.
+ *
+ * Most services take as input the server, the current session and pointers to
  * the request and response structures. Possible error codes are returned as
  * part of the response. */
+
 typedef void (*UA_Service)(UA_Server*, UA_Session*,
                            const void *request, void *response);
 
@@ -40,14 +42,20 @@ typedef void (*UA_Service)(UA_Server*, UA_Session*,
  * Discovery Service Set
  * ---------------------
  * This Service Set defines Services used to discover the Endpoints implemented
- * by a Server and to read the security configuration for those Endpoints. */
-/* Returns the Servers known to a Server or Discovery Server.
- * The Client may reduce the number of results returned by specifying filter criteria */
+ * by a Server and to read the security configuration for those Endpoints.
+ *
+ * FindServers Service
+ * ^^^^^^^^^^^^^^^^^^^
+ * Returns the Servers known to a Server or Discovery Server. The Client may
+ * reduce the number of results returned by specifying filter criteria */
 void Service_FindServers(UA_Server *server, UA_Session *session,
                          const UA_FindServersRequest *request,
                          UA_FindServersResponse *response);
 
-/* Returns the Endpoints supported by a Server and all of the configuration
+/**
+ * GetEndpoints Service
+ * ^^^^^^^^^^^^^^^^^^^^
+ * Returns the Endpoints supported by a Server and all of the configuration
  * information required to establish a SecureChannel and a Session. */
 void Service_GetEndpoints(UA_Server *server, UA_Session *session,
                           const UA_GetEndpointsRequest *request,
@@ -56,48 +64,69 @@ void Service_GetEndpoints(UA_Server *server, UA_Session *session,
 #ifdef UA_ENABLE_DISCOVERY
 
 # ifdef UA_ENABLE_DISCOVERY_MULTICAST
-/* Returns the Servers known to a Discovery Server. Unlike FindServer,
+
+/**
+ * FindServersOnNetwork Service
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * Returns the Servers known to a Discovery Server. Unlike FindServer,
  * this Service is only implemented by Discovery Servers. It additionally
  * Returns servery which may have been detected trough Multicast */
 void Service_FindServersOnNetwork(UA_Server *server, UA_Session *session,
                                   const UA_FindServersOnNetworkRequest *request,
                                   UA_FindServersOnNetworkResponse *response);
-# endif // UA_ENABLE_DISCOVERY_MULTICAST
 
-/* Registers a remote server in the local discovery service. */
+# endif /* UA_ENABLE_DISCOVERY_MULTICAST */
+
+/**
+ * RegisterServer
+ * ^^^^^^^^^^^^^^
+ * Registers a remote server in the local discovery service. */
 void Service_RegisterServer(UA_Server *server, UA_Session *session,
                             const UA_RegisterServerRequest *request,
                             UA_RegisterServerResponse *response);
 
-/* This Service allows a Server to register its DiscoveryUrls and capabilities
+/**
+ * RegisterServer2
+ * ^^^^^^^^^^^^^^^
+ * This Service allows a Server to register its DiscoveryUrls and capabilities
  * with a Discovery Server. It extends the registration information from
  * RegisterServer with information necessary for FindServersOnNetwork. */
 void Service_RegisterServer2(UA_Server *server, UA_Session *session,
                             const UA_RegisterServer2Request *request,
                             UA_RegisterServer2Response *response);
-#endif // UA_ENABLE_DISCOVERY
+
+#endif /* UA_ENABLE_DISCOVERY */
 
 /**
  * SecureChannel Service Set
  * -------------------------
  * This Service Set defines Services used to open a communication channel that
  * ensures the confidentiality and Integrity of all Messages exchanged with the
- * Server. */
-/* Open or renew a SecureChannel that can be used to ensure Confidentiality and
+ * Server.
+ *
+ * OpenSecureChannel Service
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^
+ * Open or renew a SecureChannel that can be used to ensure Confidentiality and
  * Integrity for Message exchange during a Session. */
 void Service_OpenSecureChannel(UA_Server *server, UA_Connection *connection,
                                const UA_OpenSecureChannelRequest *request,
                                UA_OpenSecureChannelResponse *response);
 
-/* Used to terminate a SecureChannel. */
+/**
+ * CloseSecureChannel Service
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * Used to terminate a SecureChannel. */
 void Service_CloseSecureChannel(UA_Server *server, UA_SecureChannel *channel);
 
 /**
  * Session Service Set
  * -------------------
  * This Service Set defines Services for an application layer connection
- * establishment in the context of a Session. */
-/* Used by an OPC UA Client to create a Session and the Server returns two
+ * establishment in the context of a Session.
+ *
+ * CreateSession Service
+ * ^^^^^^^^^^^^^^^^^^^^^
+ * Used by an OPC UA Client to create a Session and the Server returns two
  * values which uniquely identify the Session. The first value is the sessionId
  * which is used to identify the Session in the audit logs and in the Server's
  * address space. The second is the authenticationToken which is used to
@@ -106,7 +135,10 @@ void Service_CreateSession(UA_Server *server, UA_SecureChannel *channel,
                            const UA_CreateSessionRequest *request,
                            UA_CreateSessionResponse *response);
 
-/* Used by the Client to submit its SoftwareCertificates to the Server for
+/**
+ * ActivateSession
+ * ^^^^^^^^^^^^^^^
+ * Used by the Client to submit its SoftwareCertificates to the Server for
  * validation and to specify the identity of the user associated with the
  * Session. This Service request shall be issued by the Client before it issues
  * any other Service request after CreateSession. Failure to do so shall cause
@@ -116,12 +148,20 @@ void Service_ActivateSession(UA_Server *server, UA_SecureChannel *channel,
                              const UA_ActivateSessionRequest *request,
                              UA_ActivateSessionResponse *response);
 
-/* Used to terminate a Session. */
+/**
+ * CloseSession
+ * ^^^^^^^^^^^^
+ * Used to terminate a Session. */
 void Service_CloseSession(UA_Server *server, UA_Session *session,
                           const UA_CloseSessionRequest *request,
                           UA_CloseSessionResponse *response);
 
-/* Not Implemented: Service_Cancel */
+/**
+ * Cancel Service
+ * ^^^^^^^^^^^^^^
+ * Used to cancel outstanding Service requests. Successfully cancelled service
+ * requests shall respond with Bad_RequestCancelledByClient. */
+/* Not Implemented */
 
 /**
  * NodeManagement Service Set
@@ -129,23 +169,35 @@ void Service_CloseSession(UA_Server *server, UA_Session *session,
  * This Service Set defines Services to add and delete AddressSpace Nodes and
  * References between them. All added Nodes continue to exist in the
  * AddressSpace even if the Client that created them disconnects from the
- * Server. */
-/* Used to add one or more Nodes into the AddressSpace hierarchy. */
+ * Server.
+ *
+ * AddNodes Service
+ * ^^^^^^^^^^^^^^^^
+ * Used to add one or more Nodes into the AddressSpace hierarchy. */
 void Service_AddNodes(UA_Server *server, UA_Session *session,
                       const UA_AddNodesRequest *request,
                       UA_AddNodesResponse *response);
 
-/* Used to add one or more References to one or more Nodes. */
+/**
+ * AddReferences Service
+ * ^^^^^^^^^^^^^^^^^^^^^
+ * Used to add one or more References to one or more Nodes. */
 void Service_AddReferences(UA_Server *server, UA_Session *session,
                            const UA_AddReferencesRequest *request,
                            UA_AddReferencesResponse *response);
 
-/* Used to delete one or more Nodes from the AddressSpace. */
+/**
+ * DeleteNodes Service
+ * ^^^^^^^^^^^^^^^^^^^
+ * Used to delete one or more Nodes from the AddressSpace. */
 void Service_DeleteNodes(UA_Server *server, UA_Session *session,
                          const UA_DeleteNodesRequest *request,
                          UA_DeleteNodesResponse *response);
 
-/* Used to delete one or more References of a Node. */
+/**
+ * DeleteReferences
+ * ^^^^^^^^^^^^^^^^
+ * Used to delete one or more References of a Node. */
 void Service_DeleteReferences(UA_Server *server, UA_Session *session,
                               const UA_DeleteReferencesRequest *request,
                               UA_DeleteReferencesResponse *response);
@@ -156,15 +208,21 @@ void Service_DeleteReferences(UA_Server *server, UA_Session *session,
  * View Service Set
  * ----------------
  * Clients use the browse Services of the View Service Set to navigate through
- * the AddressSpace or through a View which is a subset of the AddressSpace. */
-/* Used to discover the References of a specified Node. The browse can be
+ * the AddressSpace or through a View which is a subset of the AddressSpace.
+ *
+ * Browse Service
+ * ^^^^^^^^^^^^^^
+ * Used to discover the References of a specified Node. The browse can be
  * further limited by the use of a View. This Browse Service also supports a
  * primitive filtering capability. */
 void Service_Browse(UA_Server *server, UA_Session *session,
                     const UA_BrowseRequest *request,
                     UA_BrowseResponse *response);
 
-/* Used to request the next set of Browse or BrowseNext response information
+/**
+ * BrowseNext Service
+ * ^^^^^^^^^^^^^^^^^^
+ * Used to request the next set of Browse or BrowseNext response information
  * that is too large to be sent in a single response. "Too large" in this
  * context means that the Server is not able to return a larger response or that
  * the number of results to return exceeds the maximum number of results to
@@ -173,19 +231,28 @@ void Service_BrowseNext(UA_Server *server, UA_Session *session,
                         const UA_BrowseNextRequest *request,
                         UA_BrowseNextResponse *response);
 
-/* Used to translate textual node paths to their respective ids. */
+/**
+ * TranslateBrowsePathsToNodeIds Service
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * Used to translate textual node paths to their respective ids. */
 void Service_TranslateBrowsePathsToNodeIds(UA_Server *server, UA_Session *session,
              const UA_TranslateBrowsePathsToNodeIdsRequest *request,
              UA_TranslateBrowsePathsToNodeIdsResponse *response);
 
-/* Used by Clients to register the Nodes that they know they will access
+/**
+ * RegisterNodes Service
+ * ^^^^^^^^^^^^^^^^^^^^^
+ * Used by Clients to register the Nodes that they know they will access
  * repeatedly (e.g. Write, Call). It allows Servers to set up anything needed so
  * that the access operations will be more efficient. */
 void Service_RegisterNodes(UA_Server *server, UA_Session *session,
                            const UA_RegisterNodesRequest *request,
                            UA_RegisterNodesResponse *response);
 
-/* This Service is used to unregister NodeIds that have been obtained via the
+/**
+ * UnregisterNodes Service
+ * ^^^^^^^^^^^^^^^^^^^^^^^
+ * This Service is used to unregister NodeIds that have been obtained via the
  * RegisterNodes service. */
 void Service_UnregisterNodes(UA_Server *server, UA_Session *session,
                              const UA_UnregisterNodesRequest *request,
@@ -200,33 +267,62 @@ void Service_UnregisterNodes(UA_Server *server, UA_Session *session,
  * and information management systems. OPC UA Query permits a Client to access
  * data maintained by a Server without any knowledge of the logical schema used
  * for internal storage of the data. Knowledge of the AddressSpace is
- * sufficient. */
-/* Not Implemented: Service_QueryFirst */
-/* Not Impelemented: Service_QueryNext */
+ * sufficient.
+ *
+ * QueryFirst Service
+ * ^^^^^^^^^^^^^^^^^^
+ * This Service is used to issue a Query request to the Server. */
+/* Not Implemented */
+
+/**
+ * QueryNext Service
+ * ^^^^^^^^^^^^^^^^^
+ * This Service is used to request the next set of QueryFirst or QueryNext
+ * response information that is too large to be sent in a single response. */
+/* Not Impelemented */
 
 /**
  * Attribute Service Set
  * ---------------------
  * This Service Set provides Services to access Attributes that are part of
- * Nodes. */
-/* Used to read one or more Attributes of one or more Nodes. For constructed
- * Attribute values whose elements are indexed, such as an array, this Service
- * allows Clients to read the entire set of indexed values as a composite, to
- * read individual elements or to read ranges of elements of the composite. */
+ * Nodes.
+ *
+ * Read Service
+ * ^^^^^^^^^^^^
+ * Used to read attributes of nodes. For constructed attribute values whose
+ * elements are indexed, such as an array, this Service allows Clients to read
+ * the entire set of indexed values as a composite, to read individual elements
+ * or to read ranges of elements of the composite. */
 void Service_Read(UA_Server *server, UA_Session *session,
                   const UA_ReadRequest *request,
                   UA_ReadResponse *response);
 
-/* Used to write one or more Attributes of one or more Nodes. For constructed
- * Attribute values whose elements are indexed, such as an array, this Service
- * allows Clients to write the entire set of indexed values as a composite, to
- * write individual elements or to write ranges of elements of the composite. */
+/**
+ * Write Service
+ * ^^^^^^^^^^^^^
+ * Used to write attributes of nodes. For constructed attribute values whose
+ * elements are indexed, such as an array, this Service allows Clients to write
+ * the entire set of indexed values as a composite, to write individual elements
+ * or to write ranges of elements of the composite. */
 void Service_Write(UA_Server *server, UA_Session *session,
                    const UA_WriteRequest *request,
                    UA_WriteResponse *response);
 
-/* Not Implemented: Service_HistoryRead */
-/* Not Implemented: Service_HistoryUpdate */
+/**
+ * HistoryRead Service
+ * ^^^^^^^^^^^^^^^^^^^
+ * Used to read historical values or Events of one or more Nodes. Servers may
+ * make historical values available to Clients using this Service, although the
+ * historical values themselves are not visible in the AddressSpace. */
+/* Not Implemented */
+
+/**
+ * HistoryUpdate Service
+ * ^^^^^^^^^^^^^^^^^^^^^
+ * Used to update historical values or Events of one or more Nodes. Several
+ * request parameters indicate how the Server is to update the historical value
+ * or Event. Valid actions are Insert, Replace or Delete. */
+/* Not Implemented */
 
 /**
  * .. _method-services:
@@ -235,11 +331,13 @@ void Service_Write(UA_Server *server, UA_Session *session,
  * ------------------
  * The Method Service Set defines the means to invoke methods. A method shall be
  * a component of an Object. See the section on :ref:`MethodNodes <methodnode>`
- * for more information. */
-/* Used to call (invoke) a list of Methods. Each method call is invoked within
- * the context of an existing Session. If the Session is terminated, the results
- * of the method's execution cannot be returned to the Client and are
- * discarded. */
+ * for more information.
+ *
+ * Call Service
+ * ^^^^^^^^^^^^
+ * Used to call (invoke) a methods. Each method call is invoked within the
+ * context of an existing Session. If the Session is terminated, the results of
+ * the method's execution cannot be returned to the Client and are discarded. */
 void Service_Call(UA_Server *server, UA_Session *session,
                   const UA_CallRequest *request,
                   UA_CallResponse *response);
@@ -249,8 +347,11 @@ void Service_Call(UA_Server *server, UA_Session *session,
  * -------------------------
  * Clients define MonitoredItems to subscribe to data and Events. Each
  * MonitoredItem identifies the item to be monitored and the Subscription to use
- * to send Notifications. The item to be monitored may be any Node Attribute. */
-/* Used to create and add one or more MonitoredItems to a Subscription. A
+ * to send Notifications. The item to be monitored may be any Node Attribute.
+ *
+ * CreateMonitoredItems Service
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * Used to create and add one or more MonitoredItems to a Subscription. A
  * MonitoredItem is deleted automatically by the Server when the Subscription is
  * deleted. Deleting a MonitoredItem causes its entire set of triggered item
  * links to be deleted, but has no effect on the MonitoredItems referenced by
@@ -259,46 +360,78 @@ void Service_CreateMonitoredItems(UA_Server *server, UA_Session *session,
                                   const UA_CreateMonitoredItemsRequest *request, 
                                   UA_CreateMonitoredItemsResponse *response);
 
-/* Used to remove one or more MonitoredItems of a Subscription. When a
+/**
+ * DeleteMonitoredItems Service
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * Used to remove one or more MonitoredItems of a Subscription. When a
  * MonitoredItem is deleted, its triggered item links are also deleted. */
 void Service_DeleteMonitoredItems(UA_Server *server, UA_Session *session,
                                   const UA_DeleteMonitoredItemsRequest *request,
                                   UA_DeleteMonitoredItemsResponse *response);
 
+/**
+ * ModifyMonitoredItems Service
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * Used to modify MonitoredItems of a Subscription. Changes to the MonitoredItem
+ * settings shall be applied immediately by the Server. They take effect as soon
+ * as practical but not later than twice the new revisedSamplingInterval.
+ *
+ * Illegal request values for parameters that can be revised do not generate
+ * errors. Instead the server will choose default values and indicate them in
+ * the corresponding revised parameter. */
 void Service_ModifyMonitoredItems(UA_Server *server, UA_Session *session,
                                   const UA_ModifyMonitoredItemsRequest *request,
                                   UA_ModifyMonitoredItemsResponse *response);
 
-/* Used to set the monitoring mode for one or more MonitoredItems of a
-   Subscription. */
+/**
+ * SetMonitoringMode Service
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^
+ * Used to set the monitoring mode for one or more MonitoredItems of a
+ * Subscription. */
 void Service_SetMonitoringMode(UA_Server *server, UA_Session *session,
                                const UA_SetMonitoringModeRequest *request,
                                UA_SetMonitoringModeResponse *response);
 
-/* Not Implemented: Service_SetTriggering */
+/**
+ * SetTriggering Service
+ * ^^^^^^^^^^^^^^^^^^^^^
+ * Used to create and delete triggering links for a triggering item. */
+/* Not Implemented */
 
 /**
  * Subscription Service Set
  * ------------------------
- * Subscriptions are used to report Notifications to the Client. */
-/* Used to create a Subscription. Subscriptions monitor a set of MonitoredItems
+ * Subscriptions are used to report Notifications to the Client.
+ *
+ * CreateSubscription Service
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * Used to create a Subscription. Subscriptions monitor a set of MonitoredItems
  * for Notifications and return them to the Client in response to Publish
  * requests. */
 void Service_CreateSubscription(UA_Server *server, UA_Session *session,
                                 const UA_CreateSubscriptionRequest *request,
                                 UA_CreateSubscriptionResponse *response);
 
-/* Used to modify a Subscription. */
+/**
+ * ModifySubscription Service
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * Used to modify a Subscription. */
 void Service_ModifySubscription(UA_Server *server, UA_Session *session,
                                 const UA_ModifySubscriptionRequest *request,
                                 UA_ModifySubscriptionResponse *response);
 
-/* Used to enable sending of Notifications on one or more Subscriptions. */
+/**
+ * SetPublishingMode Service
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^
+ * Used to enable sending of Notifications on one or more Subscriptions. */
 void Service_SetPublishingMode(UA_Server *server, UA_Session *session,
                                const UA_SetPublishingModeRequest *request,
                                UA_SetPublishingModeResponse *response);
 
-/* Used for two purposes. First, it is used to acknowledge the receipt of
+/**
+ * Publish Service
+ * ^^^^^^^^^^^^^^^
+ * Used for two purposes. First, it is used to acknowledge the receipt of
  * NotificationMessages for one or more Subscriptions. Second, it is used to
  * request the Server to return a NotificationMessage or a keep-alive
  * Message.
@@ -309,19 +442,33 @@ void Service_SetPublishingMode(UA_Server *server, UA_Session *session,
 void Service_Publish(UA_Server *server, UA_Session *session,
                      const UA_PublishRequest *request, UA_UInt32 requestId);
 
-/* Requests the Subscription to republish a NotificationMessage from its
+/**
+ * Republish Service
+ * ^^^^^^^^^^^^^^^^^
+ * Requests the Subscription to republish a NotificationMessage from its
  * retransmission queue. */
 void Service_Republish(UA_Server *server, UA_Session *session,
                        const UA_RepublishRequest *request,
                        UA_RepublishResponse *response);
 
-/* Invoked to delete one or more Subscriptions that belong to the Client's
+/**
+ * DeleteSubscriptions Service
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * Invoked to delete one or more Subscriptions that belong to the Client's
  * Session. */
 void Service_DeleteSubscriptions(UA_Server *server, UA_Session *session,
                                  const UA_DeleteSubscriptionsRequest *request,
                                  UA_DeleteSubscriptionsResponse *response);
 
-/* Not Implemented: Service_TransferSubscription */
+/**
+ * TransferSubscription Service
+ * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * Used to transfer a Subscription and its MonitoredItems from one Session to
+ * another. For example, a Client may need to reopen a Session and then transfer
+ * its Subscriptions to that Session. It may also be used by one Client to take
+ * over a Subscription from another Client by transferring the Subscription to
+ * its Session. */
+/* Not Implemented */
 
 #ifdef __cplusplus
 } // extern "C"