1 //******************************************************************
3 // Copyright 2015 Samsung Electronics All Rights Reserved.
5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
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
11 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
24 * This file contains the declaration of classes and its members related to RCSRemoteResourceObject
27 #ifndef RCSREMOTERESOURCEOBJECT_H
28 #define RCSREMOTERESOURCEOBJECT_H
32 #include "RCSResourceAttributes.h"
33 #include "RCSRepresentation.h"
39 namespace HeaderOption
50 class RCSRepresentation;
52 typedef std::vector< OC::HeaderOption::OCHeaderOption > HeaderOpts;
55 * The states of caching.
62 NONE, /**< Caching is not started.*/
63 UNREADY, /**< Caching is started, but the data is not ready yet.
64 This is the default state after startCaching. */
65 READY, /**< The data is ready.*/
66 LOST_SIGNAL, /**< Failed to reach the resource. */
70 * The states of monitoring.
72 * @see startMonitoring
75 enum class ResourceState
77 NONE, /**< Monitoring is not started.*/
78 REQUESTED, /**< Monitoring is started and checking state is in progress.
79 This is the default state after startMonitoring. */
80 ALIVE, /**< The resource is alive. */
81 LOST_SIGNAL, /**< Failed to reach the resource. */
82 DESTROYED /**< The resource is deleted. */
85 class PrimitiveResource;
88 * This is to specify query parameters for requests to the server.
90 * @see RCSRemoteResourceObject
95 typedef std::unordered_map< std::string, std::string > Map;
100 * Sets an interface of the resource to operate on
102 * @param interface interface
104 RCSQueryParams& setResourceInterface(std::string interface);
107 * Sets a resource type of the resource to operate on
109 * @param type resource type
111 RCSQueryParams& setResourceType(std::string type);
114 * Sets a resource type of the resource to operate on
116 * @param key key to be inserted
117 * @param value value to be inserted
119 * @note "rt" and "if" are reserved, so you should avoid them as a key.
122 RCSQueryParams& put(std::string key, std::string value);
125 * Returns the resource interface.
127 std::string getResourceInterface() const;
130 * Returns the resource type.
132 std::string getResourceType() const;
137 * @param key key of the element whose mapped value is accessed.
139 * @throws InvalidKeyException If @a key doesn't match the key of any value.
141 std::string get(const std::string& key) const;
144 * Returns all params.
146 const Map& getAll() const;
149 std::string m_resourceInterface;
150 std::string m_resourceType;
152 std::unordered_map< std::string, std::string > m_map;
157 * This represents a remote resource and provides simple ways to interact with it.
158 * Basically this is a client of a remote resource that runs on other device.
160 * The class supports features to help get information of a remote resource
161 * such as monitoring and caching.
163 * @see RCSDiscoveryManager
166 class RCSRemoteResourceObject
169 typedef std::shared_ptr< RCSRemoteResourceObject > Ptr;
172 * Callback definition to be invoked when monitoring state is changed.
174 * @see startMonitioring
177 typedef std::function< void(ResourceState) > StateChangedCallback;
180 * Callback definition to be invoked when cache is updated.
182 * @param attrs the updated attributes
184 typedef std::function< void(const RCSResourceAttributes& attrs) > CacheUpdatedCallback;
187 * Callback definition to be invoked when the response of getRemoteAttributes is
190 * @param attrs the result attributes
191 * @param eCode the error code received from the resource
193 * @see getRemoteAttributes
195 typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
196 RemoteAttributesGetCallback;
199 * Callback definition to be invoked when the response of get is received.
202 * @param rep the result representation
203 * @param eCode the error code received from the resource
207 typedef std::function< void(const HeaderOpts& headerOpts,
208 const RCSRepresentation& rep, int eCode) > GetCallback;
211 * Callback definition to be invoked when the response of setRemoteAttributes is
214 * @param attrs the result attributes
215 * @param eCode the error code received from the resource
217 * @see setRemoteAttributes
219 typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
220 RemoteAttributesSetCallback;
223 * Callback definition to be invoked when the response of set is received.
226 * @param rep the result representation
227 * @param eCode the error code received from the resource
231 typedef std::function< void(const HeaderOpts& headerOpts,
232 const RCSRepresentation& rep, int eCode) > SetCallback;
236 typedef unsigned int BrokerID;
240 RCSRemoteResourceObject(std::shared_ptr< PrimitiveResource >);
243 ~RCSRemoteResourceObject();
246 * Creates an instance from an OCResource instance.
248 * @throw RCSInvalidParameterException If ocResource is nullptr.
250 static RCSRemoteResourceObject::Ptr fromOCResource(
251 std::shared_ptr< OC::OCResource > ocResource);
254 * Returns an equivalent OCResource using RCSRemoteResourceObject instance.
256 * @throw RCSInvalidParameterException If rcsResource is nullptr.
258 static std::shared_ptr< OC::OCResource > toOCResource(
259 RCSRemoteResourceObject::Ptr rcsResource);
262 * Returns whether monitoring is enabled.
264 * @see startMonitoring()
266 bool isMonitoring() const;
269 * Returns whether caching is enabled.
271 * @see startCaching()
274 bool isCaching() const;
277 * Returns whether the resource is observable.
280 bool isObservable() const;
283 * Starts monitoring the resource.
285 * Monitoring provides a feature to check the presence of a resource,
286 * even when the server is not announcing Presence using startPresnece.
288 * @param cb A Callback to get changed resource state.
290 * @throws InvalidParameterException If cb is an empty function or null.
291 * @throws BadRequestException If monitoring is already started.
293 * @note The callback will be invoked in an internal thread.
295 * @see StateChangedCallback
297 * @see isMonitoring()
298 * @see stopMonitoring()
301 void startMonitoring(StateChangedCallback cb);
304 * Stops monitoring the resource.
306 * It does nothing if monitoring is not started.
308 * @see startMonitoring()
311 void stopMonitoring();
314 * Returns the current state of the resource.
316 * @see startMonitoring
318 ResourceState getState() const;
321 * Starts caching attributes of the resource.
323 * This will start caching for the resource.
324 * Once caching started it will look for the data updation on the resource
325 * and updates the cache data accordingly.
327 * It is equivalent to calling startCaching(CacheUpdatedCallback) with an empty function.
329 * @see getCacheState()
330 * @see getCachedAttributes()
331 * @see getCachedAttribute(const std::string&) const
333 * @throws BadRequestException
339 * Starts caching attributes for the resource.
341 * This will start data caching for the resource.
342 * Once caching started it will look for the data updation on the resource and
343 * updates the cached data accordingly.
345 * @param cb If non-empty function, it will be invoked whenever the cache updated.
347 * @throws BadRequestException If caching is already started.
349 * @note The callback will be invoked in an internal thread.
351 * @see CacheUpdatedCallback
352 * @see getCacheState()
353 * @see isCachedAvailable()
354 * @see getCachedAttributes()
355 * @see getCachedAttribute(const std::string&) const
358 void startCaching(CacheUpdatedCallback cb);
363 * It does nothing if caching is not started.
365 * @see startCaching()
366 * @see startCaching(CacheUpdatedCallback)
371 * Returns the current cache state.
374 CacheState getCacheState() const;
377 * Returns whether cached data is available.
379 * Cache will be available always once cache state had been CacheState::READY
380 * even if current state is CacheState::LOST_SIGNAL.
382 * @see getCacheState()
384 bool isCachedAvailable() const;
387 * Gets the cached RCSResourceAttributes data.
389 * @pre Cache should be available.
391 * @return The cached attributes.
393 * @throws BadRequestException If the precondition is not fulfilled.
395 * @see RCSResourceAttributes
396 * @see isCachedAvailable()
397 * @see startCaching()
398 * @see startCaching(CacheUpdatedCallback)
401 RCSResourceAttributes getCachedAttributes() const;
404 * Gets a particular cached a ResourceAttribute Value.
406 * @pre Cache should be available.
408 * @return A requested attribute value.
410 * @throws BadRequestException If the precondition is not fulfilled.
411 * @throws InvalidKeyException If @a key doesn't match the key of any value.
413 * @see RCSResourceAttributes::Value
414 * @see isCachedAvailable()
415 * @see startCaching()
416 * @see startCaching(CacheUpdatedCallback)
419 RCSResourceAttributes::Value getCachedAttribute(const std::string& key) const;
422 * Gets resource attributes directly from the server.
424 * This API send a get request to the resource of interest and provides
425 * the attributes to the caller in the RemoteAttributesGetCallback.
427 * @throws PlatformException If the operation failed
428 * @throws InvalidParameterException If cb is an empty function or null.
430 * @note The callback will be invoked in an internal thread.
432 void getRemoteAttributes(RemoteAttributesGetCallback cb);
435 * Gets resource representation with empty query parameters directly from the server.
437 * @param cb A callback to receive the response.
439 * @throws PlatformException If the operation failed
440 * @throws InvalidParameterException If cb is an empty function or null.
442 * @note The callback will be invoked in an internal thread.
444 void get(GetCallback cb);
447 * Gets resource representation directly from the server.
449 * The response could be different by the query parameters, it depends on server.
451 * @param queryParams Query parameters
452 * @param cb A callback to receive the response.
454 * @throws PlatformException If the operation failed
455 * @throws InvalidParameterException If cb is an empty function or null.
457 * @note The callback will be invoked in an internal thread.
459 void get(const RCSQueryParams& queryParams, GetCallback cb);
462 * Sends a set request with resource attributes to the server.
464 * The SetRequest behavior depends on the server, whether updating its attributes or not.
466 * @param attributes Attributes to set
467 * @param cb A callback to receive the response.
469 * @throws PlatformException If the operation failed
470 * @throws InvalidParameterException If cb is an empty function or null.
472 * @see RCSResourceObject
473 * @see RCSResourceObject::SetRequestHandlerPolicy
475 * @note The callback will be invoked in an internal thread.
477 void setRemoteAttributes(const RCSResourceAttributes& attributes,
478 RemoteAttributesSetCallback cb);
481 * Sends a set request with resource attributes to the server.
483 * The SetRequest behavior depends on query parameters and the server.
485 * @param attributes Attributes to set
486 * @param cb A callback to receive the response.
488 * @throws PlatformException If the operation failed
489 * @throws InvalidParameterException If cb is an empty function or null.
491 * @see RCSResourceObject
492 * @see RCSResourceObject::SetRequestHandlerPolicy
494 * @note The callback will be invoked in an internal thread.
496 void set(const RCSResourceAttributes& attributes, SetCallback cb);
499 * Sends a set request with resource attributes to the server.
501 * The SetRequest behavior depends on query parameters and the server.
503 * @param queryParams Query parameters
504 * @param attributes Attributes to set
505 * @param cb A callback to receive the response.
507 * @throws PlatformException If the operation failed
508 * @throws InvalidParameterException If cb is an empty function or null.
510 * @see RCSResourceObject
511 * @see RCSResourceObject::SetRequestHandlerPolicy
513 * @note The callback will be invoked in an internal thread.
515 void set(const RCSQueryParams& queryParams, const RCSResourceAttributes& attributes,
519 * Sends a set request with resource representation to the server.
521 * The SetRequest behavior depends on query parameters and the server.
523 * @param queryParams Query parameters
524 * @param rep Representation to set
525 * @param cb A callback to receive the response.
527 * @throws PlatformException If the operation failed
528 * @throws InvalidParameterException If cb is an empty function or null.
530 * @see RCSResourceObject
531 * @see RCSResourceObject::SetRequestHandlerPolicy
533 * @note The callback will be invoked in an internal thread.
535 void set(const RCSQueryParams& queryParams, const RCSRepresentation &rep,
539 * Returns the uri of the resource.
542 std::string getUri() const;
545 * Returns the address of the resource .
548 std::string getAddress() const;
551 * Returns the resource types of the resource.
554 std::vector< std::string > getTypes() const;
557 * Returns the resource interfaces of the resource.
560 std::vector< std::string > getInterfaces() const;
563 std::shared_ptr< PrimitiveResource > m_primitiveResource;
569 #endif // RCSREMOTERESOURCEOBJECT_H