Merge branch 'resource-container'
[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 OC_RESOURCE_H_
29 #define OC_RESOURCE_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 Returns  ::OC_STACK_OK on success, some other value upon failure.
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 Returns  ::OC_STACK_OK on success, some other value upon failure.
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 Returns  ::OC_STACK_OK on success, some other value upon failure.
152         * @note OCStackResult is defined in ocstack.h.
153         * @par Example:
154         * Consider resource "a/home" (with link interface and resource type as home) contains links
155         *  to "a/kitchen" and "a/room".
156         * -# get("home", Link_Interface, &onGet)
157         * @par
158         * Callback onGet will receive a) Empty attribute map because there are no attributes for
159         * a/home b) list with
160         * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
161         * operation
162         * @note A resource may contain single or multiple resource types. Also, a resource may
163         * contain single or multiple interfaces.
164         * Currently, single GET request is allowed to do operate on single resource type or resource
165         * interface. In future, a single GET
166         * can operate on multiple resource types and interfaces.
167         * @note A client can traverse a tree or graph by doing successive GETs on the returned
168         * resources at a node.
169         *
170         */
171         OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
172                         const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
173         /**
174         * Function to get the attributes of a resource.
175         *
176         * @param resourceType resourceType of the resource operate on
177         * @param resourceInterface interface type of the resource to operate on
178         * @param queryParametersMap map which can have the query parameter name and value
179         * @param attributeHandler handles callback
180         *        The callback function will be invoked with a map of attribute name and values.
181         *        The callback function will be invoked with a list of URIs if 'get' is invoked on a
182         *        resource container (list will be empty if not a container)
183         *        The callback function will also have the result from this Get operation. This will
184         *        have error codes
185         * @param QoS the quality of communication
186         * @return Returns  ::OC_STACK_OK on success, some other value upon failure.
187         * note OCStackResult is defined in ocstack.h.
188         * @par Example:
189         * Consider resource "a/home" (with link interface and resource type as home) contains links
190         *  to "a/kitchen" and "a/room".
191         * -# get("home", Link_Interface, &onGet)
192         * @par
193         * Callback onGet will receive a) Empty attribute map because there are no attributes for
194         * a/home b) list with
195         * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
196         * operation
197         * @note A resource may contain single or multiple resource types. Also, a resource may
198         * contain single or multiple interfaces.
199         * Currently, single GET request is allowed to do operate on single resource type or resource
200         * interface. In future, a single GET
201         * can operate on multiple resource types and interfaces.
202         * @note A client can traverse a tree or graph by doing successive GETs on the returned
203         * resources at a node.
204         *
205         */
206         OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
207                         const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
208                         QualityOfService QoS);
209
210         /**
211         * Function to set the representation of a resource (via PUT)
212         *
213         * @param representation which can either have all the attribute names and values
214                  (which will represent entire state of the resource) or a
215         *        set of attribute names and values which needs to be modified
216         *        The callback function will be invoked with a map of attribute name and values.
217         *        The callback function will also have the result from this Put operation
218         *        This will have error codes
219         * @param queryParametersMap map which can have the query parameter name and value
220         * @param attributeHandler attribute handler
221         * @return Returns  ::OC_STACK_OK on success, some other value upon failure.
222         * @note OCStackResult is defined in ocstack.h.
223         *
224         */
225         OCStackResult put(const OCRepresentation& representation,
226                         const QueryParamsMap& queryParametersMap, PutCallback attributeHandler);
227         /**
228         * Function to set the representation of a resource (via PUT)
229         *
230         * @param representation which can either have all the attribute names and values
231                  (which will represent entire state of the resource) or a
232         *        set of attribute names and values which needs to be modified
233         *        The callback function will be invoked with a map of attribute name and values.
234         *        The callback function will also have the result from this Put operation
235         *        This will have error codes
236         * @param queryParametersMap map which can have the query parameter name and value
237         * @param attributeHandler attribute handler
238         * @param QoS the quality of communication
239         * @return Returns  ::OC_STACK_OK on success, some other value upon failure.
240         * @note OCStackResult is defined in ocstack.h.
241         *
242         */
243         OCStackResult put(const OCRepresentation& representation,
244                         const QueryParamsMap& queryParametersMap, PutCallback attributeHandler,
245                         QualityOfService QoS);
246
247         /**
248         * Function to set the attributes of a resource (via PUT)
249         *
250         * @param resourceType resource type of the resource to operate on
251         * @param resourceInterface interface type of the resource to operate on
252         * @param representation representation of the resource
253         * @param queryParametersMap Map which can have the query parameter name and value
254         * @param attributeHandler attribute handler
255         *        The callback function will be invoked with a map of attribute name and values.
256         *        The callback function will also have the result from this Put operation
257         *        This will have error codes.
258         *        The Representation parameter maps which can either have all the attribute names
259         *        and values
260         *        (which will represent entire state of the resource) or a
261         *        set of attribute names and values which needs to be modified
262         * @return Returns  ::OC_STACK_OK on success, some other value upon failure.
263         * @note OCStackResult is defined in ocstack.h.
264         *
265         */
266         OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
267                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
268                         PutCallback attributeHandler);
269         /**
270         * Function to set the attributes of a resource (via PUT)
271         * @param resourceType resource type of the resource to operate on
272         * @param resourceInterface interface type of the resource to operate on
273         * @param representation representation of the resource
274         * @param queryParametersMap Map which can have the query parameter name and value
275         * @param attributeHandler attribute handler
276         *        The callback function will be invoked with a map of attribute name and values.
277         *        The callback function will also have the result from this Put operation
278         *        This will have error codes.
279         *        The Representation parameter maps which can either have all the attribute names
280         *        and values
281         *        (which will represent entire state of the resource) or a
282         *        set of attribute names and values which needs to be modified
283         * @param QoS the quality of communication
284         * @return Returns  ::OC_STACK_OK on success, some other value upon failure.
285         * @note OCStackResult is defined in ocstack.h.
286         *
287         */
288         OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
289                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
290                         PutCallback attributeHandler, QualityOfService QoS);
291
292         /**
293         * Function to post on a resource
294         *
295         * @param representation which can either have all the attribute names and values
296         *        (which will represent entire state of the resource) or a
297         *        set of attribute names and values which needs to be modified
298         *        The callback function will be invoked with a map of attribute name and values.
299         *        The callback function will also have the result from this Put operation
300         *        This will have error codes
301         * @param queryParametersMap map which can have the query parameter name and value
302         * @param attributeHandler attribute handler
303         * @return Returns  ::OC_STACK_OK on success, some other value upon failure.
304         * @note OCStackResult is defined in ocstack.h.
305         */
306         OCStackResult post(const OCRepresentation& representation,
307                         const QueryParamsMap& queryParametersMap, PostCallback attributeHandler);
308         /**
309         * Function to post on a resource
310         *
311         * @param representation which can either have all the attribute names and values
312         *        (which will represent entire state of the resource) or a
313         *        set of attribute names and values which needs to be modified
314         *        The callback function will be invoked with a map of attribute name and values.
315         *        The callback function will also have the result from this Put operation
316         *        This will have error codes
317         * @param queryParametersMap map which can have the query parameter name and value
318         * @param attributeHandler attribute handler
319         * @param QoS the quality of communication
320         * @return Returns  ::OC_STACK_OK on success, some other value upon failure.
321         * @note OCStackResult is defined in ocstack.h.
322         */
323         OCStackResult post(const OCRepresentation& representation,
324                         const QueryParamsMap& queryParametersMap, PostCallback attributeHandler,
325                         QualityOfService QoS);
326
327         /**
328         * Function to post on a resource
329         *
330         * @param resourceType resource type of the resource to operate on
331         * @param resourceInterface interface type of the resource to operate on
332         * @param representation representation of the resource
333         * @param queryParametersMap Map which can have the query parameter name and value
334         * @param attributeHandler attribute handler
335         *        The callback function will be invoked with a map of attribute name and values.
336         *        The callback function will also have the result from this Put operation
337         *        This will have error codes.
338         *        The Representation parameter maps which can either have all the attribute names
339         *        and values
340         *        (which will represent entire state of the resource) or a
341         *        set of attribute names and values which needs to be modified
342         * @return Returns  ::OC_STACK_OK on success, some other value upon failure.
343         * @note OCStackResult is defined in ocstack.h.
344         *
345         */
346         OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
347                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
348                         PostCallback attributeHandler);
349         /**
350         * Function to post on a resource
351         *
352         * @param resourceType resource type of the resource to operate on
353         * @param resourceInterface interface type of the resource to operate on
354         * @param representation representation of the resource
355         * @param queryParametersMap Map which can have the query parameter name and value
356         * @param attributeHandler attribute handler
357         *        The callback function will be invoked with a map of attribute name and values.
358         *        The callback function will also have the result from this Put operation
359         *        This will have error codes.
360         *        The Representation parameter maps which can either have all the attribute names
361         *        and values
362         *        (which will represent entire state of the resource) or a
363         *        set of attribute names and values which needs to be modified
364         * @param QoS the quality of communication
365         * @return Returns  ::OC_STACK_OK on success, some other value upon failure.
366         * @note OCStackResult is defined in ocstack.h.
367         *
368         */
369         OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
370                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
371                         PostCallback attributeHandler, QualityOfService QoS);
372
373         /**
374         * Function to perform DELETE operation
375         *
376         * @param deleteHandler handles callback
377         *        The callback function will have headerOptions and result from this Delete
378         *        operation. This will have error codes
379         * @return Returns  ::OC_STACK_OK on success, some other value upon failure.
380         * @note OCStackResult is defined in ocstack.h.
381         *
382         */
383         OCStackResult deleteResource(DeleteCallback deleteHandler);
384         OCStackResult deleteResource(DeleteCallback deleteHandler, QualityOfService QoS);
385
386         /**
387         * Function to set observation on the resource
388         *
389         * @param observeType allows the client to specify how it wants to observe.
390         * @param queryParametersMap map which can have the query parameter name and value
391         * @param observeHandler handles callback
392         *        The callback function will be invoked with a map of attribute name and values.
393         *        The callback function will also have the result from this observe operation
394         *        This will have error codes
395         * @return Returns  ::OC_STACK_OK on success, some other value upon failure.
396         * @note OCStackResult is defined in ocstack.h.
397         *
398         */
399         OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
400                         ObserveCallback observeHandler);
401         /**
402         * Function to set observation on the resource
403         *
404         * @param observeType allows the client to specify how it wants to observe.
405         * @param queryParametersMap map which can have the query parameter name and value
406         * @param observeHandler handles callback
407         *        The callback function will be invoked with a map of attribute name and values.
408         *        The callback function will also have the result from this observe operation
409         *        This will have error codes
410         * @param qos the quality of communication
411         * @return Returns  ::OC_STACK_OK on success, some other value upon failure.
412         * @note OCStackResult is defined in ocstack.h.
413         *
414         */
415         OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
416                         ObserveCallback observeHandler, QualityOfService qos);
417
418         /**
419         * Function to cancel the observation on the resource
420         *
421         * @return Returns  ::OC_STACK_OK on success, some other value upon failure.
422         * @note OCStackResult is defined in ocstack.h.
423         *
424         */
425         OCStackResult cancelObserve();
426         OCStackResult cancelObserve(QualityOfService qos);
427
428         /**
429         * Function to set header information.
430         * @param headerOptions std::vector where header information(header optionID and optionData
431         * is passed
432         *
433         * @note Once the headers information is set, it will be applicable to GET, PUT and observe
434         * request.
435         * setHeaderOptions can be used multiple times if headers need to be modifed by the client.
436         * Latest headers will be used to send in the request. <br>
437         * @note Initial support is only for two headers. If headerMap consists of more than two
438         * header options, they will be ignored. <br>
439         * Use unsetHeaderOptions API to clear the header information.
440         */
441         void setHeaderOptions(const HeaderOptions& headerOptions);
442
443         /**
444         * Function to unset header options.
445         */
446         void unsetHeaderOptions();
447
448         /**
449         * Function to get the host address of this resource
450         * @return std::string host address
451         * @note This might or might not be exposed in future due to security concerns
452         */
453         std::string host() const;
454
455         /**
456         * Function to get the URI for this resource
457         * @return std::string resource URI
458         */
459         std::string uri() const;
460
461         /**
462         * Function to get the connectivity type of this resource
463         * @return enum connectivity type (flags and adapter)
464         */
465         OCConnectivityType connectivityType() const;
466
467         /**
468         * Function to provide ability to check if this resource is observable or not
469         * @return bool true indicates resource is observable; false indicates resource is
470         *         not observable.
471         */
472         bool isObservable() const;
473
474         /**
475         * Function to get the list of resource types
476         * @return vector of resource types
477         */
478         std::vector<std::string> getResourceTypes() const;
479
480         /**
481         * Function to get the list of resource interfaces
482         * @return vector of resource interface
483         */
484         std::vector<std::string> getResourceInterfaces(void) const;
485
486         // TODO-CA Revisit this since we are exposing two identifiers
487         /**
488         * Function to get a unique identifier for this
489         * resource across network interfaces.  This will
490         * be guaranteed unique for every resource-per-server
491         * independent of how this was discovered.
492         * @return OCResourceIdentifier object, which can
493         * be used for all comparison and hashing.
494         */
495         OCResourceIdentifier uniqueIdentifier() const;
496
497         /**
498         * Function to get a string representation of the resource's server ID.
499         * This is unique per- server independent on how it was discovered.
500         * @note The format of the return value is subject to change and will
501         * likely change both in size and contents in the future.
502         */
503         std::string sid() const;
504
505         // overloaded operators allow for putting into a 'set'
506         // the uniqueidentifier allows for putting into a hash
507         bool operator==(const OCResource &other) const;
508
509         bool operator!=(const OCResource &other) const;
510
511         bool operator<(const OCResource &other) const;
512
513         bool operator>(const OCResource &other) const;
514
515         bool operator<=(const OCResource &other) const;
516
517         bool operator>=(const OCResource &other) const;
518
519     private:
520         void setHost(const std::string& host);
521         std::weak_ptr<IClientWrapper> m_clientWrapper;
522         std::string m_uri;
523         OCResourceIdentifier m_resourceId;
524         OCDevAddr m_devAddr;
525         bool m_useHostString;
526         bool m_isObservable;
527         bool m_isCollection;
528         std::vector<std::string> m_resourceTypes;
529         std::vector<std::string> m_interfaces;
530         std::vector<std::string> m_children;
531         OCDoHandle m_observeHandle;
532         HeaderOptions m_headerOptions;
533
534     private:
535         OCResource(std::weak_ptr<IClientWrapper> clientWrapper,
536                     const OCDevAddr& devAddr, const std::string& uri,
537                     const std::string& serverId, bool observable,
538                     const std::vector<std::string>& resourceTypes,
539                     const std::vector<std::string>& interfaces);
540
541         OCResource(std::weak_ptr<IClientWrapper> clientWrapper,
542                     const std::string& host, const std::string& uri,
543                     const std::string& serverId,
544                     OCConnectivityType connectivityType, bool observable,
545                     const std::vector<std::string>& resourceTypes,
546                     const std::vector<std::string>& interfaces);
547     };
548
549 } // namespace OC
550
551 #endif // OC_RESOURCE_H
552