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         class RCSQueryParams
  87         {
  88         public:
  89             typedef std::unordered_map< std::string, std::string > Map;
  90
  91         public:
  92             RCSQueryParams& setResourceInterface(const std::string&);
  93             RCSQueryParams& setResourceInterface(std::string&&);
  94
  95             RCSQueryParams& setResuorceType(const std::string&);
  96             RCSQueryParams& setResuorceType(std::string&&);
  97
  98             RCSQueryParams& put(const std::string&, const std::string&);
  99             RCSQueryParams& put(std::string&&, std::string&&);
 100             RCSQueryParams& put(const std::string&, std::string&&);
 101             RCSQueryParams& put(std::string&&, const std::string&);
 102
 103             std::string getResourceInterface() const;
 104             std::string getResourceType() const;
 105             std::string get(const std::string&) const;
 106
 107             const Map& getAll() const;
 108
 109         private:
 110             std::string m_resourceInterface;
 111             std::string m_resourceType;
 112
 113             std::unordered_map< std::string, std::string > m_map;
 114         };
 115
 116         /**
 117          *
 118          * This represents a remote resource and provides simple ways to interact with it.
 119          * Basically this is a client of a remote resource that runs on other device.
 120          *
 121          * The class supports features to help get information of a remote resource
 122          * such as monitoring and caching.
 123          *
 124          * @see RCSDiscoveryManager
 125          *
 126          */
 127         class RCSRemoteResourceObject
 128         {
 129         public:
 130             typedef std::shared_ptr< RCSRemoteResourceObject > Ptr;
 131
 132             /**
 133              * Callback definition to be invoked when monitoring state is changed.
 134              *
 135              * @see startMonitioring
 136              * @see ResourceState
 137              */
 138             typedef std::function< void(ResourceState) > StateChangedCallback;
 139
 140             /**
 141              * Callback definition to be invoked when cache is updated.
 142              *
 143              * @param attrs the updated attributes
 144              */
 145             typedef std::function< void(const RCSResourceAttributes& attrs) > CacheUpdatedCallback;
 146
 147             /**
 148              * Callback definition to be invoked when the response of getRemoteAttributes is
 149              * received.
 150              *
 151              * @param attrs the result attributes
 152              * @param eCode the error code received from the resource
 153              *
 154              * @see getRemoteAttributes
 155              */
 156             typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
 157                 RemoteAttributesGetCallback;
 158
 159             typedef std::function< void(const HeaderOpts&, const RCSRepresentation& rep, int eCode) >
 160                 GetCallback;
 161
 162             /**
 163              * Callback definition to be invoked when the response of setRemoteAttributes is
 164              * received.
 165              *
 166              * @param attrs the result attributes
 167              * @param eCode the error code received from the resource
 168              *
 169              * @see setRemoteAttributes
 170              */
 171             typedef std::function< void(const RCSResourceAttributes&, int) >
 172                 RemoteAttributesSetCallback;
 173
 174             typedef std::function< void(const HeaderOpts&, const RCSRepresentation& rep, int eCode) >
 175                 SetCallback;
 176
 177         private:
 178             typedef int CacheID;
 179             typedef unsigned int BrokerID;
 180
 181         public:
 182             //! @cond
 183             RCSRemoteResourceObject(std::shared_ptr< PrimitiveResource >);
 184             //! @endcond
 185
 186             ~RCSRemoteResourceObject();
 187
 188             static RCSRemoteResourceObject::Ptr fromOCResource(std::shared_ptr< OC::OCResource >);
 189
 190             /**
 191              * Returns whether monitoring is enabled.
 192              *
 193              * @see startMonitoring()
 194              */
 195             bool isMonitoring() const;
 196
 197             /**
 198              * Returns whether caching is enabled.
 199              *
 200              * @see startCaching()
 201              */
 202
 203             bool isCaching() const;
 204
 205             /**
 206              * Returns whether the resource is observable.
 207              *
 208              */
 209             bool isObservable() const;
 210
 211             /**
 212              * Starts monitoring the resource.
 213              *
 214              * Monitoring provides a feature to check the presence of a resource,
 215              * even when the server is not announcing Presence using startPresnece.
 216              *
 217              * @param cb A Callback to get changed resource state.
 218              *
 219              * @throws InvalidParameterException If cb is an empty function or null.
 220              * @throws BadRequestException If monitoring is already started.
 221              *
 222              * @note The callback will be invoked in an internal thread.
 223              *
 224              * @see StateChangedCallback
 225              * @see ResourceState
 226              * @see isMonitoring()
 227              * @see stopMonitoring()
 228              *
 229              */
 230             void startMonitoring(StateChangedCallback cb);
 231
 232             /**
 233              * Stops monitoring the resource.
 234              *
 235              * It does nothing if monitoring is not started.
 236              *
 237              * @see startMonitoring()
 238              *
 239              */
 240             void stopMonitoring();
 241
 242             /**
 243              * Returns the current state of the resource.
 244              *
 245              * @see startMonitoring
 246              */
 247             ResourceState getState() const;
 248
 249             /**
 250              * Starts caching attributes of the resource.
 251              *
 252              * This will start caching for the resource.
 253              * Once caching started it will look for the data updation on the resource
 254              * and updates the cache data accordingly.
 255              *
 256              * It is equivalent to calling startCaching(CacheUpdatedCallback) with an empty function.
 257              *
 258              * @see getCacheState()
 259              * @see getCachedAttributes()
 260              * @see getCachedAttribute(const std::string&) const
 261              *
 262              * @throws BadRequestException
 263              *
 264              */
 265             void startCaching();
 266
 267             /**
 268              * Starts caching attributes for the resource.
 269              *
 270              * This will start data caching for the resource.
 271              * Once caching started it will look for the data updation on the resource and
 272              * updates the cached data accordingly.
 273              *
 274              * @param cb If non-empty function, it will be invoked whenever the cache updated.
 275              *
 276              * @throws BadRequestException If caching is already started.
 277              *
 278              * @note The callback will be invoked in an internal thread.
 279              *
 280              * @see CacheUpdatedCallback
 281              * @see getCacheState()
 282              * @see isCachedAvailable()
 283              * @see getCachedAttributes()
 284              * @see getCachedAttribute(const std::string&) const
 285              *
 286              */
 287             void startCaching(CacheUpdatedCallback cb);
 288
 289             /**
 290              * Stops caching.
 291              *
 292              * It does nothing if caching is not started.
 293              *
 294              * @see startCaching()
 295              * @see startCaching(CacheUpdatedCallback)
 296              */
 297             void stopCaching();
 298
 299             /**
 300              * Returns the current cache state.
 301              *
 302              */
 303             CacheState getCacheState() const;
 304
 305             /**
 306              * Returns whether cached data is available.
 307              *
 308              * Cache will be available always once cache state had been CacheState::READY
 309              * even if current state is CacheState::LOST_SIGNAL.
 310              *
 311              * @see getCacheState()
 312              */
 313             bool isCachedAvailable() const;
 314
 315             /**
 316              * Gets the cached RCSResourceAttributes data.
 317              *
 318              * @pre Cache should be available.
 319              *
 320              * @return The cached attributes.
 321              *
 322              * @throws BadRequestException If the precondition is not fulfilled.
 323              *
 324              * @see RCSResourceAttributes
 325              * @see isCachedAvailable()
 326              * @see startCaching()
 327              * @see startCaching(CacheUpdatedCallback)
 328              *
 329              */
 330             RCSResourceAttributes getCachedAttributes() const;
 331
 332             /**
 333              * Gets a particular cached a ResourceAttribute Value.
 334              *
 335              * @pre Cache should be available.
 336              *
 337              * @return A requested attribute value.
 338              *
 339              * @throws BadRequestException If the precondition is not fulfilled.
 340              * @throws InvalidKeyException If @a key doesn't match the key of any value.
 341              *
 342              * @see RCSResourceAttributes::Value
 343              * @see isCachedAvailable()
 344              * @see startCaching()
 345              * @see startCaching(CacheUpdatedCallback)
 346              *
 347              */
 348             RCSResourceAttributes::Value getCachedAttribute(const std::string& key) const;
 349
 350             /**
 351              * Gets resource attributes directly from the server.
 352              *
 353              * This API send a get request to the resource of interest and provides
 354              * the attributes to the caller in the RemoteAttributesReceivedCallback.
 355              *
 356              * @throws PlatformException If the operation failed
 357              * @throws InvalidParameterException If cb is an empty function or null.
 358              *
 359              * @see RCSResourceAttributes::Value
 360              *
 361              * @note The callback will be invoked in an internal thread.
 362              */
 363             void getRemoteAttributes(RemoteAttributesGetCallback cb);
 364
 365             void get(GetCallback cb);
 366             void get(const RCSQueryParams&, GetCallback cb);
 367
 368             /**
 369              * Sends a set request with resource attributes to the server.
 370              *
 371              * The SetRequest behavior depends on the server, whether updating its attributes or not.
 372              *
 373              * @param attributes Attributes to set
 374              * @param cb A callback to receive the response.
 375              *
 376              * @throws PlatformException If the operation failed
 377              * @throws InvalidParameterException If cb is an empty function or null.
 378              *
 379              * @see RCSResourceObject
 380              * @see RCSResourceObject::SetRequestHandlerPolicy
 381              *
 382              * @note The callback will be invoked in an internal thread.
 383              */
 384             void setRemoteAttributes(const RCSResourceAttributes& attributes,
 385                     RemoteAttributesSetCallback cb);
 386
 387             void set(const RCSResourceAttributes& attributes, SetCallback cb);
 388             void set(const RCSQueryParams&, const RCSResourceAttributes& attributes,  SetCallback cb);
 389
 390             /**
 391              * Returns the uri of the resource.
 392              *
 393              */
 394             std::string getUri() const;
 395
 396             /**
 397              * Returns the address of the resource .
 398              *
 399              */
 400             std::string getAddress() const;
 401
 402             /**
 403              * Returns the resource types of the resource.
 404              *
 405              */
 406             std::vector< std::string > getTypes() const;
 407
 408             /**
 409              * Returns the resource interfaces of the resource.
 410              *
 411              */
 412             std::vector< std::string > getInterfaces() const;
 413
 414         private:
 415             std::shared_ptr< PrimitiveResource > m_primitiveResource;
 416             CacheID m_cacheId;
 417             BrokerID m_brokerId;
 418         };
 419     }
 420 }
 421 #endif // RCSREMOTERESOURCEOBJECT_H