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