Refactored 'RCSDiscoveryManager'
[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
35 namespace OIC
36 {
37     namespace Service
38     {
39         class RCSAddress;
40         class RCSRemoteResourceObject;
41         /**
42          * This class contains the resource discovery methods.
43          *
44          * @see RCSRemoteResourceObject
45          */
46         class RCSDiscoveryManager
47         {
48         public:
49
50             /**
51              * This class represents a discovery task.
52              *
53              */
54             class DiscoveryTask
55             {
56             public:
57                 typedef std::unique_ptr< DiscoveryTask > Ptr;
58
59                 ~DiscoveryTask() = default;
60
61                 DiscoveryTask(const DiscoveryTask&) = delete;
62                 DiscoveryTask(DiscoveryTask&&) = delete;
63                 DiscoveryTask& operator =(const DiscoveryTask&) const = delete;
64                 DiscoveryTask& operator =(DiscoveryTask&&) const = delete;
65
66                 /**
67                  * It is cancelling the task of discovery.
68                  * If it is already canceled, the operation is ignored.
69                  */
70                 void cancel();
71
72                 /**
73                  * Returns whether the discovery request is canceled or not.
74                  */
75                 bool isCanceled();
76
77             private:
78                 explicit DiscoveryTask(unsigned int);
79
80             private:
81                 unsigned int m_id;
82
83                 friend class RCSDiscoveryManagerImpl;
84             };
85
86         public:
87
88             /**
89              * Typedef for callback of discoverResource APIs
90              *
91              * @see discoverResource
92              */
93             typedef std::function< void(std::shared_ptr< RCSRemoteResourceObject >) >
94                         ResourceDiscoveredCallback;
95
96             /**
97              * @return RCSDiscoveryManager instance.
98              *
99              */
100             static RCSDiscoveryManager* getInstance();
101
102             /**
103              * Discovers resources of interest, regardless of uri and resource type.
104              * It is Consistently discovering resources until the discovery task is canceled.
105              *
106              * @param address         A RCSAddress object
107              * @param cb              A callback to obtain discovered resource
108              *
109              * @throws InvalidParameterException If cb is empty.
110              *
111              * @note The callback will be invoked in an internal thread.
112              *
113              */
114             DiscoveryTask::Ptr discoverResource(const RCSAddress& address,
115                     ResourceDiscoveredCallback cb);
116
117             /**
118              * Discovers resources of interest, regardless of resource type.
119              * It is Consistently discovering resources until the discovery task is canceled.
120              *
121              * @param address          A RCSAddress object
122              * @param relativeUri      The relative uri of resource to be searched
123              * @param cb               A callback to obtain discovered resource
124              *
125              * @throws InvalidParameterException If cb is empty.
126              *
127              * @note The callback will be invoked in an internal thread.
128              *
129              */
130             DiscoveryTask::Ptr discoverResource(const RCSAddress& address,
131                     const std::string& relativeUri, ResourceDiscoveredCallback cb);
132
133             /**
134              * Discovers resources of interest by resource type.
135              * It is Consistently discovering resources until the discovery task is canceled.
136              *
137              * @param address          A RCSAddress object
138              * @param resourceType     Resource Type
139              * @param cb               A callback to obtain discovered resource
140              *
141              * @throws InvalidParameterException If cb is empty.
142              *
143              * @note The callback will be invoked in an internal thread.
144              *
145              */
146             DiscoveryTask::Ptr discoverResourceByType(const RCSAddress& address,
147                     const std::string& resourceType, ResourceDiscoveredCallback cb);
148
149             /**
150              * Discovers resources of interest by resource type with provided relativeUri.
151              * It is Consistently discovering resources until the discovery task is canceled.
152              *
153              * @param address          A RCSAddress object
154              * @param relativeUri      The relative uri of resource to be searched
155              * @param resourceType     Resource Type
156              * @param cb               A callback to obtain discovered resource
157              *
158              * @throws InvalidParameterException If cb is empty.
159              *
160              * @note The callback will be invoked in an internal thread.
161              *
162              */
163             DiscoveryTask::Ptr discoverResourceByType(const RCSAddress& address,
164                     const std::string& relativeUri, const std::string& resourceType,
165                     ResourceDiscoveredCallback cb);
166
167         private:
168             RCSDiscoveryManager() = default;
169             ~RCSDiscoveryManager() = default;
170         };
171     }
172 }
173 #endif // RCSDISCOVERYMANAGER_H