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
 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) > CacheUpdatedCallback;
 191
 192             /**
 193              * Callback definition to be invoked when the response of getRemoteAttributes is
 194              * received.
 195              *
 196              * @param attrs the result attributes
 197              * @param eCode the error code received from the resource
 198              *
 199              * @see getRemoteAttributes
 200              */
 201             typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
 202                 RemoteAttributesGetCallback;
 203
 204             /**
 205              * Callback definition to be invoked when the response of get is received.
 206              *
 207              * @param HeaderOpts
 208              * @param rep the result representation
 209              * @param eCode the error code received from the resource
 210              *
 211              * @see get
 212              */
 213             typedef std::function< void(const HeaderOpts& headerOpts,
 214                     const RCSRepresentation& rep, int eCode) > GetCallback;
 215
 216             /**
 217              * Callback definition to be invoked when the response of setRemoteAttributes is
 218              * received.
 219              *
 220              * @param attrs the result attributes
 221              * @param eCode the error code received from the resource
 222              *
 223              * @see setRemoteAttributes
 224              */
 225             typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
 226                 RemoteAttributesSetCallback;
 227
 228             /**
 229              * Callback definition to be invoked when the response of set is received.
 230              *
 231              * @param HeaderOpts
 232              * @param rep the result representation
 233              * @param eCode the error code received from the resource
 234              *
 235              * @see set
 236              */
 237             typedef std::function< void(const HeaderOpts& headerOpts,
 238                     const RCSRepresentation& rep, int eCode) > SetCallback;
 239
 240         private:
 241             typedef int CacheID;
 242             typedef unsigned int BrokerID;
 243
 244         public:
 245             //! @cond
 246             RCSRemoteResourceObject(std::shared_ptr< PrimitiveResource >);
 247             //! @endcond
 248
 249             ~RCSRemoteResourceObject();
 250
 251             /**
 252              * Creates an instance from an OCResource instance.
 253              *
 254              * @throw RCSInvalidParameterException If ocResource is nullptr.
 255              */
 256             static RCSRemoteResourceObject::Ptr fromOCResource(
 257                     std::shared_ptr< OC::OCResource > ocResource);
 258
 259             /**
 260              * Returns an equivalent OCResource using RCSRemoteResourceObject instance.
 261              *
 262              * @throw RCSInvalidParameterException If rcsResource is nullptr.
 263              */
 264             static std::shared_ptr< OC::OCResource > toOCResource(
 265                     RCSRemoteResourceObject::Ptr rcsResource);
 266
 267             /**
 268              * Returns whether monitoring is enabled.
 269              *
 270              * @see startMonitoring()
 271              */
 272             bool isMonitoring() const;
 273
 274             /**
 275              * Returns whether caching is enabled.
 276              *
 277              * @see startCaching()
 278              */
 279
 280             bool isCaching() const;
 281
 282             /**
 283              * Returns whether the resource is observable.
 284              *
 285              */
 286             bool isObservable() const;
 287
 288             /**
 289              * Starts monitoring the resource.
 290              *
 291              * Monitoring provides a feature to check the presence of a resource,
 292              * even when the server is not announcing Presence using startPresnece.
 293              *
 294              * @param cb A Callback to get changed resource state.
 295              *
 296              * @throws InvalidParameterException If cb is an empty function or null.
 297              * @throws BadRequestException If monitoring is already started.
 298              *
 299              * @note The callback will be invoked in an internal thread.
 300              *
 301              * @see StateChangedCallback
 302              * @see ResourceState
 303              * @see isMonitoring()
 304              * @see stopMonitoring()
 305              *
 306              */
 307             void startMonitoring(StateChangedCallback cb);
 308
 309             /**
 310              * Stops monitoring the resource.
 311              *
 312              * It does nothing if monitoring is not started.
 313              *
 314              * @see startMonitoring()
 315              *
 316              */
 317             void stopMonitoring();
 318
 319             /**
 320              * Returns the current state of the resource.
 321              *
 322              * @see startMonitoring
 323              */
 324             ResourceState getState() const;
 325
 326             /**
 327              * Starts caching attributes of the resource.
 328              *
 329              * This will start caching for the resource.
 330              * Once caching started it will look for the data updation on the resource
 331              * and updates the cache data accordingly.
 332              *
 333              * It is equivalent to calling startCaching(CacheUpdatedCallback) with an empty function.
 334              *
 335              * @see getCacheState()
 336              * @see getCachedAttributes()
 337              * @see getCachedAttribute(const std::string&) const
 338              *
 339              * @throws BadRequestException
 340              *
 341              */
 342             void startCaching();
 343
 344             /**
 345              * Starts caching attributes for the resource.
 346              *
 347              * This will start data caching for the resource.
 348              * Once caching started it will look for the data updation on the resource and
 349              * updates the cached data accordingly.
 350              *
 351              * @param cb If non-empty function, it will be invoked whenever the cache updated.
 352              * @param mode if CacheMode is OBSERVE_ONLY, it will be invoked when receive observe response only.
 353              *
 354              * @throws BadRequestException If caching is already started.
 355              *
 356              * @note The callback will be invoked in an internal thread.
 357              *
 358              * @see CacheUpdatedCallback
 359              * @see getCacheState()
 360              * @see isCachedAvailable()
 361              * @see getCachedAttributes()
 362              * @see getCachedAttribute(const std::string&) const
 363              *
 364              */
 365             void startCaching(CacheUpdatedCallback cb, CacheMode mode = CacheMode::OBSERVE_WITH_POLLING);
 366
 367             /**
 368              * Stops caching.
 369              *
 370              * It does nothing if caching is not started.
 371              *
 372              * @see startCaching()
 373              * @see startCaching(CacheUpdatedCallback)
 374              */
 375             void stopCaching();
 376
 377             /**
 378              * Returns the current cache state.
 379              *
 380              */
 381             CacheState getCacheState() const;
 382
 383             /**
 384              * Returns whether cached data is available.
 385              *
 386              * Cache will be available always once cache state had been CacheState::READY
 387              * even if current state is CacheState::LOST_SIGNAL.
 388              *
 389              * @see getCacheState()
 390              */
 391             bool isCachedAvailable() const;
 392
 393             /**
 394              * Gets the cached RCSResourceAttributes data.
 395              *
 396              * @pre Cache should be available.
 397              *
 398              * @return The cached attributes.
 399              *
 400              * @throws BadRequestException If the precondition is not fulfilled.
 401              *
 402              * @see RCSResourceAttributes
 403              * @see isCachedAvailable()
 404              * @see startCaching()
 405              * @see startCaching(CacheUpdatedCallback)
 406              *
 407              */
 408             RCSResourceAttributes getCachedAttributes() const;
 409
 410             /**
 411              * Gets a particular cached a ResourceAttribute Value.
 412              *
 413              * @pre Cache should be available.
 414              *
 415              * @return A requested attribute value.
 416              *
 417              * @throws BadRequestException If the precondition is not fulfilled.
 418              * @throws InvalidKeyException If @a key doesn't match the key of any value.
 419              *
 420              * @see RCSResourceAttributes::Value
 421              * @see isCachedAvailable()
 422              * @see startCaching()
 423              * @see startCaching(CacheUpdatedCallback)
 424              *
 425              */
 426             RCSResourceAttributes::Value getCachedAttribute(const std::string& key) const;
 427
 428             /**
 429              * Gets resource attributes directly from the server.
 430              *
 431              * This API send a get request to the resource of interest and provides
 432              * the attributes to the caller in the RemoteAttributesGetCallback.
 433              *
 434              * @throws PlatformException If the operation failed
 435              * @throws InvalidParameterException If cb is an empty function or null.
 436              *
 437              * @note The callback will be invoked in an internal thread.
 438              */
 439             void getRemoteAttributes(RemoteAttributesGetCallback cb);
 440
 441             /**
 442              * Gets resource representation with empty query parameters directly from the server.
 443              *
 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(GetCallback cb);
 452
 453             /**
 454              * Gets resource representation directly from the server.
 455              *
 456              * The response could be different by the query parameters, it depends on server.
 457              *
 458              * @param queryParams Query parameters
 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              * @note The callback will be invoked in an internal thread.
 465              */
 466             void get(const RCSQueryParams& queryParams, GetCallback cb);
 467
 468             /**
 469              * Sends a set request with resource attributes to the server.
 470              *
 471              * The SetRequest behavior depends on the server, whether updating its attributes or not.
 472              *
 473              * @param attributes Attributes to set
 474              * @param cb A callback to receive the response.
 475              *
 476              * @throws PlatformException If the operation failed
 477              * @throws InvalidParameterException If cb is an empty function or null.
 478              *
 479              * @see RCSResourceObject
 480              * @see RCSResourceObject::SetRequestHandlerPolicy
 481              *
 482              * @note The callback will be invoked in an internal thread.
 483              */
 484             void setRemoteAttributes(const RCSResourceAttributes& attributes,
 485                     RemoteAttributesSetCallback cb);
 486
 487             /**
 488              * Sends a set request with resource attributes to the server.
 489              *
 490              * The SetRequest behavior depends on query parameters and the server.
 491              *
 492              * @param attributes Attributes to set
 493              * @param cb A callback to receive the response.
 494              *
 495              * @throws PlatformException If the operation failed
 496              * @throws InvalidParameterException If cb is an empty function or null.
 497              *
 498              * @see RCSResourceObject
 499              * @see RCSResourceObject::SetRequestHandlerPolicy
 500              *
 501              * @note The callback will be invoked in an internal thread.
 502              */
 503             void set(const RCSResourceAttributes& attributes, SetCallback cb);
 504
 505             /**
 506              * Sends a set request with resource attributes to the server.
 507              *
 508              * The SetRequest behavior depends on query parameters and the server.
 509              *
 510              * @param queryParams Query parameters
 511              * @param attributes Attributes to set
 512              * @param cb A callback to receive the response.
 513              *
 514              * @throws PlatformException If the operation failed
 515              * @throws InvalidParameterException If cb is an empty function or null.
 516              *
 517              * @see RCSResourceObject
 518              * @see RCSResourceObject::SetRequestHandlerPolicy
 519              *
 520              * @note The callback will be invoked in an internal thread.
 521              */
 522             void set(const RCSQueryParams& queryParams, const RCSResourceAttributes& attributes,
 523                     SetCallback cb);
 524
 525             /**
 526              * Sends a set request with resource representation to the server.
 527              *
 528              * The SetRequest behavior depends on query parameters and the server.
 529              *
 530              * @param queryParams Query parameters
 531              * @param rep Representation to set
 532              * @param cb A callback to receive the response.
 533              *
 534              * @throws PlatformException If the operation failed
 535              * @throws InvalidParameterException If cb is an empty function or null.
 536              *
 537              * @see RCSResourceObject
 538              * @see RCSResourceObject::SetRequestHandlerPolicy
 539              *
 540              * @note The callback will be invoked in an internal thread.
 541              */
 542             void set(const RCSQueryParams& queryParams, const RCSRepresentation &rep,
 543                     SetCallback cb);
 544
 545             /**
 546              * Returns the uri of the resource.
 547              *
 548              */
 549             std::string getUri() const;
 550
 551             /**
 552              * Returns the address of the resource .
 553              *
 554              */
 555             std::string getAddress() const;
 556
 557             /**
 558              * Returns the resource types of the resource.
 559              *
 560              */
 561             std::vector< std::string > getTypes() const;
 562
 563             /**
 564              * Returns the resource interfaces of the resource.
 565              *
 566              */
 567             std::vector< std::string > getInterfaces() const;
 568
 569         private:
 570             std::shared_ptr< PrimitiveResource > m_primitiveResource;
 571             CacheID m_cacheId;
 572             BrokerID m_brokerId;
 573         };
 574     }
 575 }
 576 #endif // RCSREMOTERESOURCEOBJECT_H