Merge branch 'master' into cloud-interface
[iotivity.git] / 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