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 OIC
  35 {
  36     namespace Service
  37     {
  38         /**
  39          * The states of caching.
  40          *
  41          * @see startCaching
  42          * @see getCacheState
  43          */
  44         enum class CacheState
  45         {
  46             NONE, /**< Caching is not started.*/
  47             UNREADY, /**< Caching is started, but the data is not ready yet.
  48                           This is the default state after startCaching. */
  49             READY, /**< The data is ready.*/
  50             LOST_SIGNAL, /**< Failed to reach the resource. */
  51         };
  52
  53         /**
  54          * The states of monitoring.
  55          *
  56          * @see startMonitoring
  57          * @see getState
  58          */
  59         enum class ResourceState
  60         {
  61             NONE, /**< Monitoring is not started.*/
  62             REQUESTED, /**< Monitoring is started and checking state is in progress.
  63                             This is the default state after startMonitoring. */
  64             ALIVE, /**< The resource is alive. */
  65             LOST_SIGNAL, /**< Failed to reach the resource. */
  66             DESTROYED /**< The resource is deleted. */
  67         };
  68
  69         class PrimitiveResource;
  70
  71         /**
  72          *
  73          * This represents a remote resource and provides simple ways to interact with it.
  74          * Basically this is a client of a remote resource that runs on other device.
  75          *
  76          * The class supports features to help get information of a remote resource
  77          * such as monitoring and caching.
  78          *
  79          * @see RCSDiscoveryManager
  80          *
  81          */
  82         class RCSRemoteResourceObject
  83         {
  84         public:
  85             typedef std::shared_ptr< RCSRemoteResourceObject > Ptr;
  86
  87             /**
  88              * Callback definition to be invoked when monitoring state is changed.
  89              *
  90              * @see startMonitioring
  91              * @see ResourceState
  92              */
  93             typedef std::function< void(ResourceState) > StateChangedCallback;
  94
  95             /**
  96              * Callback definition to be invoked when cache is updated.
  97              *
  98              * @param attrs the updated attributes
  99              */
 100             typedef std::function< void(const RCSResourceAttributes& attrs) > CacheUpdatedCallback;
 101
 102             /**
 103              * Callback definition to be invoked when the response of getRemoteAttributes is
 104              * received.
 105              *
 106              * @param attrs the result attributes
 107              * @param eCode the error code received from the resource
 108              *
 109              * @see getRemoteAttributes
 110              */
 111             typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
 112                 RemoteAttributesGetCallback;
 113
 114             /**
 115              * Callback definition to be invoked when the response of setRemoteAttributes is
 116              * received.
 117              *
 118              * @param attrs the result attributes
 119              * @param eCode the error code received from the resource
 120              *
 121              * @see setRemoteAttributes
 122              */
 123             typedef std::function< void(const RCSResourceAttributes&, int) >
 124                 RemoteAttributesSetCallback;
 125
 126         private:
 127             typedef int CacheID;
 128             typedef unsigned int BrokerID;
 129
 130         public:
 131             //! @cond
 132             RCSRemoteResourceObject(std::shared_ptr< PrimitiveResource >);
 133             //! @endcond
 134
 135             ~RCSRemoteResourceObject();
 136
 137             /**
 138              * Returns whether monitoring is enabled.
 139              *
 140              * @see startMonitoring()
 141              */
 142             bool isMonitoring() const;
 143
 144             /**
 145              * Returns whether caching is enabled.
 146              *
 147              * @see startCaching()
 148              */
 149
 150             bool isCaching() const;
 151
 152             /**
 153              * Returns whether the resource is observable.
 154              *
 155              */
 156             bool isObservable() const;
 157
 158             /**
 159              * Starts monitoring the resource.
 160              *
 161              * Monitoring provides a feature to check the presence of a resource,
 162              * even when the server is not announcing Presence using startPresnece.
 163              *
 164              * @param cb A Callback to get changed resource state.
 165              *
 166              * @throws InvalidParameterException If cb is an empty function or null.
 167              * @throws BadRequestException If monitoring is already started.
 168              *
 169              * @note The callback will be invoked in an internal thread.
 170              *
 171              * @see StateChangedCallback
 172              * @see ResourceState
 173              * @see isMonitoring()
 174              * @see stopMonitoring()
 175              *
 176              */
 177             void startMonitoring(StateChangedCallback cb);
 178
 179             /**
 180              * Stops monitoring the resource.
 181              *
 182              * It does nothing if monitoring is not started.
 183              *
 184              * @see startMonitoring()
 185              *
 186              */
 187             void stopMonitoring();
 188
 189             /**
 190              * Returns the current state of the resource.
 191              *
 192              * @see startMonitoring
 193              */
 194             ResourceState getState() const;
 195
 196             /**
 197              * Starts caching attributes of the resource.
 198              *
 199              * This will start caching for the resource.
 200              * Once caching started it will look for the data updation on the resource
 201              * and updates the cache data accordingly.
 202              *
 203              * It is equivalent to calling startCaching(CacheUpdatedCallback) with an empty function.
 204              *
 205              * @see getCacheState()
 206              * @see getCachedAttributes()
 207              * @see getCachedAttribute(const std::string&) const
 208              *
 209              * @throws BadRequestException
 210              *
 211              */
 212             void startCaching();
 213
 214             /**
 215              * Starts caching attributes for the resource.
 216              *
 217              * This will start data caching for the resource.
 218              * Once caching started it will look for the data updation on the resource and
 219              * updates the cached data accordingly.
 220              *
 221              * @param cb If non-empty function, it will be invoked whenever the cache updated.
 222              *
 223              * @throws BadRequestException If caching is already started.
 224              *
 225              * @note The callback will be invoked in an internal thread.
 226              *
 227              * @see CacheUpdatedCallback
 228              * @see getCacheState()
 229              * @see isCachedAvailable()
 230              * @see getCachedAttributes()
 231              * @see getCachedAttribute(const std::string&) const
 232              *
 233              */
 234             void startCaching(CacheUpdatedCallback cb);
 235
 236             /**
 237              * Stops caching.
 238              *
 239              * It does nothing if caching is not started.
 240              *
 241              * @see startCaching()
 242              * @see startCaching(CacheUpdatedCallback)
 243              */
 244             void stopCaching();
 245
 246             /**
 247              * Returns the current cache state.
 248              *
 249              */
 250             CacheState getCacheState() const;
 251
 252             /**
 253              * Returns whether cached data is available.
 254              *
 255              * Cache will be available always once cache state had been CacheState::READY
 256              * even if current state is CacheState::LOST_SIGNAL.
 257              *
 258              * @see getCacheState()
 259              */
 260             bool isCachedAvailable() const;
 261
 262             /**
 263              * Gets the cached RCSResourceAttributes data.
 264              *
 265              * @pre Cache should be available.
 266              *
 267              * @return The cached attributes.
 268              *
 269              * @throws BadRequestException If the precondition is not fulfilled.
 270              *
 271              * @see RCSResourceAttributes
 272              * @see isCachedAvailable()
 273              * @see startCaching()
 274              * @see startCaching(CacheUpdatedCallback)
 275              *
 276              */
 277             RCSResourceAttributes getCachedAttributes() const;
 278
 279             /**
 280              * Gets a particular cached a ResourceAttribute Value.
 281              *
 282              * @pre Cache should be available.
 283              *
 284              * @return A requested attribute value.
 285              *
 286              * @throws BadRequestException If the precondition is not fulfilled.
 287              * @throws InvalidKeyException If @a key doesn't match the key of any value.
 288              *
 289              * @see RCSResourceAttributes::Value
 290              * @see isCachedAvailable()
 291              * @see startCaching()
 292              * @see startCaching(CacheUpdatedCallback)
 293              *
 294              */
 295             RCSResourceAttributes::Value getCachedAttribute(const std::string& key) const;
 296
 297             /**
 298              * Gets resource attributes directly from the server.
 299              *
 300              * This API send a get request to the resource of interest and provides
 301              * the attributes to the caller in the RemoteAttributesReceivedCallback.
 302              *
 303              * @throws PlatformException If the operation failed
 304              * @throws InvalidParameterException If cb is an empty function or null.
 305              *
 306              * @see RCSResourceAttributes::Value
 307              *
 308              * @note The callback will be invoked in an internal thread.
 309              */
 310             void getRemoteAttributes(RemoteAttributesGetCallback cb);
 311
 312             /**
 313              * Sends a set request with resource attributes to the server.
 314              *
 315              * The SetRequest behavior depends on the server, whether updating its attributes or not.
 316              *
 317              * @param attributes Attributes to set
 318              * @param cb A callback to receive the response.
 319              *
 320              * @throws PlatformException If the operation failed
 321              * @throws InvalidParameterException If cb is an empty function or null.
 322              *
 323              * @see RCSResourceObject
 324              * @see RCSResourceObject::SetRequestHandlerPolicy
 325              *
 326              * @note The callback will be invoked in an internal thread.
 327              */
 328             void setRemoteAttributes(const RCSResourceAttributes& attributes,
 329                     RemoteAttributesSetCallback cb);
 330
 331             /**
 332              * Returns the uri of the resource.
 333              *
 334              */
 335             std::string getUri() const;
 336
 337             /**
 338              * Returns the address of the resource .
 339              *
 340              */
 341             std::string getAddress() const;
 342
 343             /**
 344              * Returns the resource types of the resource.
 345              *
 346              */
 347             std::vector< std::string > getTypes() const;
 348
 349             /**
 350              * Returns the resource interfaces of the resource.
 351              *
 352              */
 353             std::vector< std::string > getInterfaces() const;
 354
 355         private:
 356             std::shared_ptr< PrimitiveResource > m_primitiveResource;
 357             CacheID m_cacheId;
 358             BrokerID m_brokerId;
 359         };
 360     }
 361 }
 362 #endif // RCSREMOTERESOURCEOBJECT_H