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