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