Use `URI` all caps in documentation
[iotivity.git] / service / resource-encapsulation / include / RCSDiscoveryManager.h
old mode 100755 (executable)
new mode 100644 (file)
index bb9bd64..5aaba8d
 /**
  * @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
  *
  */
 
-#ifndef RCSDISCOVERYMANAGER_H
-#define RCSDISCOVERYMANAGER_H
+#ifndef RCS_DISCOVERYMANAGER_H_
+#define RCS_DISCOVERYMANAGER_H_
 
 #include <memory>
 #include <functional>
-
-#include "octypes.h"
+#include <vector>
 
 namespace OIC
 {
     namespace Service
     {
-        class RCSRemoteResourceObject;
         class RCSAddress;
-
-        class DiscoveryTask
-        {
-            public:
-
-                DiscoveryTask(unsigned int id) : m_id{ id } {};
-                void cancel();
-                bool isCanceled();
-                ~DiscoveryTask();
-            private:
-
-                unsigned int m_id;
-                friend class RCSDiscoveryManager;
-                friend class RCSDiscoveryManagerImpl;
-        };
-
+        class RCSRemoteResourceObject;
         /**
          * This class contains the resource discovery methods.
          *
@@ -62,97 +46,171 @@ namespace OIC
          */
         class RCSDiscoveryManager
         {
+        public:
+
+            /**
+             * This class represents a discovery task.
+             *
+             */
+            class DiscoveryTask
+            {
             public:
+                typedef std::unique_ptr< DiscoveryTask > Ptr;
 
-                /**
-                 * Typedef for callback of discoverResource APIs
-                 *
-                 * @see discoverResource
-                 */
-                typedef std::function< void(std::shared_ptr< RCSRemoteResourceObject >) >
-                                       ResourceDiscoveredCallback;
-
-                /**
-                 * @return Returns RCSDiscoveryManager instance.
-                 *
-                 */
-                static RCSDiscoveryManager* getInstance();
-
-                /**
-                 * API for discovering the resource of Interest, regardless of URI and resource type
-                 *
-                 * @param address A RCSAddress object
-                 * @param cb A callback to obtain discovered resource
-                 *
-                 * @throws InvalidParameterException If cb is empty.
-                 *
-                 * @note The callback will be invoked in an internal thread.
-                 *
-                 * @see RCSAddress
-                 *
-                 */
-                std::unique_ptr<DiscoveryTask> discoverResource(const RCSAddress& address,
-                        ResourceDiscoveredCallback cb);
+                ~DiscoveryTask();
 
-                /**
-                 * API for discovering the resource of Interest, regardless of resource type
-                 *
-                 * @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.
-                 *
-                 * @note The callback will be invoked in an internal thread.
-                 *
-                 * @see RCSAddress
-                 *
-                 */
-                std::unique_ptr<DiscoveryTask> discoverResource(const RCSAddress& address,
-                        const std::string& relativeURI, ResourceDiscoveredCallback cb);
+                DiscoveryTask(const DiscoveryTask&) = delete;
+                DiscoveryTask(DiscoveryTask&&) = delete;
+                DiscoveryTask& operator =(const DiscoveryTask&) const = delete;
+                DiscoveryTask& operator =(DiscoveryTask&&) const = delete;
 
                 /**
-                 * API for discovering the resource of Interest by Resource type.
-                 *
-                 * @param address A RCSAddress object
-                 * @param resourceType Ressource Type
-                 * @param cb A callback to obtain discovered resource
-                 *
-                 * @throws InvalidParameterException If cb is empty.
-                 *
-                 * @note The callback will be invoked in an internal thread.
-                 *
-                 * @see RCSAddress
-                 *
+                 * It cancels the task of discovery.
+                 * If it is already canceled, the operation is ignored.
                  */
-                std::unique_ptr<DiscoveryTask> discoverResourceByType(const RCSAddress& address,
-                        const std::string& resourceType, ResourceDiscoveredCallback cb);
+                void cancel();
 
                 /**
-                 * API for discovering the resource of Interest by Resource type with provided relativeURI
-                 *
-                 * @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
-                 *
-                 * @throws InvalidParameterException If cb is empty.
-                 *
-                 * @note The callback will be invoked in an internal thread.
-                 *
-                 * @see RCSAddress
-                 *
+                 * Returns whether the discovery request is canceled or not.
                  */
-                std::unique_ptr<DiscoveryTask>  discoverResourceByType(const RCSAddress& address,
-                        const std::string& relativeURI, const std::string& resourceType,
-                        ResourceDiscoveredCallback cb);
+                bool isCanceled();
 
             private:
+                explicit DiscoveryTask(unsigned int);
 
-                RCSDiscoveryManager() = default;
-                ~RCSDiscoveryManager()= default;;
+            private:
+                unsigned int m_id;
 
-                friend class DiscoveryTask;
+                friend class RCSDiscoveryManagerImpl;
+            };
+
+        public:
+
+            /**
+             * Typedef for callback of discoverResource APIs
+             *
+             * @see discoverResource
+             */
+            typedef std::function< void(std::shared_ptr< RCSRemoteResourceObject >) >
+                        ResourceDiscoveredCallback;
+
+            /**
+             * @return RCSDiscoveryManager instance.
+             *
+             */
+            static RCSDiscoveryManager* getInstance();
+
+            /**
+             * Discovers resources of interest, regardless of URI and resource type.
+             * It will consistently discover resources until the discovery task is canceled.
+             *
+             * @param address         A RCSAddress object
+             * @param cb              A callback to obtain discovered resource
+             *
+             * @throws InvalidParameterException If cb is empty.
+             *
+             * @note The callback will be invoked in an internal thread.
+             *
+             */
+            DiscoveryTask::Ptr discoverResource(const RCSAddress& address,
+                    ResourceDiscoveredCallback cb);
+
+            /**
+             * Discovers resources of interest, regardless of resource type.
+             * It will consistently discover resources until the discovery task is canceled.
+             *
+             * @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.
+             *
+             * @note The callback will be invoked in an internal thread.
+             *
+             */
+            DiscoveryTask::Ptr discoverResource(const RCSAddress& address,
+                    const std::string& relativeUri, ResourceDiscoveredCallback cb);
+
+            /**
+             * Discovers resources of interest by resource type.
+             * It will consistently discover resources until the discovery task is canceled.
+             *
+             * @param address          A RCSAddress object
+             * @param resourceType     Resource Type
+             * @param cb               A callback to obtain discovered resource
+             *
+             * @throws InvalidParameterException If cb is empty.
+             *
+             * @note The callback will be invoked in an internal thread.
+             *
+             */
+            DiscoveryTask::Ptr discoverResourceByType(const RCSAddress& address,
+                    const std::string& resourceType, ResourceDiscoveredCallback cb);
+
+            /**
+             * Discovers resources of interest by resource types.
+             * It will consistently discover resources until the discovery task is canceled.
+             *
+             * @param address          A RCSAddress object
+             * @param resourceTypes    List of Resource Types
+             * @param cb               A callback to obtain discovered resource
+             *
+             * @throws InvalidParameterException If cb is empty.
+             * @throws RCSBadRequestException If resourceTypes contain more than one element and
+             * any of them is empty.
+             *
+             * @note The callback will be invoked in an internal thread.
+             * @note If resourceTypes is empty, discovers resource by all resource types.
+             *
+             */
+            DiscoveryTask::Ptr discoverResourceByTypes(const RCSAddress& address,
+                    const std::vector< std::string >& resourceTypes,
+                    ResourceDiscoveredCallback cb);
+
+            /**
+             * Discovers resources of interest by a resource type with provided relativeUri.
+             * It will consistently discover resources until the discovery task is canceled.
+             *
+             * @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 The callback will be invoked in an internal thread.
+             *
+             */
+            DiscoveryTask::Ptr discoverResourceByType(const RCSAddress& address,
+                    const std::string& relativeUri, const std::string& resourceType,
+                    ResourceDiscoveredCallback cb);
+
+            /**
+             * Discovers resources of interest by resource types with provided relativeUri.
+             * It will consistently discover resources until the discovery task is canceled.
+             *
+             * @param address          A RCSAddress object
+             * @param relativeUri      The relative URI of resource to be searched
+             * @param resourceTypes     List of Resource Types
+             * @param cb               A callback to obtain discovered resource
+             *
+             * @throws InvalidParameterException If cb is empty.
+             * @throws RCSBadRequestException If resourceTypes contain more than one element and
+             * any of them is empty.
+             *
+             * @note The callback will be invoked in an internal thread.
+             * @note If resourceTypes is empty, discovers resource by all resource types.
+             *
+             */
+            DiscoveryTask::Ptr discoverResourceByTypes(const RCSAddress& address,
+                    const std::string& relativeUri,
+                    const std::vector< std::string >& resourceTypes,
+                    ResourceDiscoveredCallback cb);
+
+        private:
+
+            RCSDiscoveryManager() = default;
+            ~RCSDiscoveryManager() = default;
         };
     }
 }