resource-encapsulation: Updated doxygen comments
[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 provide APIs to discover the Resource in the network
25  *
26  */
27
28 #ifndef RCSDISCOVERYMANAGER_H
29 #define RCSDISCOVERYMANAGER_H
30
31 #include <memory>
32 #include <functional>
33
34 namespace OIC
35 {
36     namespace Service
37     {
38         class RCSRemoteResourceObject;
39         class RCSAddress;
40
41         /**
42          * This class contains the resource discovery methods.
43          *
44          * @see RCSRemoteResourceObject
45          */
46         class RCSDiscoveryManager
47         {
48             public:
49
50                 /**
51                  * Typedef for callback of discoverResource APIs
52                  *
53                  * @see discoverResource
54                  */
55                 typedef std::function< void(std::shared_ptr< RCSRemoteResourceObject >) >
56                                        ResourceDiscoveredCallback;
57
58                 /**
59                  * @return Returns RCSDiscoveryManager instance.
60                  *
61                  */
62                 static RCSDiscoveryManager* getInstance();
63
64                 /**
65                  * API for discovering the resource of Interest, regardless of URI and resource type
66                  *
67                  * @param address A RCSAddress object
68                  * @param cb A callback to obtain discovered resource
69                  *
70                  * @throws InvalidParameterException If cb is empty.
71                  *
72                  * @note The callback will be invoked in an internal thread.
73                  *
74                  * @see RCSAddress
75                  *
76                  */
77                 void discoverResource(const RCSAddress& address, ResourceDiscoveredCallback cb);
78
79                 /**
80                  * API for discovering the resource of Interest, regardless of resource type
81                  *
82                  * @param address A RCSAddress object
83                  * @param relativeURI The relative uri of resource to be searched
84                  * @param cb A callback to obtain discovered resource
85                  *
86                  * @throws InvalidParameterException If cb is empty.
87                  *
88                  * @note The callback will be invoked in an internal thread.
89                  *
90                  * @see RCSAddress
91                  *
92                  */
93                 void discoverResource(const RCSAddress& address, const std::string& relativeURI,
94                                       ResourceDiscoveredCallback cb);
95
96                 /**
97                  * API for discovering the resource of Interest by Resource type.
98                  *
99                  * @param address A RCSAddress object
100                  * @param resourceType Ressource Type
101                  * @param cb A callback to obtain discovered resource
102                  *
103                  * @throws InvalidParameterException If cb is empty.
104                  *
105                  * @note The callback will be invoked in an internal thread.
106                  *
107                  * @see RCSAddress
108                  *
109                  */
110                 void discoverResourceByType(const RCSAddress& address, const std::string& resourceType,
111                                             ResourceDiscoveredCallback cb);
112
113                 /**
114                  * API for discovering the resource of Interest by Resource type with provided relativeURI
115                  *
116                  * @param address A RCSAddress object
117                  * @param relativeURI The relative uri of resource to be searched
118                  * @param resourceType Ressource Type
119                  * @param cb A callback to obtain discovered resource
120                  *
121                  * @throws InvalidParameterException If cb is empty.
122                  *
123                  * @note The callback will be invoked in an internal thread.
124                  *
125                  * @see RCSAddress
126                  *
127                  */
128                 void discoverResourceByType(const RCSAddress& address, const std::string& relativeURI,
129                                             const std::string& resourceType,
130                                             ResourceDiscoveredCallback cb);
131
132             private:
133
134                 RCSDiscoveryManager() = default;
135                 ~RCSDiscoveryManager() = default;
136         };
137     }
138 }
139 #endif // RCSDISCOVERYMANAGER_H