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     class OCResource;
  44     class OCResourceIdentifier;
  45     std::ostream& operator <<(std::ostream& os, const OCResourceIdentifier& ri);
  46     /**
  47     *  @brief  OCResourceIdentifier represents the identity information for a server. This
  48     *          object combined with the OCResource's URI property uniquely identify an
  49     *          OCResource on or across networks.
  50     *          Equality operators are implemented.  However, internal representation is subject
  51     *          to change and thus should not be accessed or depended on.
  52     */
  53     class OCResourceIdentifier
  54     {
  55         friend class OCResource;
  56         friend std::ostream& operator <<(std::ostream& os, const OCResourceIdentifier& ri);
  57
  58         public:
  59             bool operator==(const OCResourceIdentifier &other) const;
  60
  61             bool operator!=(const OCResourceIdentifier &other) const;
  62
  63             bool operator<(const OCResourceIdentifier &other) const;
  64
  65             bool operator>(const OCResourceIdentifier &other) const;
  66
  67             bool operator<=(const OCResourceIdentifier &other) const;
  68
  69             bool operator>=(const OCResourceIdentifier &other) const;
  70
  71         private:
  72
  73             OCResourceIdentifier(const std::string& wireServerIdentifier,
  74                     const std::string& resourceUri );
  75
  76         private:
  77             uint32_t m_representation;
  78             const std::string& m_resourceUri;
  79     };
  80
  81     /**
  82     *   @brief  OCResource represents an OC resource. A resource could be a light controller,
  83     *           temperature sensor, smoke detector, etc. A resource comes with a well-defined
  84     *           contract or interface onto which you can perform different operations, such as
  85     *           turning on the light, getting the current temperature or subscribing for event
  86     *           notifications from the smoke detector. A resource can be composed of one or
  87     *           more resources.
  88     */
  89     class OCResource
  90     {
  91     friend class OCPlatform_impl;
  92     friend class ListenOCContainer;
  93     public:
  94         typedef std::shared_ptr<OCResource> Ptr;
  95
  96         OCResource(OCResource&&) = default;
  97         OCResource& operator=(OCResource&&) = default;
  98
  99         /**
 100         * Virtual destructor
 101         */
 102         virtual ~OCResource(void);
 103
 104         /**
 105         * Function to get the attributes of a resource.
 106         * @param queryParametersMap map which can have the query parameter name and value
 107         * @param attributeHandler handles callback
 108         *        The callback function will be invoked with a map of attribute name and values.
 109         *        The callback function will also have the result from this Get operation
 110         *        This will have error codes
 111         * @param QualityOfService the quality of communication
 112         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 113         * NOTE: OCStackResult is defined in ocstack.h.
 114         */
 115         OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
 116         OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
 117                           QualityOfService QoS);
 118
 119         /**
 120         * Function to get the attributes of a resource.
 121         *
 122         * @param resourceType resourceType of the resource operate on
 123         * @param resourceInterface interface type of the resource to operate on
 124         * @param queryParametersMap map which can have the query parameter name and value
 125         * @param attributeHandler handles callback
 126         *        The callback function will be invoked with a map of attribute name and values.
 127         *        The callback function will be invoked with a list of URIs if 'get' is invoked on a
 128         *        resource container (list will be empty if not a container)
 129         *        The callback function will also have the result from this Get operation. This will
 130         *        have error codes
 131         * @param QualityOfService the quality of communication
 132         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 133         * NOTE: OCStackResult is defined in ocstack.h.<br>
 134         * <b>Example:</b><br>
 135         * Consider resource "a/home" (with link interface and resource type as home) contains links
 136         *  to "a/kitchen" and "a/room".
 137         * Step 1: get("home", Link_Interface, &onGet)<br>
 138         * Callback onGet will receive a) Empty attribute map because there are no attributes for
 139         * a/home b) list with
 140         * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
 141         * operation<br>
 142         * NOTE: A resource may contain single or multiple resource types. Also, a resource may
 143         * contain single or multiple interfaces.<br>
 144         * Currently, single GET request is allowed to do operate on single resource type or resource
 145         * interface. In future, a single GET <br>
 146         * can operate on multiple resource types and interfaces. <br>
 147         * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned
 148         * resources at a node.<br>
 149         */
 150         OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
 151                         const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
 152         OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
 153                         const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
 154                         QualityOfService QoS);
 155
 156         /**
 157         * Function to set the representation of a resource (via PUT)
 158         * @param representation which can either have all the attribute names and values
 159                  (which will represent entire state of the resource) or a
 160         *        set of attribute names and values which needs to be modified
 161         *        The callback function will be invoked with a map of attribute name and values.
 162         *        The callback function will also have the result from this Put operation
 163         *        This will have error codes
 164         * @param queryParametersMap map which can have the query parameter name and value
 165         * @param attributeHandler attribute handler
 166         * @param QualityOfService the quality of communication
 167         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 168         * NOTE: OCStackResult is defined in ocstack.h.
 169         */
 170         OCStackResult put(const OCRepresentation& representation,
 171                         const QueryParamsMap& queryParametersMap, PutCallback attributeHandler);
 172         OCStackResult put(const OCRepresentation& representation,
 173                         const QueryParamsMap& queryParametersMap, PutCallback attributeHandler,
 174                         QualityOfService QoS);
 175
 176         /**
 177         * Function to set the attributes of a resource (via PUT)
 178         * @param resourceType resource type of the resource to operate on
 179         * @param resourceInterface interface type of the resource to operate on
 180         * @param representation representation of the resource
 181         * @param queryParametersMap Map which can have the query parameter name and value
 182         * @param attributeHandler attribute handler
 183         *        The callback function will be invoked with a map of attribute name and values.
 184         *        The callback function will also have the result from this Put operation
 185         *        This will have error codes.
 186         *        The Representation parameter maps which can either have all the attribute names
 187         *        and values
 188         *        (which will represent entire state of the resource) or a
 189         *        set of attribute names and values which needs to be modified
 190         * @param QualityOfService the quality of communication
 191         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 192         * NOTE: OCStackResult is defined in ocstack.h. <br>
 193         */
 194         OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
 195                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
 196                         PutCallback attributeHandler);
 197         OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
 198                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
 199                         PutCallback attributeHandler, QualityOfService QoS);
 200
 201         /**
 202         * Function to post on a resource
 203         * @param representation which can either have all the attribute names and values
 204                  (which will represent entire state of the resource) or a
 205         *        set of attribute names and values which needs to be modified
 206         *        The callback function will be invoked with a map of attribute name and values.
 207         *        The callback function will also have the result from this Put operation
 208         *        This will have error codes
 209         * @param queryParametersMap map which can have the query parameter name and value
 210         * @param attributeHandler attribute handler
 211         * @param QualityOfService the quality of communication
 212         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 213         * NOTE: OCStackResult is defined in ocstack.h.
 214         */
 215         OCStackResult post(const OCRepresentation& representation,
 216                         const QueryParamsMap& queryParametersMap, PostCallback attributeHandler);
 217         OCStackResult post(const OCRepresentation& representation,
 218                         const QueryParamsMap& queryParametersMap, PostCallback attributeHandler,
 219                         QualityOfService QoS);
 220
 221         /**
 222         * Function to post on a resource
 223         * @param resourceType resource type of the resource to operate on
 224         * @param resourceInterface interface type of the resource to operate on
 225         * @param representation representation of the resource
 226         * @param queryParametersMap Map which can have the query parameter name and value
 227         * @param attributeHandler attribute handler
 228         *        The callback function will be invoked with a map of attribute name and values.
 229         *        The callback function will also have the result from this Put operation
 230         *        This will have error codes.
 231         *        The Representation parameter maps which can either have all the attribute names
 232         *        and values
 233         *        (which will represent entire state of the resource) or a
 234         *        set of attribute names and values which needs to be modified
 235         * @param QualityOfService the quality of communication
 236         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 237         * NOTE: OCStackResult is defined in ocstack.h. <br>
 238         */
 239         OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
 240                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
 241                         PostCallback attributeHandler);
 242         OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
 243                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
 244                         PostCallback attributeHandler, QualityOfService QoS);
 245
 246         /**
 247         * Function to perform DELETE operation
 248         * @param observeHandler handles callback
 249         *        The callback function will have headerOptions and result from this Delete
 250         *        operation. This will have error codes
 251         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 252         * NOTE: OCStackResult is defined in ocstack.h.
 253         */
 254         OCStackResult deleteResource(DeleteCallback deleteHandler);
 255         OCStackResult deleteResource(DeleteCallback deleteHandler, QualityOfService QoS);
 256
 257         /**
 258         * Function to set observation on the resource
 259         * @param observeType allows the client to specify how it wants to observe.
 260         * @param queryParametersMap map which can have the query parameter name and value
 261         * @param observeHandler handles callback
 262         *        The callback function will be invoked with a map of attribute name and values.
 263         *        The callback function will also have the result from this observe operation
 264         *        This will have error codes
 265         * @param QualityOfService the quality of communication
 266         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 267         * NOTE: OCStackResult is defined in ocstack.h.
 268         */
 269         OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
 270                         ObserveCallback observeHandler);
 271         OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
 272                         ObserveCallback observeHandler, QualityOfService qos);
 273
 274         /**
 275         * Function to cancel the observation on the resource
 276         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 277         * NOTE: OCStackResult is defined in ocstack.h.
 278         */
 279         OCStackResult cancelObserve();
 280         OCStackResult cancelObserve(QualityOfService qos);
 281
 282         /**
 283         * Function to set header information.
 284         * @param headerOptions std::vector where header information(header optionID and optionData
 285         * is passed
 286         *
 287         * NOTE: Once the headers information is set, it will be applicable to GET, PUT and observe
 288         * request. <br>
 289         * setHeaderOptions can be used multiple times if headers need to be modifed by the client.
 290         * Latest headers will be used to send in the request. <br>
 291         * NOTE: Initial support is only for two headers. If headerMap consists of more than two
 292         * header options, they will be ignored. <br>
 293         * Use unsetHeaderOptions API to clear the header information.
 294         */
 295         void setHeaderOptions(const HeaderOptions& headerOptions)
 296         {
 297             m_headerOptions = headerOptions;
 298         }
 299
 300         /**
 301         * Function to unset header options.
 302         */
 303         void unsetHeaderOptions()
 304         {
 305             m_headerOptions.clear();
 306         }
 307
 308         /**
 309         * Function to get the host address of this resource
 310         * @return std::string host address
 311         * NOTE: This might or might not be exposed in future due to security concerns
 312         */
 313         std::string host() const;
 314
 315         /**
 316         * Function to get the URI for this resource
 317         * @return std::string resource URI
 318         */
 319         std::string uri() const;
 320
 321         /**
 322         * Function to get the connectivity type of this resource
 323         * @return uint8_t connectivity type
 324         */
 325         OCConnectivityType connectivityType() const;
 326
 327         /**
 328         * Function to provide ability to check if this resource is observable or not
 329         * @return bool true indicates resource is observable; false indicates resource is
 330         *         not observable.
 331         */
 332         bool isObservable() const;
 333
 334         /**
 335         * Function to get the list of resource types
 336         * @return vector of resource types
 337         */
 338         std::vector<std::string> getResourceTypes() const
 339         {
 340             return m_resourceTypes;
 341         }
 342
 343         /**
 344         * Function to get the list of resource interfaces
 345         * @return vector of resource interface
 346         */
 347         std::vector<std::string> getResourceInterfaces(void) const
 348         {
 349             return m_interfaces;
 350         }
 351
 352         // TODO-CA Revisit this since we are exposing two identifiers
 353         /**
 354         * Function to get a unique identifier for this
 355         * resource across network interfaces.  This will
 356         * be guaranteed unique for every resource-per-server
 357         * independent of how this was discovered.
 358         * @return OCResourceIdentifier object, which can
 359         * be used for all comparison and hashing.
 360         */
 361         OCResourceIdentifier uniqueIdentifier() const;
 362
 363         /**
 364         * Function to get a string representation of the resource's server ID.
 365         * This is unique per- server independent on how it was discovered.
 366         * Note: The format of the return value is subject to change and will
 367         * likely change both in size and contents in the future.
 368         */
 369         std::string sid() const;
 370
 371         // overloaded operators allow for putting into a 'set'
 372         // the uniqueidentifier allows for putting into a hash
 373         bool operator==(const OCResource &other) const;
 374
 375         bool operator!=(const OCResource &other) const;
 376
 377         bool operator<(const OCResource &other) const;
 378
 379         bool operator>(const OCResource &other) const;
 380
 381         bool operator<=(const OCResource &other) const;
 382
 383         bool operator>=(const OCResource &other) const;
 384
 385     private:
 386         std::weak_ptr<IClientWrapper> m_clientWrapper;
 387         std::string m_uri;
 388         OCResourceIdentifier m_resourceId;
 389         std::string m_host;
 390         OCConnectivityType m_connectivityType;
 391         bool m_isObservable;
 392         bool m_isCollection;
 393         std::vector<std::string> m_resourceTypes;
 394         std::vector<std::string> m_interfaces;
 395         std::vector<std::string> m_children;
 396         OCDoHandle m_observeHandle;
 397         HeaderOptions m_headerOptions;
 398
 399     private:
 400         OCResource(std::weak_ptr<IClientWrapper> clientWrapper, const std::string& host,
 401             const std::string& uri, const std::string& serverId,
 402             OCConnectivityType m_connectivityType, bool observable,
 403             const std::vector<std::string>& resourceTypes,
 404             const std::vector<std::string>& interfaces);
 405     };
 406
 407 } // namespace OC
 408
 409 #endif //__OCRESOURCE_H
 410