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 <boost/property_tree/ptree.hpp>
  34 #include <boost/property_tree/json_parser.hpp>
  35
  36 #include <OCApi.h>
  37 #include <ResourceInitException.h>
  38 #include <IClientWrapper.h>
  39 #include <InProcClientWrapper.h>
  40 #include <OCRepresentation.h>
  41
  42 namespace OC
  43 {
  44     /**
  45     *   @brief  OCResource represents an OC resource. A resource could be a light controller,
  46     *           temperature sensor, smoke detector, etc. A resource comes with a well-defined
  47     *           contract or interface onto which you can perform different operations, such as
  48     *           turning on the light, getting the current temperature or subscribing for event
  49     *           notifications from the smoke detector. A resource can be composed of one or
  50     *           more resources.
  51     */
  52     class OCResource
  53     {
  54     friend class OCPlatform;
  55     friend class InProcClientWrapper;
  56     public:
  57         typedef std::shared_ptr<OCResource> Ptr;
  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         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
  72         * NOTE: OCStackResult is defined in ocstack.h.
  73         */
  74         OCStackResult get(const QueryParamsMap& queryParametersMap, std::function<void(const OCRepresentation, const int)> attributeHandler);
  75
  76         /**
  77         * Function to get the attributes of a resource.
  78         *
  79         * @param resourceType resourceType of the resource operate on
  80         * @param resourceInterface interface type of the resource to operate on
  81         * @param queryParametersMap map which can have the query parameter name and value
  82         * @param attributeHandler handles callback
  83         *        The callback function will be invoked with a map of attribute name and values.
  84         *        The callback function will be invoked with a list of URIs if 'get' is invoked on a resource container
  85         *        (list will be empty if not a container)
  86         *        The callback function will also have the result from this Get operation. This will have error codes
  87         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
  88         * NOTE: OCStackResult is defined in ocstack.h.<br>
  89         * <b>Example:</b><br>
  90         * Consider resource "a/home" (with link interface and resource type as home) contains links to "a/kitchen" and "a/room".
  91         * Step 1: get("home", Link_Interface, &onGet)<br>
  92         * Callback onGet will receive a) Empty attribute map because there are no attributes for a/home b) list with
  93         * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET operation<br>
  94         * NOTE: A resource may contain single or multiple resource types. Also, a resource may contain single or multiple interfaces.<br>
  95         * Currently, single GET request is allowed to do operate on single resource type or resource interface. In future, a single GET <br>
  96         * can operate on multiple resource types and interfaces. <br>
  97         * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned resources at a node.<br>
  98         * TODO: Implementation
  99         */
 100         OCStackResult get(const std::string& resourceType, const std::string& resourceInterface, const QueryParamsMap& queryParametersMap,
 101             std::function<void(const OCRepresentation& rep, const std::vector<std::string>& resourceUriList, const int& errorCode)> attributeHandler)
 102             { return OC_STACK_OK; }
 103
 104         /**
 105         * Function to set the attributes of a resource (via PUT)
 106         * @param attributeMap Map which can either have all the attribute names and values
 107                  (which will represent entire state of the resource) or a
 108         *        set of attribute names and values which needs to be modified
 109         *        The callback function will be invoked with a map of attribute name and values.
 110         *        The callback function will also have the result from this Put operation
 111         *        This will have error codes
 112         * @param queryParametersMap map which can have the query parameter name and value
 113         * @param attributeHandler attribute handler
 114         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 115         * NOTE: OCStackResult is defined in ocstack.h.
 116         */
 117         OCStackResult put(const OCRepresentation& attributeMap, const QueryParamsMap& queryParametersMap,
 118             std::function< void(const OCRepresentation,const int)> attributeHandler);
 119
 120         /**
 121         * Function to set the attributes of a resource (via PUT)
 122         * @param resourceType resource type of the resource to operate on
 123         * @param resourceInterface interface type of the resource to operate on
 124         * @param attributeMap attribute map
 125         * @param queryParametersMap Map which can have the query parameter name and value
 126         * @param attributeHandler attribute handler
 127         *        The callback function will be invoked with a map of attribute name and values.
 128         *        The callback function will also have the result from this Put operation
 129         *        This will have error codes.
 130         *        The AttributeMap parameter maps which can either have all the attribute names and values
 131         *        (which will represent entire state of the resource) or a
 132         *        set of attribute names and values which needs to be modified
 133         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 134         * NOTE: OCStackResult is defined in ocstack.h. <br>
 135         * TODO: consider to input hrefs for resource collection
 136         * TODO: Implementation
 137         */
 138         OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
 139             const OCRepresentation& attributeMap, const QueryParamsMap& queryParametersMap,
 140             std::function< void(const OCRepresentation&,const int&)> attributeHandler) { return OC_STACK_OK; }
 141
 142         /**
 143         * Function to set observation on the resource
 144         * @param observeType allows the client to specify how it wants to observe.
 145         * @param queryParametersMap map which can have the query parameter name and value
 146         * @param observeHandler handles callback
 147         *        The callback function will be invoked with a map of attribute name and values.
 148         *        The callback function will also have the result from this observe operation
 149         *        This will have error codes
 150         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 151         * NOTE: OCStackResult is defined in ocstack.h.
 152         */
 153         OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
 154             std::function<void(const OCRepresentation&, const int&, const int&)> observeHandler);
 155
 156         /**
 157         * Function to cancel the observation on the resource
 158         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 159         * NOTE: OCStackResult is defined in ocstack.h.
 160         */
 161         OCStackResult cancelObserve();
 162
 163         /**
 164         * Function to get the host address of this resource
 165         * @return std::string host address
 166         * NOTE: This might or might not be exposed in future due to security concerns
 167         */
 168         std::string host() const;
 169
 170         /**
 171         * Function to get the URI for this resource
 172         * @return std::string resource URI
 173         */
 174         std::string uri() const;
 175
 176         /**
 177         * Function to provide ability to check if this resource is observable or not
 178         * @return bool true indicates resource is observable; false indicates resource is
 179         *         not observable.
 180         */
 181         bool isObservable() const;
 182
 183         /**
 184         * Function to get the list of resource types
 185         * @return vector of resource types
 186         */
 187         std::vector<std::string> getResourceTypes() const
 188         {
 189             return m_resourceTypes;
 190         }
 191
 192         /**
 193         * Function to get the list of resource interfaces
 194         * @return vector of resource interface
 195         */
 196         std::vector<std::string> getResourceInterfaces(void) const
 197         {
 198             return m_interfaces;
 199         }
 200
 201     private:
 202         std::weak_ptr<IClientWrapper> m_clientWrapper;
 203         std::string m_uri;
 204         std::string m_host;
 205         bool m_isObservable;
 206         bool m_isCollection;
 207         std::vector<std::string> m_resourceTypes;
 208         std::vector<std::string> m_interfaces;
 209         std::vector<std::string> m_children;
 210         OCDoHandle m_observeHandle;
 211
 212     private:
 213         OCResource(std::weak_ptr<IClientWrapper> clientWrapper, const std::string& host, const std::string& uri,
 214             bool observable, const std::vector<std::string>& resourceTypes, const std::vector<std::string>& interfaces);
 215     };
 216
 217 } // namespace OC
 218
 219 #endif //__OCRESOURCE_H