service/resource-encapsulation/include/RCSDiscoveryManager.h

   1 //******************************************************************
   2 //
   3 // Copyright 2015 Samsung Electronics All Rights Reserved.
   4 //
   5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   6 //
   7 // Licensed under the Apache License, Version 2.0 (the "License");
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //      http://www.apache.org/licenses/LICENSE-2.0
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an "AS IS" BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  20
  21 /**
  22  * @file
  23  *
  24  * This file contains the RCSDiscoveryManager class which provides APIs to discover the
  25  * Resource in the network
  26  *
  27  */
  28
  29 #ifndef RCS_DISCOVERYMANAGER_H_
  30 #define RCS_DISCOVERYMANAGER_H_
  31
  32 #include <memory>
  33 #include <functional>
  34 #include <vector>
  35
  36 namespace OIC
  37 {
  38     namespace Service
  39     {
  40         class RCSAddress;
  41         class RCSRemoteResourceObject;
  42         /**
  43          * This class contains the resource discovery methods.
  44          *
  45          * @see RCSRemoteResourceObject
  46          */
  47         class RCSDiscoveryManager
  48         {
  49         public:
  50
  51             /**
  52              * This class represents a discovery task.
  53              *
  54              */
  55             class DiscoveryTask
  56             {
  57             public:
  58                 typedef std::unique_ptr< DiscoveryTask > Ptr;
  59
  60                 ~DiscoveryTask() = default;
  61
  62                 DiscoveryTask(const DiscoveryTask&) = delete;
  63                 DiscoveryTask(DiscoveryTask&&) = delete;
  64                 DiscoveryTask& operator =(const DiscoveryTask&) const = delete;
  65                 DiscoveryTask& operator =(DiscoveryTask&&) const = delete;
  66
  67                 /**
  68                  * It cancels the task of discovery.
  69                  * If it is already canceled, the operation is ignored.
  70                  */
  71                 void cancel();
  72
  73                 /**
  74                  * Returns whether the discovery request is canceled or not.
  75                  */
  76                 bool isCanceled();
  77
  78             private:
  79                 explicit DiscoveryTask(unsigned int);
  80
  81             private:
  82                 unsigned int m_id;
  83
  84                 friend class RCSDiscoveryManagerImpl;
  85             };
  86
  87         public:
  88
  89             /**
  90              * Typedef for callback of discoverResource APIs
  91              *
  92              * @see discoverResource
  93              */
  94             typedef std::function< void(std::shared_ptr< RCSRemoteResourceObject >) >
  95                         ResourceDiscoveredCallback;
  96
  97             /**
  98              * @return RCSDiscoveryManager instance.
  99              *
 100              */
 101             static RCSDiscoveryManager* getInstance();
 102
 103             /**
 104              * Discovers resources of interest, regardless of uri and resource type.
 105              * It is Consistently discovering resources until the discovery task is canceled.
 106              *
 107              * @param address         A RCSAddress object
 108              * @param cb              A callback to obtain discovered resource
 109              *
 110              * @throws InvalidParameterException If cb is empty.
 111              *
 112              * @note The callback will be invoked in an internal thread.
 113              *
 114              */
 115             DiscoveryTask::Ptr discoverResource(const RCSAddress& address,
 116                     ResourceDiscoveredCallback cb);
 117
 118             /**
 119              * Discovers resources of interest, regardless of resource type.
 120              * It is Consistently discovering resources until the discovery task is canceled.
 121              *
 122              * @param address          A RCSAddress object
 123              * @param relativeUri      The relative uri of resource to be searched
 124              * @param cb               A callback to obtain discovered resource
 125              *
 126              * @throws InvalidParameterException If cb is empty.
 127              *
 128              * @note The callback will be invoked in an internal thread.
 129              *
 130              */
 131             DiscoveryTask::Ptr discoverResource(const RCSAddress& address,
 132                     const std::string& relativeUri, ResourceDiscoveredCallback cb);
 133
 134             /**
 135              * Discovers resources of interest by resource type.
 136              * It is Consistently discovering resources until the discovery task is canceled.
 137              *
 138              * @param address          A RCSAddress object
 139              * @param resourceType     Resource Type
 140              * @param cb               A callback to obtain discovered resource
 141              *
 142              * @throws InvalidParameterException If cb is empty.
 143              *
 144              * @note The callback will be invoked in an internal thread.
 145              *
 146              */
 147             DiscoveryTask::Ptr discoverResourceByType(const RCSAddress& address,
 148                     const std::string& resourceType, ResourceDiscoveredCallback cb);
 149
 150             /**
 151              * Discovers resources of interest by resource type.
 152              * It is Consistently discovering resources until the discovery task is canceled.
 153              *
 154              * @param address          A RCSAddress object
 155              * @param resourceTypes    List of Resource Types
 156              * @param cb               A callback to obtain discovered resource
 157              *
 158              * @throws InvalidParameterException If cb is empty.
 159              * @throws InvalidParameterException If resourceType's size is than 2,
 160              * at least one of resource type is empty.
 161              *
 162              * @note The callback will be invoked in an internal thread.
 163              * @note If resourceTypes is empty, discovers resource by all resource types.
 164              *
 165              */
 166             DiscoveryTask::Ptr discoverResourceByTypes(const RCSAddress& address,
 167                     const std::vector< std::string >& resourceTypes,
 168                     ResourceDiscoveredCallback cb);
 169
 170             /**
 171              * Discovers resources of interest by resource types with provided relativeUri.
 172              * It is Consistently discovering resources until the discovery task is canceled.
 173              *
 174              * @param address          A RCSAddress object
 175              * @param relativeUri      The relative uri of resource to be searched
 176              * @param resourceType     Resource Type
 177              * @param cb               A callback to obtain discovered resource
 178              *
 179              * @throws InvalidParameterException If cb is empty.
 180              *
 181              * @note The callback will be invoked in an internal thread.
 182              *
 183              */
 184             DiscoveryTask::Ptr discoverResourceByType(const RCSAddress& address,
 185                     const std::string& relativeUri, const std::string& resourceType,
 186                     ResourceDiscoveredCallback cb);
 187
 188             /**
 189              * Discovers resources of interest by resource types with provided relativeUri.
 190              * It is Consistently discovering resources until the discovery task is canceled.
 191              *
 192              * @param address          A RCSAddress object
 193              * @param relativeUri      The relative uri of resource to be searched
 194              * @param resourceTypes     List of Resource Types
 195              * @param cb               A callback to obtain discovered resource
 196              *
 197              * @throws InvalidParameterException If cb is empty.
 198              * @throws InvalidParameterException If resourceType's size is than 2,
 199              * at least one of resource type is empty.
 200              *
 201              * @note The callback will be invoked in an internal thread.
 202              * @note If resourceTypes is empty, discovers resource by all resource types.
 203              *
 204              */
 205             DiscoveryTask::Ptr discoverResourceByTypes(const RCSAddress& address,
 206                     const std::string& relativeUri,
 207                     const std::vector< std::string >& resourceTypes,
 208                     ResourceDiscoveredCallback cb);
 209
 210         private:
 211
 212             RCSDiscoveryManager() = default;
 213             ~RCSDiscoveryManager() = default;
 214         };
 215     }
 216 }
 217 #endif // RCSDISCOVERYMANAGER_H