improve documentation of the services

src/server/ua_services.h

@@ -16,9 +16,9 @@ extern "C" {
  * Services
  * ========
  * The services defined in the OPC UA standard. */
-/* All services take as input the server, the current session and pointers to
-   the request and response. The status code is returned as part of the
-   response. */
+/* Most services take as input the server, the current session and pointers to
+   the request and response. The possible error codes are returned as part of
+   the response. */
 typedef void (*UA_Service)(UA_Server*, UA_Session*, const void*, void*);
 
 /**
@@ -103,7 +103,7 @@ void Service_AddNodes_single(UA_Server *server, UA_Session *session,
                              UA_InstantiationCallback *instantiationCallback);
 
 /* Add an existing node. The node is assumed to be "finished", i.e. no
-   instantiation from inheritance is necessary */
+ * instantiation from inheritance is necessary */
 void Service_AddNodes_existing(UA_Server *server, UA_Session *session, UA_Node *node,
                                const UA_NodeId *parentNodeId, const UA_NodeId *referenceTypeId,
                                UA_AddNodesResult *result);
@@ -122,7 +122,8 @@ void Service_DeleteNodes(UA_Server *server, UA_Session *session,
                          UA_DeleteNodesResponse *response);
 
 UA_StatusCode Service_DeleteNodes_single(UA_Server *server, UA_Session *session,
-                                         const UA_NodeId *nodeId, UA_Boolean deleteReferences);
+                                         const UA_NodeId *nodeId,
+                                         UA_Boolean deleteReferences);
 
 /* Used to delete one or more References of a Node. */
 void Service_DeleteReferences(UA_Server *server, UA_Session *session,
@@ -169,12 +170,18 @@ void Service_TranslateBrowsePathsToNodeIds(UA_Server *server, UA_Session *sessio
                                            UA_TranslateBrowsePathsToNodeIdsResponse *response);
 
 void Service_TranslateBrowsePathsToNodeIds_single(UA_Server *server, UA_Session *session,
-                                                  const UA_BrowsePath *path, UA_BrowsePathResult *result);
+                                                  const UA_BrowsePath *path,
+                                                  UA_BrowsePathResult *result);
 
+/* 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
+ * RegisterNodes service. */
 void Service_UnregisterNodes(UA_Server *server, UA_Session *session,
                              const UA_UnregisterNodesRequest *request,
                              UA_UnregisterNodesResponse *response);
@@ -209,8 +216,6 @@ void Service_Read_single(UA_Server *server, UA_Session *session,
                          UA_TimestampsToReturn timestamps,
                          const UA_ReadValueId *id, UA_DataValue *v);
 
-/* Not Implemented: Service_HistoryRead */
-
 /* 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
@@ -219,11 +224,10 @@ void Service_Write(UA_Server *server, UA_Session *session,
                    const UA_WriteRequest *request,
                    UA_WriteResponse *response);
 
-/* Single attribute writes are exposed to the userspace. The wvalue may be
-    destroyed (deleteMembers) */
 UA_StatusCode Service_Write_single(UA_Server *server, UA_Session *session,
                                    const UA_WriteValue *wvalue);
 
+/* Not Implemented: Service_HistoryRead */
 /* Not Implemented: Service_HistoryUpdate */
 
 /**
@@ -232,6 +236,10 @@ UA_StatusCode Service_Write_single(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. */
 #ifdef UA_ENABLE_METHODCALLS
+/* 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. */
 void Service_Call(UA_Server *server, UA_Session *session,
                   const UA_CallRequest *request,
                   UA_CallResponse *response);
@@ -248,6 +256,7 @@ void Service_Call_single(UA_Server *server, UA_Session *session,
  * 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. */
 #ifdef UA_ENABLE_SUBSCRIPTIONS
+
 /* 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
@@ -257,6 +266,8 @@ 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
+ * 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);
@@ -264,6 +275,7 @@ void Service_DeleteMonitoredItems(UA_Server *server, UA_Session *session,
 /* Not Implemented: Service_ModifyMonitoredItems */
 /* Not Implemented: Service_SetMonitoringMode */
 /* Not Implemented: Service_SetTriggering */
+
 #endif
                                       
 /**
@@ -271,27 +283,45 @@ void Service_DeleteMonitoredItems(UA_Server *server, UA_Session *session,
  * ------------------------
  * Subscriptions are used to report Notifications to the Client. */
 #ifdef UA_ENABLE_SUBSCRIPTIONS
+
+/* 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. */
 void Service_ModifySubscription(UA_Server *server, UA_Session *session,
                                 const UA_ModifySubscriptionRequest *request,
                                 UA_ModifySubscriptionResponse *response);
 
-void Service_DeleteSubscriptions(UA_Server *server, UA_Session *session,
-                                 const UA_DeleteSubscriptionsRequest *request,
-                                 UA_DeleteSubscriptionsResponse *response);
-                                     
+/* 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.
+ *
+ * Note that the service signature is an exception and does not contain a
+ * pointer to a PublishResponse. That is because the service queues up publish
+ * requests internally and sends responses asynchronously based on timeouts. */
 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
+ * 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
+ * Session. */
+void Service_DeleteSubscriptions(UA_Server *server, UA_Session *session,
+                                 const UA_DeleteSubscriptionsRequest *request,
+                                 UA_DeleteSubscriptionsResponse *response);
+
 /* Not Implemented: Service_SetPublishingMode */
 /* Not Implemented: Service_TransferSubscription */
+
 #endif
 
 #ifdef __cplusplus