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 Resource Client APIs provided to the developers.
  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              * Typedef for callback of startMonitoring API
  89              *
  90              * @see ResourceState
  91              */
  92             typedef std::function< void(ResourceState) > StateChangedCallback;
  93
  94             /**
  95              * Typedef for callback of startCaching API
  96              *
  97              * @see RCSResourceAttributes
  98              */
  99             typedef std::function< void(const RCSResourceAttributes&) > CacheUpdatedCallback;
 100
 101             /**
 102              * Typedef for callback of getRemoteAttributes API
 103              *
 104              * @see RCSResourceAttributes
 105              */
 106             typedef std::function< void(const RCSResourceAttributes&, int) >
 107                 RemoteAttributesGetCallback;
 108
 109             /**
 110              * Typedef for callback of setRemoteAttributes API
 111              *
 112              * @see RCSResourceAttributes
 113              */
 114             typedef std::function< void(const RCSResourceAttributes&, int) >
 115                 RemoteAttributesSetCallback;
 116
 117         private:
 118             typedef int CacheID;
 119             typedef unsigned int BrokerID;
 120
 121         public:
 122             //! @cond
 123             RCSRemoteResourceObject(std::shared_ptr< PrimitiveResource >);
 124             //! @endcond
 125
 126             ~RCSRemoteResourceObject();
 127
 128             /**
 129              * Returns whether monitoring is enabled.
 130              *
 131              * @see startMonitoring()
 132              */
 133             bool isMonitoring() const;
 134
 135             /**
 136              * Returns whether caching is enabled.
 137              *
 138              * @see startCaching()
 139              */
 140
 141             bool isCaching() const;
 142
 143             /**
 144              * Returns whether the resource is observable.
 145              *
 146              */
 147             bool isObservable() const;
 148
 149             /**
 150              * Starts monitoring the resource.
 151              *
 152              * Monitoring provides a feature to check the presence of a resource,
 153              * even when the server is not announcing Presence using startPresnece.
 154              *
 155              * @param cb A Callback to get changed resource state.
 156              *
 157              * @throws InvalidParameterException If cb is an empty function or null.
 158              * @throws BadRequestException If monitoring is already started.
 159              *
 160              * @note The callback will be invoked in an internal thread.
 161              *
 162              * @see StateChangedCallback
 163              * @see ResourceState
 164              * @see isMonitoring()
 165              * @see stopMonitoring()
 166              *
 167              */
 168             void startMonitoring(StateChangedCallback cb);
 169
 170             /**
 171              * Stops monitoring the resource.
 172              *
 173              * It does nothing if monitoring is not started.
 174              *
 175              * @see startMonitoring()
 176              *
 177              */
 178             void stopMonitoring();
 179
 180             /**
 181              * Returns the current state of the resource.
 182              *
 183              * @see startMonitoring
 184              */
 185             ResourceState getState() const;
 186
 187             /**
 188              * Starts caching attributes of the resource.
 189              *
 190              * This will start caching for the resource.
 191              * Once caching started it will look for the data updation on the resource
 192              * and updates the cache data accordingly.
 193              *
 194              * It is equivalent to calling startCaching(CacheUpdatedCallback) with an empty function.
 195              *
 196              * @see getCacheState()
 197              * @see getCachedAttributes()
 198              * @see getCachedAttribute(const std::string&) const
 199              *
 200              * @throws BadRequestException
 201              *
 202              */
 203             void startCaching();
 204
 205             /**
 206              * Starts caching attributes for the resource.
 207              *
 208              * This will start data caching for the resource.
 209              * Once caching started it will look for the data updation on the resource and
 210              * updates the cached data accordingly.
 211              *
 212              * @param cb If non-empty function, it will be invoked whenever the cache updated.
 213              *
 214              * @throws BadRequestException If caching is already started.
 215              *
 216              * @note The callback will be invoked in an internal thread.
 217              *
 218              * @see CacheUpdatedCallback
 219              * @see getCacheState()
 220              * @see isCachedAvailable()
 221              * @see getCachedAttributes()
 222              * @see getCachedAttribute(const std::string&) const
 223              *
 224              */
 225             void startCaching(CacheUpdatedCallback cb);
 226
 227             /**
 228              * Stops caching.
 229              *
 230              * It does nothing if caching is not started.
 231              *
 232              * @see startCaching()
 233              * @see startCaching(CacheUpdatedCallback)
 234              */
 235             void stopCaching();
 236
 237             /**
 238              * Returns the current cache state.
 239              *
 240              */
 241             CacheState getCacheState() const;
 242
 243             /**
 244              * Returns whether cached data is available.
 245              *
 246              * Cache will be available always once cache state had been CacheState::READY
 247              * even if current state is CacheState::LOST_SIGNAL.
 248              *
 249              * @see getCacheState()
 250              */
 251             bool isCachedAvailable() const;
 252
 253             /**
 254              * Gets the cached RCSResourceAttributes data.
 255              *
 256              * @pre Cache should be available.
 257              *
 258              * @return The cached attributes.
 259              *
 260              * @throws BadRequestException If the precondition is not fulfilled.
 261              *
 262              * @see RCSResourceAttributes
 263              * @see isCachedAvailable()
 264              * @see startCaching()
 265              * @see startCaching(CacheUpdatedCallback)
 266              *
 267              */
 268             RCSResourceAttributes getCachedAttributes() const;
 269
 270             /**
 271              * Gets a particular cached a ResourceAttribute Value.
 272              *
 273              * @pre Cache should be available.
 274              *
 275              * @return A requested attribute value.
 276              *
 277              * @throws BadRequestException If the precondition is not fulfilled.
 278              * @throws InvalidKeyException If @a key doesn't match the key of any value.
 279              *
 280              * @see RCSResourceAttributes::Value
 281              * @see isCachedAvailable()
 282              * @see startCaching()
 283              * @see startCaching(CacheUpdatedCallback)
 284              *
 285              */
 286             RCSResourceAttributes::Value getCachedAttribute(const std::string& key) const;
 287
 288             /**
 289              * Gets resource attributes directly from the server.
 290              *
 291              * This API send a get request to the resource of interest and provides
 292              * the attributes to the caller in the RemoteAttributesReceivedCallback.
 293              *
 294              * @throws PlatformException If the operation failed
 295              * @throws InvalidParameterException If cb is an empty function or null.
 296              *
 297              * @see RCSResourceAttributes::Value
 298              *
 299              * @note The callback will be invoked in an internal thread.
 300              */
 301             void getRemoteAttributes(RemoteAttributesGetCallback cb);
 302
 303             /**
 304              * Sends a set request with resource attributes to the server.
 305              *
 306              * The SetRequest behavior depends on the server, whether updating its attributes or not.
 307              *
 308              * @param attributes Attributes to set
 309              * @param cb A callback to receive the response.
 310              *
 311              * @throws PlatformException If the operation failed
 312              * @throws InvalidParameterException If cb is an empty function or null.
 313              *
 314              * @see RCSResourceObject
 315              * @see RCSResourceObject::SetRequestHandlerPolicy
 316              *
 317              * @note The callback will be invoked in an internal thread.
 318              */
 319             void setRemoteAttributes(const RCSResourceAttributes& attributes,
 320                     RemoteAttributesSetCallback cb);
 321
 322             /**
 323              * Returns the uri of the resource.
 324              *
 325              */
 326             std::string getUri() const;
 327
 328             /**
 329              * Returns the address of the resource .
 330              *
 331              */
 332             std::string getAddress() const;
 333
 334             /**
 335              * Returns the resource types of the resource.
 336              *
 337              */
 338             std::vector< std::string > getTypes() const;
 339
 340             /**
 341              * Returns the resource interfaces of the resource.
 342              *
 343              */
 344             std::vector< std::string > getInterfaces() const;
 345
 346         private:
 347             std::shared_ptr< PrimitiveResource > m_primitiveResource;
 348             CacheID m_cacheId;
 349             BrokerID m_brokerId;
 350         };
 351     }
 352 }
 353 #endif // RCSREMOTERESOURCEOBJECT_H