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