include/OCResource.h

   1 //******************************************************************
   2 //
   3 // Copyright 2014 Intel Corporation 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
  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;
  54     friend class InProcClientWrapper;
  55     public:
  56         typedef std::shared_ptr<OCResource> Ptr;
  57
  58         /**
  59         * Virtual destructor
  60         */
  61         virtual ~OCResource(void);
  62
  63         /**
  64         * Function to get the attributes of a resource.
  65         * @param attributeHandler handles callback
  66         *        The callback function will be invoked with a map of attribute name and values.
  67         *        The callback function will also have the result from this Get operation
  68         *        This will have error codes
  69         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
  70         * NOTE: OCStackResult is defined in ocstack.h.
  71         */
  72         OCStackResult get(std::function<void(const AttributeMap, const int)> attributeHandler);
  73
  74         /**
  75         * Function to get the attributes of a resource.
  76         *
  77         * @param resourceType resourceType of the resource operate on
  78         * @param resourceInterface interface type of the resource to operate on
  79         * @param attributeHandler handles callback
  80         *        The callback function will be invoked with a map of attribute name and values.
  81         *        The callback function will be invoked with a list of URIs if 'get' is invoked on a resource container
  82         *        (list will be empty if not a container)
  83         *        The callback function will also have the result from this Get operation. This will have error codes
  84         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
  85         * NOTE: OCStackResult is defined in ocstack.h.<br>
  86         * <b>Example:</b><br>
  87         * Consider resource "a/home" (with link interface and resource type as home) contains links to "a/kitchen" and "a/room".
  88         * Step 1: get("home", Link_Interface, &onGet)<br>
  89         * Callback onGet will receive a) Empty attribute map because there are no attributes for a/home b) list with
  90         * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET operation<br>
  91         * NOTE: A resource may contain single or multiple resource types. Also, a resource may contain single or multiple interfaces.<br>
  92         * Currently, single GET request is allowed to do operate on single resource type or resource interface. In future, a single GET <br>
  93         * can operate on multiple resource types and interfaces. <br>
  94         * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned resources at a node.<br>
  95         * TODO: Implementation
  96         */
  97         OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
  98             std::function<void(const AttributeMap& attributeMap, const std::vector<std::string>& resourceUriList, const int& errorCode)> attributeHandler) { return OC_STACK_OK; }
  99
 100         /**
 101         * Function to set the attributes of a resource (via PUT)
 102         * @param AttributeMap Map which can either have all the attribute names and values
 103                  (which will represent entire state of the resource) or a
 104         *        set of attribute names and values which needs to be modified
 105         *        The callback function will be invoked with a map of attribute name and values.
 106         *        The callback function will also have the result from this Put operation
 107         *        This will have error codes
 108         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 109         * NOTE: OCStackResult is defined in ocstack.h.
 110         */
 111         OCStackResult put(const AttributeMap& attributeMap, const QueryParamsMap& queryParametersMap, std::function< void(const AttributeMap,const int)> attributeHandler);
 112
 113         /**
 114         * Function to set the attributes of a resource (via PUT)
 115         * @param resourceType resource type of the resource to operate on
 116         * @param resourceInterface interface type of the resource to operate on
 117         * @param AttributeMap Map which can either have all the attribute names and values
 118         *        (which will represent entire state of the resource) or a
 119         *        set of attribute names and values which needs to be modified
 120         * @param QueryParamsMap Map which can have the query parameter name and value
 121         * @param attributeHandler
 122         *        The callback function will be invoked with a map of attribute name and values.
 123         *        The callback function will also have the result from this Put operation
 124         *        This will have error codes
 125         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 126         * NOTE: OCStackResult is defined in ocstack.h. <br>
 127         * TODO: consider to input hrefs for resource collection
 128         * TODO: Implementation
 129         */
 130         OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
 131             const AttributeMap& attributeMap, const QueryParamsMap& queryParametersMap, std::function< void(const AttributeMap&,const int&)> attributeHandler) { return OC_STACK_OK; }
 132
 133         /**
 134         * Function to set observation on the resource
 135         * @param observeType allows the client to specify how it wants to observe.
 136         * @param observeHandler handles callback
 137         *        The callback function will be invoked with a map of attribute name and values.
 138         *        The callback function will also have the result from this observe operation
 139         *        This will have error codes
 140         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 141         * NOTE: OCStackResult is defined in ocstack.h.
 142         */
 143         OCStackResult observe(ObserveType observeType, std::function<void(const AttributeMap&, const int&, const int&)> observeHandler);
 144
 145         /**
 146         * Function to cancel the observation on the resource
 147         * @param observeCancellationHandler handles callback
 148         *        The callback function will also have the result from this 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 cancelObserve();
 154
 155         /**
 156         * Function to get the host address of this resource
 157         * @return std::string host address
 158         * NOTE: This might or might not be exposed in future due to security concerns
 159         */
 160         std::string host() const;
 161
 162         /**
 163         * Function to get the URI for this resource
 164         * @return std::string resource URI
 165         */
 166         std::string uri() const;
 167
 168         /**
 169         * Function to provide ability to check if this resource is observable or not
 170         * @return bool true indicates resource is observable; false indicates resource is
 171         *         not observable.
 172         */
 173         bool isObservable() const;
 174
 175         // bool whether this is a collection type, and will have children that can be queried
 176         //bool isCollection() const {return m_isCollection;}
 177         // a collection of the resource-type names
 178         //const std::vector<std::string> resourceTypes() const {return m_resourceTypes;}
 179         // a collection of the interfaces supported by this resource
 180         //const std::vector<std::string> interfaces() const { return m_interfaces;}
 181         // a collection of property objects that allow calling of properties on this Resource
 182         //const std::vector<std::string> properties() const { return m_properties;}
 183         // a collection of the names of the children of this resource, assuming it supports a collection interface
 184         //const std::vector<std::string> children() const {return m_children;}
 185
 186         /*void post(const AttributeMap&, std::function<void(const int&)> attributeHandler);
 187
 188         NOTE: dont expose the host ip .. so some kind of handle is required
 189         static OCResource::Ptr getResource(const std::string& host, const std::string& resourceURI, const std::string& resourceName,
 190             const std::string interfaceName, bool observerable);*/
 191
 192
 193     private:
 194         IClientWrapper::Ptr m_clientWrapper;
 195         std::string m_uri;
 196         std::string m_host;
 197         bool m_isObservable;
 198         bool m_isCollection;
 199         std::vector<std::string> m_resourceTypes;
 200         std::vector<std::string> m_interfaces;
 201         std::vector<std::string> m_children;
 202         AttributeMap m_attributeMap;
 203         OCDoHandle m_observeHandle;
 204
 205     private:
 206         OCResource(IClientWrapper::Ptr clientWrapper, const std::string& host, const std::string& uri,
 207             bool observable, const std::vector<std::string>& resourceTypes, const std::vector<std::string>& interfaces);
 208     };
 209
 210 } // namespace OC
 211
 212 #endif //__OCRESOURCE_H