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