Update API description

API description is updated including the usage of subControllability.

Change-Id: I141d47d2c655b29531b9251dbbf50ecdb8a1c1de
Signed-off-by: ch79.cho <ch79.cho@samsung.com>
Reviewed-on: https://gerrit.iotivity.org/gerrit/12251
Tested-by: jenkins-iotivity <jenkins-iotivity@opendaylight.org>
Reviewed-by: Uze Choi <uzchoi@samsung.com>
(cherry picked from commit 3a5bc429cca37aa1eb967d249ae39addd4adf491)
Reviewed-on: https://gerrit.iotivity.org/gerrit/12463

diff --git a/service/notification/include/NSProviderInterface.h b/service/notification/include/NSProviderInterface.h
index 6958589..305fec6 100644 (file)
--- a/service/notification/include/NSProviderInterface.h
+++ b/service/notification/include/NSProviderInterface.h
@@ -37,14 +37,14 @@ extern "C"
 #include <stdint.h>\r
 \r
 /**\r
- * Provider uses this callback function to receive subscription request of consumer\r
+ * Invoked when a consumer requests subscription.\r
  * @param[in] consumer        Consumer who subscribes the resource\r
  */\r
 typedef void (*NSSubscribeRequestCallback)(NSConsumer *);\r
 \r
 /**\r
- * Provider use this callback function to receive the status of the message\r
- * synchronization\r
+ * Invoked when synchronization data which has notification message \r
+ * read/deleted event from consumer is received.\r
  * @param[in] sync        Synchronization information of the notification message\r
  */\r
 typedef void (*NSProviderSyncInfoCallback)(NSSyncInfo *);\r
@@ -59,8 +59,8 @@ typedef struct
     /* Invoked when the synchronization data, read and deleted, is sent by consumer is received */\r
     NSProviderSyncInfoCallback syncInfoCallback;\r
     /* Set the policy for notification servcie refering to following\r
-     * if policy is true, provider decides to allow or deny for all the subscribing consumers.\r
-     * Otherwise(policy is false) consumer decides to request subscription to discovered providers.\r
+     * if true, the controllability such as subscription request and consumer topic selection\r
+     * is owned by provider user. Otherwise(policy is false), consumer user has the same.\r
      */\r
     bool subControllability;\r
     /* User Information */\r
@@ -71,36 +71,36 @@ typedef struct
 } NSProviderConfig;\r
 \r
 /**\r
- * Initialize notification service for provider service\r
+ * Initialize notification service for provider\r
  * @param[in]  config   Refer to NSProviderConfig\r
- * @return ::NS_OK or result code of NSResult\r
+ * @return ::NS_OK if the action is requested succesfully\r
  */\r
 NSResult NSStartProvider(NSProviderConfig config);\r
 \r
 /**\r
  * Terminate notification service for provider\r
- * @return ::NS_OK or result code of NSResult\r
+ * @return ::NS_OK if the action is requested succesfully\r
  */\r
 NSResult NSStopProvider();\r
 \r
 /**\r
- * Request to publish resource to cloud server\r
+ * Request to publish resource using remote relay server\r
  * @param[in]  server address combined with IP address and port number using delimiter :\r
- * @return ::NS_OK or result code of NSResult\r
+ * @return ::NS_OK if the action is requested succesfully or NS_FAIL if wrong parameter is set.\r
  */\r
 NSResult NSProviderEnableRemoteService(char * serverAddress);\r
 \r
 /**\r
- * Request to cancel remote service using cloud server\r
+ * Request to terminate remote service from relay server\r
  * @param[in]  server address combined with IP address and port number using delimiter :\r
- * @return ::NS_OK or result code of NSResult\r
+ * @return ::NS_OK if the action is requested succesfully or NS_FAIL if wrong parameter is set.\r
  */\r
 NSResult NSProviderDisableRemoteService(char * serverAddress);\r
 \r
 /**\r
  * Send notification message to all subscribers\r
  * @param[in]  message  Notification message including id, title, contentText\r
- * @return ::NS_OK or result code of NSResult\r
+ * @return ::NS_OK if the action is requested succesfully or NS_FAIL if wrong parameter is set.\r
  */\r
 NSResult NSSendMessage(NSMessage * msg);\r
 \r
@@ -108,7 +108,7 @@ NSResult NSSendMessage(NSMessage * msg);
  * Send acceptance to consumer who subscribes the resource of notification message\r
  * @param[in]  consumer  Consumer who subscribes the resource\r
  * @param[in]  accepted  the result of acceptance; Allow or Deny\r
- * @return ::NS_OK or result code of NSResult\r
+ * @return ::NS_OK if the action is requested succesfully or NS_FAIL if subContollability is false.\r
  */\r
 NSResult NSAcceptSubscription(const char * consumerId, bool accepted);\r
 \r
@@ -122,14 +122,14 @@ NSResult NSAcceptSubscription(const char * consumerId, bool accepted);
 // NSResult NSGetConsumerList(uint8_t *list, uint32_t size);\r
 \r
 /**\r
- * Send read-check to provider in order to synchronize notification status with other consumers\r
+ * Send synchronizad state of notificaion message to consumers\r
  * @param[in]  message  Notification message to synchronize the status\r
- * @return ::NS_OK or result code of NSResult\r
+ * @return ::NS_OK if the action is requested succesfully or NS_FAIL if wrong parameter is set.\r
  */\r
 NSResult NSProviderSendSyncInfo(uint64_t messageId, NSSyncType type);\r
 \r
 /**\r
- * Initialize NSMessage struct, our service set message id and provider(device) id\r
+ * Initialize NSMessage struct, provider service sets generated message id and provider(device) id\r
  * @return ::NSMessage *\r
  */\r
 NSMessage * NSCreateMessage();\r
@@ -137,14 +137,14 @@ NSMessage * NSCreateMessage();
 /**\r
  * Add topic to topic list which is located in provider service storage\r
  * @param[in]  topicName Topic name to add\r
- * @return ::NS_OK or result code of NSResult\r
+ * @return ::NS_OK if the action is requested succesfully or NS_FAIL if wrong parameter is set.\r
  */\r
 NSResult NSProviderRegisterTopic(const char * topicName);\r
 \r
 /**\r
  * Delete topic from topic list\r
  * @param[in]  topicName Topic name to delete\r
- * @return ::NS_OK or result code of NSResult\r
+ * @return ::NS_OK if the action is requested succesfully or NS_FAIL if wrong parameter is set.\r
  */\r
 NSResult NSProviderUnregisterTopic(const char * topicName);\r
 \r
@@ -152,7 +152,7 @@ NSResult NSProviderUnregisterTopic(const char * topicName);
  * Select a topic name for a consumer\r
  * @param[in]  consumerId  consumer id for which the user on provider selects a topic\r
  * @param[in]  topicName Topic name to select\r
- * @return ::NS_OK or result code of NSResult\r
+ * @return ::NS_OK if the action is requested succesfully or NS_FAIL if subContollability is false\r
  */\r
 NSResult NSProviderSetConsumerTopic(const char * consumerId, const char * topicName);\r
 \r
@@ -160,7 +160,7 @@ NSResult NSProviderSetConsumerTopic(const char * consumerId, const char * topicN
  * Unselect a topic from the topic list for consumer\r
  * @param[in]  consumerId  consumer id for which the user on provider unselects a topic\r
  * @param[in]  topicName Topic name to unselect\r
- * @return ::NS_OK or result code of NSResult\r
+ * @return ::NS_OK if the action is requested succesfully or NS_FAIL if subContollability is false\r
  */\r
 NSResult NSProviderUnsetConsumerTopic(const char * consumerId, const char * topicName);\r
 \r