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