Add API explained comments for RCSDiscoveryManager and RCSDiscoveryManagerImpl
authorChaJiwon <jw_wonny.cha@samsung.com>
Thu, 24 Sep 2015 06:29:41 +0000 (15:29 +0900)
committerHabib Virji <habib.virji@samsung.com>
Thu, 24 Sep 2015 22:04:10 +0000 (22:04 +0000)
- Modify return type (void -> unique_ptr<DiscoveryTask>) in RCSDiscoveryManager
- Add new API in RCSDiscoveryManagerImpl

Need to be cherry picked master branch into 1.0.0-dev branch

Change-Id: I69c90a7448efa325941c2aef53ea4a252e2ab6c8
Signed-off-by: ChaJiwon <jw_wonny.cha@samsung.com>
Reviewed-on: https://gerrit.iotivity.org/gerrit/3021
Tested-by: jenkins-iotivity <jenkins-iotivity@opendaylight.org>
Reviewed-by: Hun-je Yeon <hunje.yeon@samsung.com>
Reviewed-by: Habib Virji <habib.virji@samsung.com>
service/resource-encapsulation/include/RCSDiscoveryManager.h [changed mode: 0755->0644]
service/resource-encapsulation/include/RCSDiscoveryManagerImpl.h [changed mode: 0755->0644]

old mode 100755 (executable)
new mode 100644 (file)
index b55daee..57537b9
@@ -21,7 +21,8 @@
 /**
  * @file
  *
- * This file contains the RCSDiscoveryManager class which provide APIs to discover the Resource in the network
+ * This file contains the RCSDiscoveryManager class which provides APIs to discover the
+ * Resource in the network
  *
  */
 
@@ -48,14 +49,30 @@ namespace OIC
         class RCSDiscoveryManager
         {
             public:
+
+            /**
+             * This class represents a discovery task.
+             *
+             * @note A discovery task will be automatically canceled when destroyed.
+             */
                 class DiscoveryTask
                 {
                     public:
 
+                        /**
+                         * Cancel the task for discovery request. If cancel is called in duplicate, the request is ignored.
+                         */
                         void cancel();
+
+                        /**
+                         * Return a boolean value whether the discovery request is canceled or not.
+                         */
                         bool isCanceled();
+
                         ~DiscoveryTask();
 
+                    public:
+
                         DiscoveryTask(const DiscoveryTask&) = delete;
                         DiscoveryTask(DiscoveryTask&&) = delete;
                         DiscoveryTask& operator = (const DiscoveryTask&) const = delete;
@@ -80,37 +97,39 @@ namespace OIC
                                        ResourceDiscoveredCallback;
 
                 /**
-                 * Returns RCSDiscoveryManager instance.
+                 * @return RCSDiscoveryManager instance.
                  *
                  */
                 static RCSDiscoveryManager* getInstance();
 
                 /**
-                 * API for discovering the resource of Interest, regardless of URI and resource type
+                 * Discovering the resource of interest, regardless of uri and resource type.
+                 * Find resource matching request periodically until returned resource is disappeared or destroyed.
+                 *
+                 * @return Returned object must be received.
                  *
-                 * @param address A RCSAddress object
-                 * @param cb A callback to obtain discovered resource
+                 * @param address         A RCSAddress object
+                 * @param cb              A callback to obtain discovered resource
                  *
                  * @throws InvalidParameterException If cb is empty.
-                 * @throws PlatformException If the operation failed.
                  *
                  * @note The callback will be invoked in an internal thread.
                  *
-                 * @see RCSAddress
-                 *
                  */
                 std::unique_ptr<DiscoveryTask> discoverResource(const RCSAddress& address,
                         ResourceDiscoveredCallback cb);
 
                 /**
-                 * API for discovering the resource of Interest, regardless of resource type
+                 * Discovering the resource of Interest, regardless of resource type.
+                 * Find resource matching request periodically until returned resource is disappeared or destroyed.
+                 *
+                 * @return Returned object must be received.
                  *
-                 * @param address A RCSAddress object
-                 * @param relativeURI The relative uri of resource to be searched
-                 * @param cb A callback to obtain discovered resource
+                 * @param address          A RCSAddress object
+                 * @param relativeURI      The relative uri of resource to be searched
+                 * @param cb               A callback to obtain discovered resource
                  *
                  * @throws InvalidParameterException If cb is empty.
-                 * @throws PlatformException If the operation failed.
                  *
                  * @note The callback will be invoked in an internal thread.
                  *
@@ -121,14 +140,16 @@ namespace OIC
                         const std::string& relativeURI, ResourceDiscoveredCallback cb);
 
                 /**
-                 * API for discovering the resource of Interest by Resource type.
+                 * Discovering the resource of Interest by Resource type.
+                 * Find resource matching request periodically until returned resource is disappeared or destroyed.
                  *
-                 * @param address A RCSAddress object
-                 * @param resourceType Ressource Type
-                 * @param cb A callback to obtain discovered resource
+                 * @return Returned object must be received.
+                 *
+                 * @param address          A RCSAddress object
+                 * @param resourceType     Resource Type
+                 * @param cb               A callback to obtain discovered resource
                  *
                  * @throws InvalidParameterException If cb is empty.
-                 * @throws PlatformException If the operation failed.
                  *
                  * @note The callback will be invoked in an internal thread.
                  *
@@ -139,15 +160,17 @@ namespace OIC
                         const std::string& resourceType, ResourceDiscoveredCallback cb);
 
                 /**
-                 * API for discovering the resource of Interest by Resource type with provided relativeURI
+                 * Discovering the resource of Interest by Resource type with provided relativeURI.
+                 * Find resource matching request periodically until returned resource is disappeared or destroyed.
+                 *
+                 * @return Returned object must be received.
                  *
-                 * @param address A RCSAddress object
-                 * @param relativeURI The relative uri of resource to be searched
-                 * @param resourceType Ressource Type
-                 * @param cb A callback to obtain discovered resource
+                 * @param address          A RCSAddress object
+                 * @param relativeURI      The relative uri of resource to be searched
+                 * @param resourceType     Resource Type
+                 * @param cb               A callback to obtain discovered resource
                  *
                  * @throws InvalidParameterException If cb is empty.
-                 * @throws PlatformException If the operation failed.
                  *
                  * @note The callback will be invoked in an internal thread.
                  *
old mode 100755 (executable)
new mode 100644 (file)
index 5790040..391544a
@@ -21,7 +21,8 @@
 /**
  * @file
  *
- * This file contains the RCSActiveDiscoveryManager class which provide APIs to discover the Resource in the network
+ * This file contains the RCSActiveDiscoveryManagerImpl class which provide APIs to discover the Resource in the network
+ * and discovery requests management.
  *
  */
 
@@ -50,6 +51,12 @@ namespace OIC
         class RCSDiscoveryManager;
         class PrimitiveResource;
         class RCSAddress;
+
+        /**
+         * The class contains discovery request information
+         *
+         * @see RCSDiscoveryManager
+         */
         class DiscoverRequestInfo
         {
             public:
@@ -63,19 +70,40 @@ namespace OIC
                 RCSDiscoveryManager::ResourceDiscoveredCallback m_discoverCB;
         };
 
+        /**
+         * The class contains the resource discovery and management requests methods.
+         */
         class RCSDiscoveryManagerImpl
         {
             static unsigned int s_uniqueId;
 
             public:
 
+                /*
+                 * Typedef for callback of requesting presence API
+                 *
+                 * @see requestMulticastPresence
+                 */
                 typedef std::function<void(OCStackResult, const unsigned int,
                         const std::string&)> PresenceCallback;
+
+                /*
+                 * Typedef for discovery request ID
+                 *
+                 * @note This is generated for each discovery request
+                 */
                 typedef unsigned int ID;
+
+                /*
+                 * Typedef for callback of discoverResource API
+                 */
                 typedef std::function<void(std::shared_ptr< PrimitiveResource >, ID)> FindCallback;
 
             public:
 
+                /*
+                 * @return Returns RCSDiscoveryManagerImpl instance.
+                 */
                 static RCSDiscoveryManagerImpl* getInstance();
 
                 DiscoverRequestInfo m_discoveryItem;
@@ -92,18 +120,81 @@ namespace OIC
 
             public:
 
+                /**
+                 * Starting discovery of resource
+                 *
+                 * @return DiscoverTask pointer
+                 *
+                 * @param address        A RCSAddress object
+                 * @param relativeURI    The relative uri of resource to be searched
+                 * @param resourceType   Resource Type
+                 * @param cb             A callback to obtain discovered resource
+                 *
+                 * @throws InvalidParameterException If cb is empty
+                 *
+                 * @note If relativeURI is empty, will be discovered after be changed into "OC_RSRVD_WELL_KNOWN_URI"
+                 * @note If resourceType is empty, will be discovered all resources in network
+                 *
+                 * @see RCSAddress
+                 * @see RCSDiscoveryManager
+                 */
                 std::unique_ptr<RCSDiscoveryManager::DiscoveryTask> startDiscovery(const RCSAddress& address,
                         const std::string& relativeURI,const std::string& resourceType,
                         RCSDiscoveryManager::ResourceDiscoveredCallback cb);
 
             private:
 
+                /**
+                 * Requesting presence by multicast
+                 */
                 void requestMulticastPresence();
+
+                /**
+                 * Initializing callback of presence and polling
+                 */
                 void initializedDiscoveryEnvironment();
+
+                /**
+                 * Checking duplicated callback and invoking callback when resource is discovered
+                 *
+                 * @param resource     A pointer of discovered resource
+                 * @param discoverID   The ID of discovery request
+                 *
+                 * @see PrimitiveResource
+                 */
                 void findCallback(std::shared_ptr< PrimitiveResource > resource, ID discoverID);
+
+                /**
+                 * Discovering resource on all requests and posting timer when timer is expired
+                 */
                 void pollingCallback(unsigned int /*msg*/);
+
+                /**
+                 * Discovering resource on all requests when supporting presence function resource enter into network
+                 *
+                 * @param ret          Not used in this class
+                 * @param seq          Not used in this class
+                 * @param address      A address of supporting presence function resource
+                 */
                 void presenceCallback(OCStackResult, const unsigned int,const std::string&);
-                bool isDuplicatedCallback(std::shared_ptr<PrimitiveResource> resource,ID discoverID);
+
+                /**
+                 * Checking duplicated callback
+                 *
+                 * @return The callback is duplicated or not
+                 *
+                 * @param resource A pointer of discovered resource
+                 * @param discoverID The ID of discovery request
+                 *
+                 * @see PrimitiveResource
+                 */
+                bool isDuplicatedCallback(std::shared_ptr<PrimitiveResource> resource, ID discoverID);
+
+                /**
+                 * Creating unique id
+                 *
+                 * @return Returns the id
+                 */
                 ID createId();
 
             private: