Merge branch 'master' into easysetup and fixed OCStack issue
[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     class OCResource;
44     class OCResourceIdentifier;
45     std::ostream& operator <<(std::ostream& os, const OCResourceIdentifier& ri);
46     /**
47     *  @brief  OCResourceIdentifier represents the identity information for a server. This
48     *          object combined with the OCResource's URI property uniquely identify an
49     *          OCResource on or across networks.
50     *          Equality operators are implemented.  However, internal representation is subject
51     *          to change and thus should not be accessed or depended on.
52     */
53     class OCResourceIdentifier
54     {
55         friend class OCResource;
56         friend std::ostream& operator <<(std::ostream& os, const OCResourceIdentifier& ri);
57
58         public:
59             OCResourceIdentifier() = delete;
60
61             OCResourceIdentifier(const OCResourceIdentifier&) = default;
62
63             OCResourceIdentifier(OCResourceIdentifier&&) = default;
64
65             OCResourceIdentifier& operator=(const OCResourceIdentifier&) = delete;
66
67             OCResourceIdentifier& operator=(OCResourceIdentifier&&) = delete;
68
69             bool operator==(const OCResourceIdentifier &other) const;
70
71             bool operator!=(const OCResourceIdentifier &other) const;
72
73             bool operator<(const OCResourceIdentifier &other) const;
74
75             bool operator>(const OCResourceIdentifier &other) const;
76
77             bool operator<=(const OCResourceIdentifier &other) const;
78
79             bool operator>=(const OCResourceIdentifier &other) const;
80
81         private:
82
83             OCResourceIdentifier(const std::string& wireServerIdentifier,
84                     const std::string& resourceUri );
85
86         private:
87             std::string m_representation;
88             const std::string& m_resourceUri;
89     };
90
91     /**
92     *   @brief  OCResource represents an OC resource. A resource could be a light controller,
93     *           temperature sensor, smoke detector, etc. A resource comes with a well-defined
94     *           contract or interface onto which you can perform different operations, such as
95     *           turning on the light, getting the current temperature or subscribing for event
96     *           notifications from the smoke detector. A resource can be composed of one or
97     *           more resources.
98     */
99     class OCResource
100     {
101     friend class OCPlatform_impl;
102     friend class ListenOCContainer;
103     public:
104         typedef std::shared_ptr<OCResource> Ptr;
105
106         OCResource(OCResource&&) = default;
107         OCResource& operator=(OCResource&&) = default;
108
109         /**
110         * Virtual destructor
111         */
112         virtual ~OCResource(void);
113
114         /**
115         * Function to get the attributes of a resource.
116         * @param queryParametersMap map which can have the query parameter name and value
117         * @param attributeHandler handles callback
118         *        The callback function will be invoked with a map of attribute name and values.
119         *        The callback function will also have the result from this Get operation
120         *        This will have error codes
121         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
122         * NOTE: OCStackResult is defined in ocstack.h.
123         */
124         OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
125         /**
126         * Function to get the attributes of a resource.
127         * @param queryParametersMap map which can have the query parameter name and value
128         * @param attributeHandler handles callback
129         *        The callback function will be invoked with a map of attribute name and values.
130         *        The callback function will also have the result from this Get operation
131         *        This will have error codes
132         * @param QoS the quality of communication
133         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
134         * NOTE: OCStackResult is defined in ocstack.h.
135         */
136         OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
137                           QualityOfService QoS);
138
139         /**
140         * Function to get the attributes of a resource.
141         *
142         * @param resourceType resourceType of the resource operate on
143         * @param resourceInterface interface type of the resource to operate on
144         * @param queryParametersMap map which can have the query parameter name and value
145         * @param attributeHandler handles callback
146         *        The callback function will be invoked with a map of attribute name and values.
147         *        The callback function will be invoked with a list of URIs if 'get' is invoked on a
148         *        resource container (list will be empty if not a container)
149         *        The callback function will also have the result from this Get operation. This will
150         *        have error codes
151         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
152         * NOTE: OCStackResult is defined in ocstack.h.<br>
153         * <b>Example:</b><br>
154         * Consider resource "a/home" (with link interface and resource type as home) contains links
155         *  to "a/kitchen" and "a/room".
156         * Step 1: get("home", Link_Interface, &onGet)<br>
157         * Callback onGet will receive a) Empty attribute map because there are no attributes for
158         * a/home b) list with
159         * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
160         * operation<br>
161         * NOTE: A resource may contain single or multiple resource types. Also, a resource may
162         * contain single or multiple interfaces.<br>
163         * Currently, single GET request is allowed to do operate on single resource type or resource
164         * interface. In future, a single GET <br>
165         * can operate on multiple resource types and interfaces. <br>
166         * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned
167         * resources at a node.<br>
168         */
169         OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
170                         const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
171         /**
172         * Function to get the attributes of a resource.
173         *
174         * @param resourceType resourceType of the resource operate on
175         * @param resourceInterface interface type of the resource to operate on
176         * @param queryParametersMap map which can have the query parameter name and value
177         * @param attributeHandler handles callback
178         *        The callback function will be invoked with a map of attribute name and values.
179         *        The callback function will be invoked with a list of URIs if 'get' is invoked on a
180         *        resource container (list will be empty if not a container)
181         *        The callback function will also have the result from this Get operation. This will
182         *        have error codes
183         * @param QoS the quality of communication
184         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
185         * NOTE: OCStackResult is defined in ocstack.h.<br>
186         * <b>Example:</b><br>
187         * Consider resource "a/home" (with link interface and resource type as home) contains links
188         *  to "a/kitchen" and "a/room".
189         * Step 1: get("home", Link_Interface, &onGet)<br>
190         * Callback onGet will receive a) Empty attribute map because there are no attributes for
191         * a/home b) list with
192         * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
193         * operation<br>
194         * NOTE: A resource may contain single or multiple resource types. Also, a resource may
195         * contain single or multiple interfaces.<br>
196         * Currently, single GET request is allowed to do operate on single resource type or resource
197         * interface. In future, a single GET <br>
198         * can operate on multiple resource types and interfaces. <br>
199         * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned
200         * resources at a node.<br>
201         */
202         OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
203                         const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
204                         QualityOfService QoS);
205
206         /**
207         * Function to set the representation of a resource (via PUT)
208         * @param representation which can either have all the attribute names and values
209                  (which will represent entire state of the resource) or a
210         *        set of attribute names and values which needs to be modified
211         *        The callback function will be invoked with a map of attribute name and values.
212         *        The callback function will also have the result from this Put operation
213         *        This will have error codes
214         * @param queryParametersMap map which can have the query parameter name and value
215         * @param attributeHandler attribute handler
216         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
217         * NOTE: OCStackResult is defined in ocstack.h.
218         */
219         OCStackResult put(const OCRepresentation& representation,
220                         const QueryParamsMap& queryParametersMap, PutCallback attributeHandler);
221         /**
222         * Function to set the representation of a resource (via PUT)
223         * @param representation which can either have all the attribute names and values
224                  (which will represent entire state of the resource) or a
225         *        set of attribute names and values which needs to be modified
226         *        The callback function will be invoked with a map of attribute name and values.
227         *        The callback function will also have the result from this Put operation
228         *        This will have error codes
229         * @param queryParametersMap map which can have the query parameter name and value
230         * @param attributeHandler attribute handler
231         * @param QoS the quality of communication
232         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
233         * NOTE: OCStackResult is defined in ocstack.h.
234         */
235         OCStackResult put(const OCRepresentation& representation,
236                         const QueryParamsMap& queryParametersMap, PutCallback attributeHandler,
237                         QualityOfService QoS);
238
239         /**
240         * Function to set the attributes of a resource (via PUT)
241         * @param resourceType resource type of the resource to operate on
242         * @param resourceInterface interface type of the resource to operate on
243         * @param representation representation of the resource
244         * @param queryParametersMap Map which can have the query parameter name and value
245         * @param attributeHandler attribute handler
246         *        The callback function will be invoked with a map of attribute name and values.
247         *        The callback function will also have the result from this Put operation
248         *        This will have error codes.
249         *        The Representation parameter maps which can either have all the attribute names
250         *        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         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
254         * NOTE: OCStackResult is defined in ocstack.h. <br>
255         */
256         OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
257                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
258                         PutCallback attributeHandler);
259         /**
260         * Function to set the attributes of a resource (via PUT)
261         * @param resourceType resource type of the resource to operate on
262         * @param resourceInterface interface type of the resource to operate on
263         * @param representation representation of the resource
264         * @param queryParametersMap Map which can have the query parameter name and value
265         * @param attributeHandler attribute handler
266         *        The callback function will be invoked with a map of attribute name and values.
267         *        The callback function will also have the result from this Put operation
268         *        This will have error codes.
269         *        The Representation parameter maps which can either have all the attribute names
270         *        and values
271         *        (which will represent entire state of the resource) or a
272         *        set of attribute names and values which needs to be modified
273         * @param QoS the quality of communication
274         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
275         * NOTE: OCStackResult is defined in ocstack.h. <br>
276         */
277         OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
278                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
279                         PutCallback attributeHandler, QualityOfService QoS);
280
281         /**
282         * Function to post on a resource
283         * @param representation which can either have all the attribute names and values
284         *        (which will represent entire state of the resource) or a
285         *        set of attribute names and values which needs to be modified
286         *        The callback function will be invoked with a map of attribute name and values.
287         *        The callback function will also have the result from this Put operation
288         *        This will have error codes
289         * @param queryParametersMap map which can have the query parameter name and value
290         * @param attributeHandler attribute handler
291         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
292         * NOTE: OCStackResult is defined in ocstack.h.
293         */
294         OCStackResult post(const OCRepresentation& representation,
295                         const QueryParamsMap& queryParametersMap, PostCallback attributeHandler);
296         /**
297         * Function to post on a resource
298         * @param representation which can either have all the attribute names and values
299         *        (which will represent entire state of the resource) or a
300         *        set of attribute names and values which needs to be modified
301         *        The callback function will be invoked with a map of attribute name and values.
302         *        The callback function will also have the result from this Put operation
303         *        This will have error codes
304         * @param queryParametersMap map which can have the query parameter name and value
305         * @param attributeHandler attribute handler
306         * @param QoS the quality of communication
307         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
308         * NOTE: OCStackResult is defined in ocstack.h.
309         */
310         OCStackResult post(const OCRepresentation& representation,
311                         const QueryParamsMap& queryParametersMap, PostCallback attributeHandler,
312                         QualityOfService QoS);
313
314         /**
315         * Function to post on a resource
316         * @param resourceType resource type of the resource to operate on
317         * @param resourceInterface interface type of the resource to operate on
318         * @param representation representation of the resource
319         * @param queryParametersMap Map which can have the query parameter name and value
320         * @param attributeHandler attribute handler
321         *        The callback function will be invoked with a map of attribute name and values.
322         *        The callback function will also have the result from this Put operation
323         *        This will have error codes.
324         *        The Representation parameter maps which can either have all the attribute names
325         *        and values
326         *        (which will represent entire state of the resource) or a
327         *        set of attribute names and values which needs to be modified
328         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
329         * NOTE: OCStackResult is defined in ocstack.h. <br>
330         */
331         OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
332                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
333                         PostCallback attributeHandler);
334         /**
335         * Function to post on a resource
336         * @param resourceType resource type of the resource to operate on
337         * @param resourceInterface interface type of the resource to operate on
338         * @param representation representation of the resource
339         * @param queryParametersMap Map which can have the query parameter name and value
340         * @param attributeHandler attribute handler
341         *        The callback function will be invoked with a map of attribute name and values.
342         *        The callback function will also have the result from this Put operation
343         *        This will have error codes.
344         *        The Representation parameter maps which can either have all the attribute names
345         *        and values
346         *        (which will represent entire state of the resource) or a
347         *        set of attribute names and values which needs to be modified
348         * @param QoS the quality of communication
349         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
350         * NOTE: OCStackResult is defined in ocstack.h. <br>
351         */
352         OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
353                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
354                         PostCallback attributeHandler, QualityOfService QoS);
355
356         /**
357         * Function to perform DELETE operation
358         * @param deleteHandler handles callback
359         *        The callback function will have headerOptions and result from this Delete
360         *        operation. This will have error codes
361         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
362         * NOTE: OCStackResult is defined in ocstack.h.
363         */
364         OCStackResult deleteResource(DeleteCallback deleteHandler);
365         OCStackResult deleteResource(DeleteCallback deleteHandler, QualityOfService QoS);
366
367         /**
368         * Function to set observation on the resource
369         * @param observeType allows the client to specify how it wants to observe.
370         * @param queryParametersMap map which can have the query parameter name and value
371         * @param observeHandler handles callback
372         *        The callback function will be invoked with a map of attribute name and values.
373         *        The callback function will also have the result from this observe operation
374         *        This will have error codes
375         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
376         * NOTE: OCStackResult is defined in ocstack.h.
377         */
378         OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
379                         ObserveCallback observeHandler);
380         /**
381         * Function to set observation on the resource
382         * @param observeType allows the client to specify how it wants to observe.
383         * @param queryParametersMap map which can have the query parameter name and value
384         * @param observeHandler handles callback
385         *        The callback function will be invoked with a map of attribute name and values.
386         *        The callback function will also have the result from this observe operation
387         *        This will have error codes
388         * @param qos the quality of communication
389         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
390         * NOTE: OCStackResult is defined in ocstack.h.
391         */
392         OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
393                         ObserveCallback observeHandler, QualityOfService qos);
394
395         /**
396         * Function to cancel the observation on the resource
397         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
398         * NOTE: OCStackResult is defined in ocstack.h.
399         */
400         OCStackResult cancelObserve();
401         OCStackResult cancelObserve(QualityOfService qos);
402
403         /**
404         * Function to set header information.
405         * @param headerOptions std::vector where header information(header optionID and optionData
406         * is passed
407         *
408         * NOTE: Once the headers information is set, it will be applicable to GET, PUT and observe
409         * request. <br>
410         * setHeaderOptions can be used multiple times if headers need to be modifed by the client.
411         * Latest headers will be used to send in the request. <br>
412         * NOTE: Initial support is only for two headers. If headerMap consists of more than two
413         * header options, they will be ignored. <br>
414         * Use unsetHeaderOptions API to clear the header information.
415         */
416         void setHeaderOptions(const HeaderOptions& headerOptions)
417         {
418             m_headerOptions = headerOptions;
419         }
420
421         /**
422         * Function to unset header options.
423         */
424         void unsetHeaderOptions()
425         {
426             m_headerOptions.clear();
427         }
428
429         /**
430         * Function to get the host address of this resource
431         * @return std::string host address
432         * NOTE: This might or might not be exposed in future due to security concerns
433         */
434         std::string host() const;
435
436         /**
437         * Function to get the URI for this resource
438         * @return std::string resource URI
439         */
440         std::string uri() const;
441
442         /**
443         * Function to get the connectivity type of this resource
444         * @return enum connectivity type (flags and adapter)
445         */
446         OCConnectivityType connectivityType() const;
447
448         /**
449         * Function to provide ability to check if this resource is observable or not
450         * @return bool true indicates resource is observable; false indicates resource is
451         *         not observable.
452         */
453         bool isObservable() const;
454
455         /**
456         * Function to get the list of resource types
457         * @return vector of resource types
458         */
459         std::vector<std::string> getResourceTypes() const
460         {
461             return m_resourceTypes;
462         }
463
464         /**
465         * Function to get the list of resource interfaces
466         * @return vector of resource interface
467         */
468         std::vector<std::string> getResourceInterfaces(void) const
469         {
470             return m_interfaces;
471         }
472
473         // TODO-CA Revisit this since we are exposing two identifiers
474         /**
475         * Function to get a unique identifier for this
476         * resource across network interfaces.  This will
477         * be guaranteed unique for every resource-per-server
478         * independent of how this was discovered.
479         * @return OCResourceIdentifier object, which can
480         * be used for all comparison and hashing.
481         */
482         OCResourceIdentifier uniqueIdentifier() const;
483
484         /**
485         * Function to get a string representation of the resource's server ID.
486         * This is unique per- server independent on how it was discovered.
487         * Note: The format of the return value is subject to change and will
488         * likely change both in size and contents in the future.
489         */
490         std::string sid() const;
491
492         // overloaded operators allow for putting into a 'set'
493         // the uniqueidentifier allows for putting into a hash
494         bool operator==(const OCResource &other) const;
495
496         bool operator!=(const OCResource &other) const;
497
498         bool operator<(const OCResource &other) const;
499
500         bool operator>(const OCResource &other) const;
501
502         bool operator<=(const OCResource &other) const;
503
504         bool operator>=(const OCResource &other) const;
505
506     private:
507         std::weak_ptr<IClientWrapper> m_clientWrapper;
508         std::string m_uri;
509         OCResourceIdentifier m_resourceId;
510         OCDevAddr m_devAddr;
511         bool m_isObservable;
512         bool m_isCollection;
513         std::vector<std::string> m_resourceTypes;
514         std::vector<std::string> m_interfaces;
515         std::vector<std::string> m_children;
516         OCDoHandle m_observeHandle;
517         HeaderOptions m_headerOptions;
518
519     private:
520         OCResource(std::weak_ptr<IClientWrapper> clientWrapper,
521                     const OCDevAddr& devAddr, const std::string& uri,
522                     const std::string& serverId, bool observable,
523                     const std::vector<std::string>& resourceTypes,
524                     const std::vector<std::string>& interfaces);
525
526         OCResource(std::weak_ptr<IClientWrapper> clientWrapper,
527                     const std::string& host, const std::string& uri,
528                     const std::string& serverId,
529                     OCConnectivityType connectivityType, bool observable,
530                     const std::vector<std::string>& resourceTypes,
531                     const std::vector<std::string>& interfaces);
532     };
533
534 } // namespace OC
535
536 #endif //__OCRESOURCE_H
537