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