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             std::string 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         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 122         * NOTE: OCStackResult is defined in ocstack.h.
 123         */
 124         OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
 125         /**
 126         * Function to get the attributes of a resource.
 127         * @param queryParametersMap map which can have the query parameter name and value
 128         * @param attributeHandler handles callback
 129         *        The callback function will be invoked with a map of attribute name and values.
 130         *        The callback function will also have the result from this Get operation
 131         *        This will have error codes
 132         * @param QoS the quality of communication
 133         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 134         * NOTE: OCStackResult is defined in ocstack.h.
 135         */
 136         OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
 137                           QualityOfService QoS);
 138
 139         /**
 140         * Function to get the attributes of a resource.
 141         *
 142         * @param resourceType resourceType of the resource operate on
 143         * @param resourceInterface interface type of the resource to operate on
 144         * @param queryParametersMap map which can have the query parameter name and value
 145         * @param attributeHandler handles callback
 146         *        The callback function will be invoked with a map of attribute name and values.
 147         *        The callback function will be invoked with a list of URIs if 'get' is invoked on a
 148         *        resource container (list will be empty if not a container)
 149         *        The callback function will also have the result from this Get operation. This will
 150         *        have error codes
 151         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 152         * NOTE: OCStackResult is defined in ocstack.h.<br>
 153         * <b>Example:</b><br>
 154         * Consider resource "a/home" (with link interface and resource type as home) contains links
 155         *  to "a/kitchen" and "a/room".
 156         * Step 1: get("home", Link_Interface, &onGet)<br>
 157         * Callback onGet will receive a) Empty attribute map because there are no attributes for
 158         * a/home b) list with
 159         * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
 160         * operation<br>
 161         * NOTE: A resource may contain single or multiple resource types. Also, a resource may
 162         * contain single or multiple interfaces.<br>
 163         * Currently, single GET request is allowed to do operate on single resource type or resource
 164         * interface. In future, a single GET <br>
 165         * can operate on multiple resource types and interfaces. <br>
 166         * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned
 167         * resources at a node.<br>
 168         */
 169         OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
 170                         const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
 171         /**
 172         * Function to get the attributes of a resource.
 173         *
 174         * @param resourceType resourceType of the resource operate on
 175         * @param resourceInterface interface type of the resource to operate on
 176         * @param queryParametersMap map which can have the query parameter name and value
 177         * @param attributeHandler handles callback
 178         *        The callback function will be invoked with a map of attribute name and values.
 179         *        The callback function will be invoked with a list of URIs if 'get' is invoked on a
 180         *        resource container (list will be empty if not a container)
 181         *        The callback function will also have the result from this Get operation. This will
 182         *        have error codes
 183         * @param QoS the quality of communication
 184         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 185         * NOTE: OCStackResult is defined in ocstack.h.<br>
 186         * <b>Example:</b><br>
 187         * Consider resource "a/home" (with link interface and resource type as home) contains links
 188         *  to "a/kitchen" and "a/room".
 189         * Step 1: get("home", Link_Interface, &onGet)<br>
 190         * Callback onGet will receive a) Empty attribute map because there are no attributes for
 191         * a/home b) list with
 192         * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
 193         * operation<br>
 194         * NOTE: A resource may contain single or multiple resource types. Also, a resource may
 195         * contain single or multiple interfaces.<br>
 196         * Currently, single GET request is allowed to do operate on single resource type or resource
 197         * interface. In future, a single GET <br>
 198         * can operate on multiple resource types and interfaces. <br>
 199         * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned
 200         * resources at a node.<br>
 201         */
 202         OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
 203                         const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
 204                         QualityOfService QoS);
 205
 206         /**
 207         * Function to set the representation of a resource (via PUT)
 208         * @param representation which can either have all the attribute names and values
 209                  (which will represent entire state of the resource) or a
 210         *        set of attribute names and values which needs to be modified
 211         *        The callback function will be invoked with a map of attribute name and values.
 212         *        The callback function will also have the result from this Put operation
 213         *        This will have error codes
 214         * @param queryParametersMap map which can have the query parameter name and value
 215         * @param attributeHandler attribute handler
 216         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 217         * NOTE: OCStackResult is defined in ocstack.h.
 218         */
 219         OCStackResult put(const OCRepresentation& representation,
 220                         const QueryParamsMap& queryParametersMap, PutCallback attributeHandler);
 221         /**
 222         * Function to set the representation of a resource (via PUT)
 223         * @param representation which can either have all the attribute names and values
 224                  (which will represent entire state of the resource) or a
 225         *        set of attribute names and values which needs to be modified
 226         *        The callback function will be invoked with a map of attribute name and values.
 227         *        The callback function will also have the result from this Put operation
 228         *        This will have error codes
 229         * @param queryParametersMap map which can have the query parameter name and value
 230         * @param attributeHandler attribute handler
 231         * @param QoS the quality of communication
 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 put(const OCRepresentation& representation,
 236                         const QueryParamsMap& queryParametersMap, PutCallback attributeHandler,
 237                         QualityOfService QoS);
 238
 239         /**
 240         * Function to set the attributes of a resource (via PUT)
 241         * @param resourceType resource type of the resource to operate on
 242         * @param resourceInterface interface type of the resource to operate on
 243         * @param representation representation of the resource
 244         * @param queryParametersMap Map which can have the query parameter name and value
 245         * @param attributeHandler attribute handler
 246         *        The callback function will be invoked with a map of attribute name and values.
 247         *        The callback function will also have the result from this Put operation
 248         *        This will have error codes.
 249         *        The Representation parameter maps which can either have all the attribute names
 250         *        and values
 251         *        (which will represent entire state of the resource) or a
 252         *        set of attribute names and values which needs to be modified
 253         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 254         * NOTE: OCStackResult is defined in ocstack.h. <br>
 255         */
 256         OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
 257                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
 258                         PutCallback attributeHandler);
 259         /**
 260         * Function to set the attributes of a resource (via PUT)
 261         * @param resourceType resource type of the resource to operate on
 262         * @param resourceInterface interface type of the resource to operate on
 263         * @param representation representation of the resource
 264         * @param queryParametersMap Map which can have the query parameter name and value
 265         * @param attributeHandler attribute handler
 266         *        The callback function will be invoked with a map of attribute name and values.
 267         *        The callback function will also have the result from this Put operation
 268         *        This will have error codes.
 269         *        The Representation parameter maps which can either have all the attribute names
 270         *        and values
 271         *        (which will represent entire state of the resource) or a
 272         *        set of attribute names and values which needs to be modified
 273         * @param QoS the quality of communication
 274         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 275         * NOTE: OCStackResult is defined in ocstack.h. <br>
 276         */
 277         OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
 278                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
 279                         PutCallback attributeHandler, QualityOfService QoS);
 280
 281         /**
 282         * Function to post on a resource
 283         * @param representation which can either have all the attribute names and values
 284         *        (which will represent entire state of the resource) or a
 285         *        set of attribute names and values which needs to be modified
 286         *        The callback function will be invoked with a map of attribute name and values.
 287         *        The callback function will also have the result from this Put operation
 288         *        This will have error codes
 289         * @param queryParametersMap map which can have the query parameter name and value
 290         * @param attributeHandler attribute handler
 291         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 292         * NOTE: OCStackResult is defined in ocstack.h.
 293         */
 294         OCStackResult post(const OCRepresentation& representation,
 295                         const QueryParamsMap& queryParametersMap, PostCallback attributeHandler);
 296         /**
 297         * Function to post on a resource
 298         * @param representation which can either have all the attribute names and values
 299         *        (which will represent entire state of the resource) or a
 300         *        set of attribute names and values which needs to be modified
 301         *        The callback function will be invoked with a map of attribute name and values.
 302         *        The callback function will also have the result from this Put operation
 303         *        This will have error codes
 304         * @param queryParametersMap map which can have the query parameter name and value
 305         * @param attributeHandler attribute handler
 306         * @param QoS the quality of communication
 307         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 308         * NOTE: OCStackResult is defined in ocstack.h.
 309         */
 310         OCStackResult post(const OCRepresentation& representation,
 311                         const QueryParamsMap& queryParametersMap, PostCallback attributeHandler,
 312                         QualityOfService QoS);
 313
 314         /**
 315         * Function to post on a resource
 316         * @param resourceType resource type of the resource to operate on
 317         * @param resourceInterface interface type of the resource to operate on
 318         * @param representation representation of the resource
 319         * @param queryParametersMap Map which can have the query parameter name and value
 320         * @param attributeHandler attribute handler
 321         *        The callback function will be invoked with a map of attribute name and values.
 322         *        The callback function will also have the result from this Put operation
 323         *        This will have error codes.
 324         *        The Representation parameter maps which can either have all the attribute names
 325         *        and values
 326         *        (which will represent entire state of the resource) or a
 327         *        set of attribute names and values which needs to be modified
 328         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 329         * NOTE: OCStackResult is defined in ocstack.h. <br>
 330         */
 331         OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
 332                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
 333                         PostCallback attributeHandler);
 334         /**
 335         * Function to post on a resource
 336         * @param resourceType resource type of the resource to operate on
 337         * @param resourceInterface interface type of the resource to operate on
 338         * @param representation representation of the resource
 339         * @param queryParametersMap Map which can have the query parameter name and value
 340         * @param attributeHandler attribute handler
 341         *        The callback function will be invoked with a map of attribute name and values.
 342         *        The callback function will also have the result from this Put operation
 343         *        This will have error codes.
 344         *        The Representation parameter maps which can either have all the attribute names
 345         *        and values
 346         *        (which will represent entire state of the resource) or a
 347         *        set of attribute names and values which needs to be modified
 348         * @param QoS the quality of communication
 349         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 350         * NOTE: OCStackResult is defined in ocstack.h. <br>
 351         */
 352         OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
 353                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
 354                         PostCallback attributeHandler, QualityOfService QoS);
 355
 356         /**
 357         * Function to perform DELETE operation
 358         * @param deleteHandler handles callback
 359         *        The callback function will have headerOptions and result from this Delete
 360         *        operation. This will have error codes
 361         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 362         * NOTE: OCStackResult is defined in ocstack.h.
 363         */
 364         OCStackResult deleteResource(DeleteCallback deleteHandler);
 365         OCStackResult deleteResource(DeleteCallback deleteHandler, QualityOfService QoS);
 366
 367         /**
 368         * Function to set observation on the resource
 369         * @param observeType allows the client to specify how it wants to observe.
 370         * @param queryParametersMap map which can have the query parameter name and value
 371         * @param observeHandler handles callback
 372         *        The callback function will be invoked with a map of attribute name and values.
 373         *        The callback function will also have the result from this observe operation
 374         *        This will have error codes
 375         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 376         * NOTE: OCStackResult is defined in ocstack.h.
 377         */
 378         OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
 379                         ObserveCallback observeHandler);
 380         /**
 381         * Function to set observation on the resource
 382         * @param observeType allows the client to specify how it wants to observe.
 383         * @param queryParametersMap map which can have the query parameter name and value
 384         * @param observeHandler handles callback
 385         *        The callback function will be invoked with a map of attribute name and values.
 386         *        The callback function will also have the result from this observe operation
 387         *        This will have error codes
 388         * @param qos the quality of communication
 389         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 390         * NOTE: OCStackResult is defined in ocstack.h.
 391         */
 392         OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
 393                         ObserveCallback observeHandler, QualityOfService qos);
 394
 395         /**
 396         * Function to cancel the observation on the resource
 397         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 398         * NOTE: OCStackResult is defined in ocstack.h.
 399         */
 400         OCStackResult cancelObserve();
 401         OCStackResult cancelObserve(QualityOfService qos);
 402
 403         /**
 404         * Function to set header information.
 405         * @param headerOptions std::vector where header information(header optionID and optionData
 406         * is passed
 407         *
 408         * NOTE: Once the headers information is set, it will be applicable to GET, PUT and observe
 409         * request. <br>
 410         * setHeaderOptions can be used multiple times if headers need to be modifed by the client.
 411         * Latest headers will be used to send in the request. <br>
 412         * NOTE: Initial support is only for two headers. If headerMap consists of more than two
 413         * header options, they will be ignored. <br>
 414         * Use unsetHeaderOptions API to clear the header information.
 415         */
 416         void setHeaderOptions(const HeaderOptions& headerOptions)
 417         {
 418             m_headerOptions = headerOptions;
 419         }
 420
 421         /**
 422         * Function to unset header options.
 423         */
 424         void unsetHeaderOptions()
 425         {
 426             m_headerOptions.clear();
 427         }
 428
 429         /**
 430         * Function to get the host address of this resource
 431         * @return std::string host address
 432         * NOTE: This might or might not be exposed in future due to security concerns
 433         */
 434         std::string host() const;
 435
 436         /**
 437         * Function to get the URI for this resource
 438         * @return std::string resource URI
 439         */
 440         std::string uri() const;
 441
 442         /**
 443         * Function to get the connectivity type of this resource
 444         * @return enum connectivity type (flags and adapter)
 445         */
 446         OCConnectivityType connectivityType() const;
 447
 448         /**
 449         * Function to provide ability to check if this resource is observable or not
 450         * @return bool true indicates resource is observable; false indicates resource is
 451         *         not observable.
 452         */
 453         bool isObservable() const;
 454
 455         /**
 456         * Function to get the list of resource types
 457         * @return vector of resource types
 458         */
 459         std::vector<std::string> getResourceTypes() const
 460         {
 461             return m_resourceTypes;
 462         }
 463
 464         /**
 465         * Function to get the list of resource interfaces
 466         * @return vector of resource interface
 467         */
 468         std::vector<std::string> getResourceInterfaces(void) const
 469         {
 470             return m_interfaces;
 471         }
 472
 473         // TODO-CA Revisit this since we are exposing two identifiers
 474         /**
 475         * Function to get a unique identifier for this
 476         * resource across network interfaces.  This will
 477         * be guaranteed unique for every resource-per-server
 478         * independent of how this was discovered.
 479         * @return OCResourceIdentifier object, which can
 480         * be used for all comparison and hashing.
 481         */
 482         OCResourceIdentifier uniqueIdentifier() const;
 483
 484         /**
 485         * Function to get a string representation of the resource's server ID.
 486         * This is unique per- server independent on how it was discovered.
 487         * Note: The format of the return value is subject to change and will
 488         * likely change both in size and contents in the future.
 489         */
 490         std::string sid() const;
 491
 492         // overloaded operators allow for putting into a 'set'
 493         // the uniqueidentifier allows for putting into a hash
 494         bool operator==(const OCResource &other) const;
 495
 496         bool operator!=(const OCResource &other) const;
 497
 498         bool operator<(const OCResource &other) const;
 499
 500         bool operator>(const OCResource &other) const;
 501
 502         bool operator<=(const OCResource &other) const;
 503
 504         bool operator>=(const OCResource &other) const;
 505
 506     private:
 507         void setHost(const std::string& host);
 508         std::weak_ptr<IClientWrapper> m_clientWrapper;
 509         std::string m_uri;
 510         OCResourceIdentifier m_resourceId;
 511         OCDevAddr m_devAddr;
 512         bool m_useHostString;
 513         bool m_isObservable;
 514         bool m_isCollection;
 515         std::vector<std::string> m_resourceTypes;
 516         std::vector<std::string> m_interfaces;
 517         std::vector<std::string> m_children;
 518         OCDoHandle m_observeHandle;
 519         HeaderOptions m_headerOptions;
 520
 521     private:
 522         OCResource(std::weak_ptr<IClientWrapper> clientWrapper,
 523                     const OCDevAddr& devAddr, const std::string& uri,
 524                     const std::string& serverId, bool observable,
 525                     const std::vector<std::string>& resourceTypes,
 526                     const std::vector<std::string>& interfaces);
 527
 528         OCResource(std::weak_ptr<IClientWrapper> clientWrapper,
 529                     const std::string& host, const std::string& uri,
 530                     const std::string& serverId,
 531                     OCConnectivityType connectivityType, bool observable,
 532                     const std::vector<std::string>& resourceTypes,
 533                     const std::vector<std::string>& interfaces);
 534     };
 535
 536 } // namespace OC
 537
 538 #endif //__OCRESOURCE_H
 539