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