Corrected @file tags and restored 'Files' section.
[iotivity.git] / resource / include / OCResource.h
1 //******************************************************************
2 //
3 // Copyright 2014 Intel Mobile Communications GmbH 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 declaration of classes and its members related to
25  * Resource.
26  */
27
28 #ifndef __OCRESOURCE_H
29 #define __OCRESOURCE_H
30
31 #include <memory>
32 #include <random>
33 #include <algorithm>
34
35 #include <OCApi.h>
36 #include <ResourceInitException.h>
37 #include <IClientWrapper.h>
38 #include <InProcClientWrapper.h>
39 #include <OCRepresentation.h>
40
41 namespace OC
42 {
43     /**
44     *   @brief  OCResource represents an OC resource. A resource could be a light controller,
45     *           temperature sensor, smoke detector, etc. A resource comes with a well-defined
46     *           contract or interface onto which you can perform different operations, such as
47     *           turning on the light, getting the current temperature or subscribing for event
48     *           notifications from the smoke detector. A resource can be composed of one or
49     *           more resources.
50     */
51     class OCResource
52     {
53     friend class OCPlatform_impl;
54     friend class ListenOCContainer;
55     public:
56         typedef std::shared_ptr<OCResource> Ptr;
57
58         OCResource(OCResource&&) = default;
59         OCResource& operator=(OCResource&&) = default;
60
61         /**
62         * Virtual destructor
63         */
64         virtual ~OCResource(void);
65
66         /**
67         * Function to get the attributes of a resource.
68         * @param queryParametersMap map which can have the query parameter name and value
69         * @param attributeHandler handles callback
70         *        The callback function will be invoked with a map of attribute name and values.
71         *        The callback function will also have the result from this Get operation
72         *        This will have error codes
73         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
74         * NOTE: OCStackResult is defined in ocstack.h.
75         */
76         OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
77         /**
78         * Function to get the attributes of a resource.
79         * @param queryParametersMap map which can have the query parameter name and value
80         * @param attributeHandler handles callback
81         *        The callback function will be invoked with a map of attribute name and values.
82         *        The callback function will also have the result from this Get operation
83         *        This will have error codes
84         * @param QoS the quality of communication
85         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
86         * NOTE: OCStackResult is defined in ocstack.h.
87         */
88         OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
89                           QualityOfService QoS);
90
91         /**
92         * Function to get the attributes of a resource.
93         *
94         * @param resourceType resourceType of the resource operate on
95         * @param resourceInterface interface type of the resource to operate on
96         * @param queryParametersMap map which can have the query parameter name and value
97         * @param attributeHandler handles callback
98         *        The callback function will be invoked with a map of attribute name and values.
99         *        The callback function will be invoked with a list of URIs if 'get' is invoked on a
100         *        resource container (list will be empty if not a container)
101         *        The callback function will also have the result from this Get operation. This will
102         *        have error codes
103         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
104         * NOTE: OCStackResult is defined in ocstack.h.<br>
105         * <b>Example:</b><br>
106         * Consider resource "a/home" (with link interface and resource type as home) contains links
107         *  to "a/kitchen" and "a/room".
108         * Step 1: get("home", Link_Interface, &onGet)<br>
109         * Callback onGet will receive a) Empty attribute map because there are no attributes for
110         * a/home b) list with
111         * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
112         * operation<br>
113         * NOTE: A resource may contain single or multiple resource types. Also, a resource may
114         * contain single or multiple interfaces.<br>
115         * Currently, single GET request is allowed to do operate on single resource type or resource
116         * interface. In future, a single GET <br>
117         * can operate on multiple resource types and interfaces. <br>
118         * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned
119         * resources at a node.<br>
120         */
121         OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
122                         const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
123         /**
124         * Function to get the attributes of a resource.
125         *
126         * @param resourceType resourceType of the resource operate on
127         * @param resourceInterface interface type of the resource to operate on
128         * @param queryParametersMap map which can have the query parameter name and value
129         * @param attributeHandler handles callback
130         *        The callback function will be invoked with a map of attribute name and values.
131         *        The callback function will be invoked with a list of URIs if 'get' is invoked on a
132         *        resource container (list will be empty if not a container)
133         *        The callback function will also have the result from this Get operation. This will
134         *        have error codes
135         * @param QoS the quality of communication
136         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
137         * NOTE: OCStackResult is defined in ocstack.h.<br>
138         * <b>Example:</b><br>
139         * Consider resource "a/home" (with link interface and resource type as home) contains links
140         *  to "a/kitchen" and "a/room".
141         * Step 1: get("home", Link_Interface, &onGet)<br>
142         * Callback onGet will receive a) Empty attribute map because there are no attributes for
143         * a/home b) list with
144         * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
145         * operation<br>
146         * NOTE: A resource may contain single or multiple resource types. Also, a resource may
147         * contain single or multiple interfaces.<br>
148         * Currently, single GET request is allowed to do operate on single resource type or resource
149         * interface. In future, a single GET <br>
150         * can operate on multiple resource types and interfaces. <br>
151         * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned
152         * resources at a node.<br>
153         */
154         OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
155                         const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
156                         QualityOfService QoS);
157
158         /**
159         * Function to set the representation of a resource (via PUT)
160         * @param representation which can either have all the attribute names and values
161                  (which will represent entire state of the resource) or a
162         *        set of attribute names and values which needs to be modified
163         *        The callback function will be invoked with a map of attribute name and values.
164         *        The callback function will also have the result from this Put operation
165         *        This will have error codes
166         * @param queryParametersMap map which can have the query parameter name and value
167         * @param attributeHandler attribute handler
168         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
169         * NOTE: OCStackResult is defined in ocstack.h.
170         */
171         OCStackResult put(const OCRepresentation& representation,
172                         const QueryParamsMap& queryParametersMap, PutCallback attributeHandler);
173         /**
174         * Function to set the representation of a resource (via PUT)
175         * @param representation which can either have all the attribute names and values
176                  (which will represent entire state of the resource) or a
177         *        set of attribute names and values which needs to be modified
178         *        The callback function will be invoked with a map of attribute name and values.
179         *        The callback function will also have the result from this Put operation
180         *        This will have error codes
181         * @param queryParametersMap map which can have the query parameter name and value
182         * @param attributeHandler attribute handler
183         * @param QoS the quality of communication
184         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
185         * NOTE: OCStackResult is defined in ocstack.h.
186         */
187         OCStackResult put(const OCRepresentation& representation,
188                         const QueryParamsMap& queryParametersMap, PutCallback attributeHandler,
189                         QualityOfService QoS);
190
191         /**
192         * Function to set the attributes of a resource (via PUT)
193         * @param resourceType resource type of the resource to operate on
194         * @param resourceInterface interface type of the resource to operate on
195         * @param representation representation of the resource
196         * @param queryParametersMap Map which can have the query parameter name and value
197         * @param attributeHandler attribute handler
198         *        The callback function will be invoked with a map of attribute name and values.
199         *        The callback function will also have the result from this Put operation
200         *        This will have error codes.
201         *        The Representation parameter maps which can either have all the attribute names
202         *        and values
203         *        (which will represent entire state of the resource) or a
204         *        set of attribute names and values which needs to be modified
205         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
206         * NOTE: OCStackResult is defined in ocstack.h. <br>
207         */
208         OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
209                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
210                         PutCallback attributeHandler);
211         /**
212         * Function to set the attributes of a resource (via PUT)
213         * @param resourceType resource type of the resource to operate on
214         * @param resourceInterface interface type of the resource to operate on
215         * @param representation representation of the resource
216         * @param queryParametersMap Map which can have the query parameter name and value
217         * @param attributeHandler attribute handler
218         *        The callback function will be invoked with a map of attribute name and values.
219         *        The callback function will also have the result from this Put operation
220         *        This will have error codes.
221         *        The Representation parameter maps which can either have all the attribute names
222         *        and values
223         *        (which will represent entire state of the resource) or a
224         *        set of attribute names and values which needs to be modified
225         * @param QoS the quality of communication
226         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
227         * NOTE: OCStackResult is defined in ocstack.h. <br>
228         */
229         OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
230                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
231                         PutCallback attributeHandler, QualityOfService QoS);
232
233         /**
234         * Function to post on a resource
235         * @param representation which can either have all the attribute names and values
236         *        (which will represent entire state of the resource) or a
237         *        set of attribute names and values which needs to be modified
238         *        The callback function will be invoked with a map of attribute name and values.
239         *        The callback function will also have the result from this Put operation
240         *        This will have error codes
241         * @param queryParametersMap map which can have the query parameter name and value
242         * @param attributeHandler attribute handler
243         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
244         * NOTE: OCStackResult is defined in ocstack.h.
245         */
246         OCStackResult post(const OCRepresentation& representation,
247                         const QueryParamsMap& queryParametersMap, PostCallback attributeHandler);
248         /**
249         * Function to post on a resource
250         * @param representation which can either have all the attribute names and values
251         *        (which will represent entire state of the resource) or a
252         *        set of attribute names and values which needs to be modified
253         *        The callback function will be invoked with a map of attribute name and values.
254         *        The callback function will also have the result from this Put operation
255         *        This will have error codes
256         * @param queryParametersMap map which can have the query parameter name and value
257         * @param attributeHandler attribute handler
258         * @param QoS the quality of communication
259         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
260         * NOTE: OCStackResult is defined in ocstack.h.
261         */
262         OCStackResult post(const OCRepresentation& representation,
263                         const QueryParamsMap& queryParametersMap, PostCallback attributeHandler,
264                         QualityOfService QoS);
265
266         /**
267         * Function to post on a resource
268         * @param resourceType resource type of the resource to operate on
269         * @param resourceInterface interface type of the resource to operate on
270         * @param representation representation of the resource
271         * @param queryParametersMap Map which can have the query parameter name and value
272         * @param attributeHandler attribute handler
273         *        The callback function will be invoked with a map of attribute name and values.
274         *        The callback function will also have the result from this Put operation
275         *        This will have error codes.
276         *        The Representation parameter maps which can either have all the attribute names
277         *        and values
278         *        (which will represent entire state of the resource) or a
279         *        set of attribute names and values which needs to be modified
280         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
281         * NOTE: OCStackResult is defined in ocstack.h. <br>
282         */
283         OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
284                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
285                         PostCallback attributeHandler);
286         /**
287         * Function to post on a resource
288         * @param resourceType resource type of the resource to operate on
289         * @param resourceInterface interface type of the resource to operate on
290         * @param representation representation of the resource
291         * @param queryParametersMap Map which can have the query parameter name and value
292         * @param attributeHandler attribute handler
293         *        The callback function will be invoked with a map of attribute name and values.
294         *        The callback function will also have the result from this Put operation
295         *        This will have error codes.
296         *        The Representation parameter maps which can either have all the attribute names
297         *        and values
298         *        (which will represent entire state of the resource) or a
299         *        set of attribute names and values which needs to be modified
300         * @param QoS the quality of communication
301         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
302         * NOTE: OCStackResult is defined in ocstack.h. <br>
303         */
304         OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
305                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
306                         PostCallback attributeHandler, QualityOfService QoS);
307
308         /**
309         * Function to perform DELETE operation
310         * @param deleteHandler handles callback
311         *        The callback function will have headerOptions and result from this Delete
312         *        operation. This will have error codes
313         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
314         * NOTE: OCStackResult is defined in ocstack.h.
315         */
316         OCStackResult deleteResource(DeleteCallback deleteHandler);
317         OCStackResult deleteResource(DeleteCallback deleteHandler, QualityOfService QoS);
318
319         /**
320         * Function to set observation on the resource
321         * @param observeType allows the client to specify how it wants to observe.
322         * @param queryParametersMap map which can have the query parameter name and value
323         * @param observeHandler handles callback
324         *        The callback function will be invoked with a map of attribute name and values.
325         *        The callback function will also have the result from this observe operation
326         *        This will have error codes
327         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
328         * NOTE: OCStackResult is defined in ocstack.h.
329         */
330         OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
331                         ObserveCallback observeHandler);
332         /**
333         * Function to set observation on the resource
334         * @param observeType allows the client to specify how it wants to observe.
335         * @param queryParametersMap map which can have the query parameter name and value
336         * @param observeHandler handles callback
337         *        The callback function will be invoked with a map of attribute name and values.
338         *        The callback function will also have the result from this observe operation
339         *        This will have error codes
340         * @param qos the quality of communication
341         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
342         * NOTE: OCStackResult is defined in ocstack.h.
343         */
344         OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
345                         ObserveCallback observeHandler, QualityOfService qos);
346
347         /**
348         * Function to cancel the observation on the resource
349         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
350         * NOTE: OCStackResult is defined in ocstack.h.
351         */
352         OCStackResult cancelObserve();
353         OCStackResult cancelObserve(QualityOfService qos);
354
355         /**
356         * Function to set header information.
357         * @param headerOptions std::vector where header information(header optionID and optionData
358         * is passed
359         *
360         * NOTE: Once the headers information is set, it will be applicable to GET, PUT and observe
361         * request. <br>
362         * setHeaderOptions can be used multiple times if headers need to be modifed by the client.
363         * Latest headers will be used to send in the request. <br>
364         * NOTE: Initial support is only for two headers. If headerMap consists of more than two
365         * header options, they will be ignored. <br>
366         * Use unsetHeaderOptions API to clear the header information.
367         */
368         void setHeaderOptions(const HeaderOptions& headerOptions)
369         {
370             m_headerOptions = headerOptions;
371         }
372
373         /**
374         * Function to unset header options.
375         */
376         void unsetHeaderOptions()
377         {
378             m_headerOptions.clear();
379         }
380
381         /**
382         * Function to get the host address of this resource
383         * @return std::string host address
384         * NOTE: This might or might not be exposed in future due to security concerns
385         */
386         std::string host() const;
387
388         /**
389         * Function to get the URI for this resource
390         * @return std::string resource URI
391         */
392         std::string uri() const;
393
394         /**
395         * Function to provide ability to check if this resource is observable or not
396         * @return bool true indicates resource is observable; false indicates resource is
397         *         not observable.
398         */
399         bool isObservable() const;
400
401         /**
402         * Function to get the list of resource types
403         * @return vector of resource types
404         */
405         std::vector<std::string> getResourceTypes() const
406         {
407             return m_resourceTypes;
408         }
409
410         /**
411         * Function to get the list of resource interfaces
412         * @return vector of resource interface
413         */
414         std::vector<std::string> getResourceInterfaces(void) const
415         {
416             return m_interfaces;
417         }
418
419     private:
420         std::weak_ptr<IClientWrapper> m_clientWrapper;
421         std::string m_uri;
422         std::string m_host;
423         bool m_isObservable;
424         bool m_isCollection;
425         std::vector<std::string> m_resourceTypes;
426         std::vector<std::string> m_interfaces;
427         std::vector<std::string> m_children;
428         OCDoHandle m_observeHandle;
429         HeaderOptions m_headerOptions;
430
431     private:
432         OCResource(std::weak_ptr<IClientWrapper> clientWrapper, const std::string& host,
433             const std::string& uri, bool observable, const std::vector<std::string>& resourceTypes,
434             const std::vector<std::string>& interfaces);
435     };
436
437 } // namespace OC
438
439 #endif //__OCRESOURCE_H