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