service/resource-encapsulation/include/RCSRemoteResourceObject.h

   1 //******************************************************************
   2 //
   3 // Copyright 2015 Samsung Electronics 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 RCSRemoteResourceObject
  25  */
  26
  27 #ifndef RCSREMOTERESOURCEOBJECT_H
  28 #define RCSREMOTERESOURCEOBJECT_H
  29
  30 #include <vector>
  31
  32 #include "RCSResourceAttributes.h"
  33 #include "RCSRepresentation.h"
  34
  35 namespace OC
  36 {
  37     class OCResource;
  38
  39     namespace HeaderOption
  40     {
  41         class OCHeaderOption;
  42     }
  43 }
  44
  45 namespace OIC
  46 {
  47     namespace Service
  48     {
  49
  50         class RCSRepresentation;
  51
  52         typedef std::vector< OC::HeaderOption::OCHeaderOption > HeaderOpts;
  53
  54         /**
  55          * The states of caching.
  56          *
  57          * @see startCaching
  58          * @see getCacheState
  59          */
  60         enum class CacheState
  61         {
  62             NONE, /**< Caching is not started.*/
  63             UNREADY, /**< Caching is started, but the data is not ready yet.
  64                           This is the default state after startCaching. */
  65             READY, /**< The data is ready.*/
  66             LOST_SIGNAL, /**< Failed to reach the resource. */
  67         };
  68
  69         enum class CacheMode
  70         {
  71             OBSERVE_ONLY,
  72             OBSERVE_WITH_POLLING
  73         };
  74
  75         /**
  76          * The states of monitoring.
  77          *
  78          * @see startMonitoring
  79          * @see getState
  80          */
  81         enum class ResourceState
  82         {
  83             NONE, /**< Monitoring is not started.*/
  84             REQUESTED, /**< Monitoring is started and checking state is in progress.
  85                             This is the default state after startMonitoring. */
  86             ALIVE, /**< The resource is alive. */
  87             LOST_SIGNAL, /**< Failed to reach the resource. */
  88             DESTROYED /**< The resource is deleted. */
  89         };
  90
  91         /**
  92          * The options available to report cache.
  93          *
  94          * @see startCaching
  95          */
  96         enum class CacheReport
  97         {
  98             REPORT_CHANGES, /**< Report only when there is any change in the representation.*/
  99             REPORT_ALL /**< Report all irrespective of the representation.*/
 100         };
 101
 102         class PrimitiveResource;
 103
 104         /**
 105          * This is to specify query parameters for requests to the server.
 106          *
 107          * @see RCSRemoteResourceObject
 108          */
 109         class RCSQueryParams
 110         {
 111         public:
 112             typedef std::unordered_map< std::string, std::string > Map;
 113
 114         public:
 115
 116             /**
 117              * Sets an interface of the resource to operate on
 118              *
 119              * @param interface interface
 120              */
 121             RCSQueryParams& setResourceInterface(std::string interface);
 122
 123             /**
 124              * Sets a resource type of the resource to operate on
 125              *
 126              * @param type resource type
 127              */
 128             RCSQueryParams& setResourceType(std::string type);
 129
 130             /**
 131              * Sets a resource type of the resource to operate on
 132              *
 133              * @param key key to be inserted
 134              * @param value value to be inserted
 135              *
 136              * @note "rt" and "if" are reserved, so you should avoid them as a key.
 137              *
 138              */
 139             RCSQueryParams& put(std::string key, std::string value);
 140
 141             /**
 142              * Returns the resource interface.
 143              */
 144             std::string getResourceInterface() const;
 145
 146             /**
 147              * Returns the resource type.
 148              */
 149             std::string getResourceType() const;
 150
 151             /**
 152              * Returns a value.
 153              *
 154              * @param key key of the element whose mapped value is accessed.
 155              *
 156              * @throws InvalidKeyException If @a key doesn't match the key of any value.
 157              */
 158             std::string get(const std::string& key) const;
 159
 160             /**
 161              * Returns all params.
 162              */
 163             const Map& getAll() const;
 164
 165         private:
 166             std::string m_resourceInterface;
 167             std::string m_resourceType;
 168
 169             std::unordered_map< std::string, std::string > m_map;
 170         };
 171
 172         /**
 173          *
 174          * This represents a remote resource and provides simple ways to interact with it.
 175          * Basically this is a client of a remote resource that runs on other device.
 176          *
 177          * The class supports features to help get information of a remote resource
 178          * such as monitoring and caching.
 179          *
 180          * @see RCSDiscoveryManager
 181          *
 182          */
 183         class RCSRemoteResourceObject : public std::enable_shared_from_this<RCSRemoteResourceObject>
 184         {
 185         public:
 186             typedef std::shared_ptr< RCSRemoteResourceObject > Ptr;
 187
 188             /**
 189              * Callback definition to be invoked when monitoring state is changed.
 190              *
 191              * @see startMonitioring
 192              * @see ResourceState
 193              */
 194             typedef std::function< void(ResourceState) > StateChangedCallback;
 195
 196             /**
 197              * Callback definition to be invoked when cache is updated.
 198              *
 199              * @param attrs the updated attributes
 200              */
 201             typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
 202                 CacheUpdatedCallback;
 203
 204             /**
 205              * Callback definition to be invoked when the response of getRemoteAttributes is
 206              * received.
 207              *
 208              * @param attrs the result attributes
 209              * @param eCode the error code received from the resource
 210              *
 211              * @see getRemoteAttributes
 212              */
 213             typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
 214                 RemoteAttributesGetCallback;
 215
 216             /**
 217              * Callback definition to be invoked when the response of get is received.
 218              *
 219              * @param HeaderOpts
 220              * @param rep the result representation
 221              * @param eCode the error code received from the resource
 222              *
 223              * @see get
 224              */
 225             typedef std::function< void(const HeaderOpts& headerOpts,
 226                     const RCSRepresentation& rep, int eCode) > GetCallback;
 227
 228             /**
 229              * Callback definition to be invoked when the response of setRemoteAttributes is
 230              * received.
 231              *
 232              * @param attrs the result attributes
 233              * @param eCode the error code received from the resource
 234              *
 235              * @see setRemoteAttributes
 236              */
 237             typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
 238                 RemoteAttributesSetCallback;
 239
 240             /**
 241              * Callback definition to be invoked when the response of set is received.
 242              *
 243              * @param HeaderOpts
 244              * @param rep the result representation
 245              * @param eCode the error code received from the resource
 246              *
 247              * @see set
 248              */
 249             typedef std::function< void(const HeaderOpts& headerOpts,
 250                     const RCSRepresentation& rep, int eCode) > SetCallback;
 251
 252         private:
 253             typedef int CacheID;
 254             typedef unsigned int BrokerID;
 255
 256         public:
 257             //! @cond
 258             RCSRemoteResourceObject(std::shared_ptr< PrimitiveResource >);
 259             //! @endcond
 260
 261             ~RCSRemoteResourceObject();
 262
 263             /**
 264              * Creates an instance from an OCResource instance.
 265              *
 266              * @throw RCSInvalidParameterException If ocResource is nullptr.
 267              */
 268             static RCSRemoteResourceObject::Ptr fromOCResource(
 269                     std::shared_ptr< OC::OCResource > ocResource);
 270
 271             /**
 272              * Returns an equivalent OCResource using RCSRemoteResourceObject instance.
 273              *
 274              * @throw RCSInvalidParameterException If rcsResource is nullptr.
 275              */
 276             static std::shared_ptr< OC::OCResource > toOCResource(
 277                     RCSRemoteResourceObject::Ptr rcsResource);
 278
 279             /**
 280              * Returns whether monitoring is enabled.
 281              *
 282              * @see startMonitoring()
 283              */
 284             bool isMonitoring() const;
 285
 286             /**
 287              * Returns whether caching is enabled.
 288              *
 289              * @see startCaching()
 290              */
 291
 292             bool isCaching() const;
 293
 294             /**
 295              * Returns whether the resource is observable.
 296              *
 297              */
 298             bool isObservable() const;
 299
 300             /**
 301              * Starts monitoring the resource.
 302              *
 303              * Monitoring provides a feature to check the presence of a resource,
 304              * even when the server is not announcing Presence using startPresnece.
 305              *
 306              * @param cb A Callback to get changed resource state.
 307              *
 308              * @throws InvalidParameterException If cb is an empty function or null.
 309              * @throws BadRequestException If monitoring is already started.
 310              *
 311              * @note The callback will be invoked in an internal thread.
 312              *
 313              * @see StateChangedCallback
 314              * @see ResourceState
 315              * @see isMonitoring()
 316              * @see stopMonitoring()
 317              *
 318              */
 319             void startMonitoring(StateChangedCallback cb);
 320
 321             /**
 322              * Stops monitoring the resource.
 323              *
 324              * It does nothing if monitoring is not started.
 325              *
 326              * @see startMonitoring()
 327              *
 328              */
 329             void stopMonitoring();
 330
 331             /**
 332              * Returns the current state of the resource.
 333              *
 334              * @see startMonitoring
 335              */
 336             ResourceState getState() const;
 337
 338             /**
 339              * Starts caching attributes of the resource.
 340              *
 341              * This will start caching for the resource.
 342              * Once caching started it will look for the data updation on the resource
 343              * and updates the cache data accordingly.
 344              *
 345              * It is equivalent to calling startCaching(CacheUpdatedCallback) with an empty function.
 346              *
 347              * @see getCacheState()
 348              * @see getCachedAttributes()
 349              * @see getCachedAttribute(const std::string&) const
 350              *
 351              * @throws BadRequestException
 352              *
 353              */
 354             void startCaching();
 355
 356             /**
 357              * Starts caching attributes for the resource.
 358              *
 359              * This will start data caching for the resource.
 360              * Once caching started it will look for the data updation on the resource and
 361              * updates the cached data accordingly.
 362              *
 363              * @param cb If non-empty function, it will be invoked whenever the cache updated.
 364              * @param mode if CacheMode is OBSERVE_ONLY, it will be invoked when receive observe response only.
 365              * @param reportType if CacheReport is REPORT_CHANGES, it will be invoked when observe response has state changes.
 366              *
 367              * @throws BadRequestException If caching is already started.
 368              *
 369              * @note The callback will be invoked in an internal thread.
 370              *
 371              * @see CacheUpdatedCallback
 372              * @see getCacheState()
 373              * @see isCachedAvailable()
 374              * @see getCachedAttributes()
 375              * @see getCachedAttribute(const std::string&) const
 376              *
 377              */
 378             void startCaching(CacheUpdatedCallback cb, CacheMode mode = CacheMode::OBSERVE_WITH_POLLING,
 379                     CacheReport reportType = CacheReport::REPORT_CHANGES);
 380
 381             /**
 382              * Stops caching.
 383              *
 384              * It does nothing if caching is not started.
 385              *
 386              * @see startCaching()
 387              * @see startCaching(CacheUpdatedCallback)
 388              */
 389             void stopCaching();
 390
 391             /**
 392              * Returns the current cache state.
 393              *
 394              */
 395             CacheState getCacheState() const;
 396
 397             /**
 398              * Returns whether cached data is available.
 399              *
 400              * Cache will be available always once cache state had been CacheState::READY
 401              * even if current state is CacheState::LOST_SIGNAL.
 402              *
 403              * @see getCacheState()
 404              */
 405             bool isCachedAvailable() const;
 406
 407             /**
 408              * Gets the cached RCSResourceAttributes data.
 409              *
 410              * @pre Cache should be available.
 411              *
 412              * @return The cached attributes.
 413              *
 414              * @throws BadRequestException If the precondition is not fulfilled.
 415              *
 416              * @see RCSResourceAttributes
 417              * @see isCachedAvailable()
 418              * @see startCaching()
 419              * @see startCaching(CacheUpdatedCallback)
 420              *
 421              */
 422             RCSResourceAttributes getCachedAttributes() const;
 423
 424             /**
 425              * Gets a particular cached a ResourceAttribute Value.
 426              *
 427              * @pre Cache should be available.
 428              *
 429              * @return A requested attribute value.
 430              *
 431              * @throws BadRequestException If the precondition is not fulfilled.
 432              * @throws InvalidKeyException If @a key doesn't match the key of any value.
 433              *
 434              * @see RCSResourceAttributes::Value
 435              * @see isCachedAvailable()
 436              * @see startCaching()
 437              * @see startCaching(CacheUpdatedCallback)
 438              *
 439              */
 440             RCSResourceAttributes::Value getCachedAttribute(const std::string& key) const;
 441
 442             /**
 443              * Gets resource attributes directly from the server.
 444              *
 445              * This API send a get request to the resource of interest and provides
 446              * the attributes to the caller in the RemoteAttributesGetCallback.
 447              *
 448              * @throws PlatformException If the operation failed
 449              * @throws InvalidParameterException If cb is an empty function or null.
 450              *
 451              * @note The callback will be invoked in an internal thread.
 452              */
 453             void getRemoteAttributes(RemoteAttributesGetCallback cb);
 454
 455             /**
 456              * Gets resource representation with empty query parameters directly from the server.
 457              *
 458              * @param cb A callback to receive the response.
 459              *
 460              * @throws PlatformException If the operation failed
 461              * @throws InvalidParameterException If cb is an empty function or null.
 462              *
 463              * @note The callback will be invoked in an internal thread.
 464              */
 465             void get(GetCallback cb);
 466
 467             /**
 468              * Gets resource representation directly from the server.
 469              *
 470              * The response could be different by the query parameters, it depends on server.
 471              *
 472              * @param queryParams Query parameters
 473              * @param cb A callback to receive the response.
 474              *
 475              * @throws PlatformException If the operation failed
 476              * @throws InvalidParameterException If cb is an empty function or null.
 477              *
 478              * @note The callback will be invoked in an internal thread.
 479              */
 480             void get(const RCSQueryParams& queryParams, GetCallback cb);
 481
 482             /**
 483              * Sends a set request with resource attributes to the server.
 484              *
 485              * The SetRequest behavior depends on the server, whether updating its attributes or not.
 486              *
 487              * @param attributes Attributes to set
 488              * @param cb A callback to receive the response.
 489              *
 490              * @throws PlatformException If the operation failed
 491              * @throws InvalidParameterException If cb is an empty function or null.
 492              *
 493              * @see RCSResourceObject
 494              * @see RCSResourceObject::SetRequestHandlerPolicy
 495              *
 496              * @note The callback will be invoked in an internal thread.
 497              */
 498             void setRemoteAttributes(const RCSResourceAttributes& attributes,
 499                     RemoteAttributesSetCallback cb);
 500
 501             /**
 502              * Sends a set request with resource attributes to the server.
 503              *
 504              * The SetRequest behavior depends on query parameters and the server.
 505              *
 506              * @param attributes Attributes to set
 507              * @param cb A callback to receive the response.
 508              *
 509              * @throws PlatformException If the operation failed
 510              * @throws InvalidParameterException If cb is an empty function or null.
 511              *
 512              * @see RCSResourceObject
 513              * @see RCSResourceObject::SetRequestHandlerPolicy
 514              *
 515              * @note The callback will be invoked in an internal thread.
 516              */
 517             void set(const RCSResourceAttributes& attributes, SetCallback cb);
 518
 519             /**
 520              * Sends a set request with resource attributes to the server.
 521              *
 522              * The SetRequest behavior depends on query parameters and the server.
 523              *
 524              * @param queryParams Query parameters
 525              * @param attributes Attributes to set
 526              * @param cb A callback to receive the response.
 527              *
 528              * @throws PlatformException If the operation failed
 529              * @throws InvalidParameterException If cb is an empty function or null.
 530              *
 531              * @see RCSResourceObject
 532              * @see RCSResourceObject::SetRequestHandlerPolicy
 533              *
 534              * @note The callback will be invoked in an internal thread.
 535              */
 536             void set(const RCSQueryParams& queryParams, const RCSResourceAttributes& attributes,
 537                     SetCallback cb);
 538
 539             /**
 540              * Sends a set request with resource representation to the server.
 541              *
 542              * The SetRequest behavior depends on query parameters and the server.
 543              *
 544              * @param queryParams Query parameters
 545              * @param rep Representation to set
 546              * @param cb A callback to receive the response.
 547              *
 548              * @throws PlatformException If the operation failed
 549              * @throws InvalidParameterException If cb is an empty function or null.
 550              *
 551              * @see RCSResourceObject
 552              * @see RCSResourceObject::SetRequestHandlerPolicy
 553              *
 554              * @note The callback will be invoked in an internal thread.
 555              */
 556             void set(const RCSQueryParams& queryParams, const RCSRepresentation &rep,
 557                     SetCallback cb);
 558
 559             /**
 560              * Returns the uri of the resource.
 561              *
 562              */
 563             std::string getUri() const;
 564
 565             /**
 566              * Returns the address of the resource .
 567              *
 568              */
 569             std::string getAddress() const;
 570
 571             /**
 572              * Returns the resource types of the resource.
 573              *
 574              */
 575             std::vector< std::string > getTypes() const;
 576
 577             /**
 578              * Returns the resource interfaces of the resource.
 579              *
 580              */
 581             std::vector< std::string > getInterfaces() const;
 582
 583         private:
 584             std::weak_ptr< RCSRemoteResourceObject > weakFromThis();
 585             std::shared_ptr< PrimitiveResource > m_primitiveResource;
 586             CacheID m_cacheId;
 587             BrokerID m_brokerId;
 588         };
 589     }
 590 }
 591 #endif // RCSREMOTERESOURCEOBJECT_H