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