From 40309df462cfde1717a467bbda6cb77fa6de6adb Mon Sep 17 00:00:00 2001 From: ChaJiwon Date: Thu, 24 Sep 2015 15:29:41 +0900 Subject: [PATCH] Add API explained comments for RCSDiscoveryManager and RCSDiscoveryManagerImpl - Modify return type (void -> unique_ptr) 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 Reviewed-on: https://gerrit.iotivity.org/gerrit/3021 Tested-by: jenkins-iotivity Reviewed-by: Hun-je Yeon Reviewed-by: Habib Virji --- .../include/RCSDiscoveryManager.h | 71 ++++++++++------ .../include/RCSDiscoveryManagerImpl.h | 95 +++++++++++++++++++++- 2 files changed, 140 insertions(+), 26 deletions(-) mode change 100755 => 100644 service/resource-encapsulation/include/RCSDiscoveryManager.h mode change 100755 => 100644 service/resource-encapsulation/include/RCSDiscoveryManagerImpl.h diff --git a/service/resource-encapsulation/include/RCSDiscoveryManager.h b/service/resource-encapsulation/include/RCSDiscoveryManager.h old mode 100755 new mode 100644 index b55daee..57537b9 --- a/service/resource-encapsulation/include/RCSDiscoveryManager.h +++ b/service/resource-encapsulation/include/RCSDiscoveryManager.h @@ -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 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. * diff --git a/service/resource-encapsulation/include/RCSDiscoveryManagerImpl.h b/service/resource-encapsulation/include/RCSDiscoveryManagerImpl.h old mode 100755 new mode 100644 index 5790040..391544a --- a/service/resource-encapsulation/include/RCSDiscoveryManagerImpl.h +++ b/service/resource-encapsulation/include/RCSDiscoveryManagerImpl.h @@ -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 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, 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 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 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 resource, ID discoverID); + + /** + * Creating unique id + * + * @return Returns the id + */ ID createId(); private: -- 2.7.4