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. */
76 * The states of monitoring.
78 * @see startMonitoring
81 enum class ResourceState
83 NONE, /**< Monitoring is not started.*/
84 REQUESTED, /**< Monitoring is started and checking state is in progress.
85 This is the default state after startMonitoring. */
86 ALIVE, /**< The resource is alive. */
87 LOST_SIGNAL, /**< Failed to reach the resource. */
88 DESTROYED /**< The resource is deleted. */
91 class PrimitiveResource;
94 * This is to specify query parameters for requests to the server.
96 * @see RCSRemoteResourceObject
101 typedef std::unordered_map< std::string, std::string > Map;
106 * Sets an interface of the resource to operate on
108 * @param interface interface
110 RCSQueryParams& setResourceInterface(std::string interface);
113 * Sets a resource type of the resource to operate on
115 * @param type resource type
117 RCSQueryParams& setResourceType(std::string type);
120 * Sets a resource type of the resource to operate on
122 * @param key key to be inserted
123 * @param value value to be inserted
125 * @note "rt" and "if" are reserved, so you should avoid them as a key.
128 RCSQueryParams& put(std::string key, std::string value);
131 * Returns the resource interface.
133 std::string getResourceInterface() const;
136 * Returns the resource type.
138 std::string getResourceType() const;
143 * @param key key of the element whose mapped value is accessed.
145 * @throws InvalidKeyException If @a key doesn't match the key of any value.
147 std::string get(const std::string& key) const;
150 * Returns all params.
152 const Map& getAll() const;
155 std::string m_resourceInterface;
156 std::string m_resourceType;
158 std::unordered_map< std::string, std::string > m_map;
163 * This represents a remote resource and provides simple ways to interact with it.
164 * Basically this is a client of a remote resource that runs on other device.
166 * The class supports features to help get information of a remote resource
167 * such as monitoring and caching.
169 * @see RCSDiscoveryManager
172 class RCSRemoteResourceObject : public std::enable_shared_from_this<RCSRemoteResourceObject>
175 typedef std::shared_ptr< RCSRemoteResourceObject > Ptr;
178 * Callback definition to be invoked when monitoring state is changed.
180 * @see startMonitioring
183 typedef std::function< void(ResourceState) > StateChangedCallback;
186 * Callback definition to be invoked when cache is updated.
188 * @param attrs the updated attributes
190 typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
191 CacheUpdatedCallback;
194 * Callback definition to be invoked when the response of getRemoteAttributes is
197 * @param attrs the result attributes
198 * @param eCode the error code received from the resource
200 * @see getRemoteAttributes
202 typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
203 RemoteAttributesGetCallback;
206 * Callback definition to be invoked when the response of get is received.
209 * @param rep the result representation
210 * @param eCode the error code received from the resource
214 typedef std::function< void(const HeaderOpts& headerOpts,
215 const RCSRepresentation& rep, int eCode) > GetCallback;
218 * Callback definition to be invoked when the response of setRemoteAttributes is
221 * @param attrs the result attributes
222 * @param eCode the error code received from the resource
224 * @see setRemoteAttributes
226 typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
227 RemoteAttributesSetCallback;
230 * Callback definition to be invoked when the response of set is received.
233 * @param rep the result representation
234 * @param eCode the error code received from the resource
238 typedef std::function< void(const HeaderOpts& headerOpts,
239 const RCSRepresentation& rep, int eCode) > SetCallback;
243 typedef unsigned int BrokerID;
247 RCSRemoteResourceObject(std::shared_ptr< PrimitiveResource >);
250 ~RCSRemoteResourceObject();
253 * Creates an instance from an OCResource instance.
255 * @throw RCSInvalidParameterException If ocResource is nullptr.
257 static RCSRemoteResourceObject::Ptr fromOCResource(
258 std::shared_ptr< OC::OCResource > ocResource);
261 * Returns an equivalent OCResource using RCSRemoteResourceObject instance.
263 * @throw RCSInvalidParameterException If rcsResource is nullptr.
265 static std::shared_ptr< OC::OCResource > toOCResource(
266 RCSRemoteResourceObject::Ptr rcsResource);
269 * Returns whether monitoring is enabled.
271 * @see startMonitoring()
273 bool isMonitoring() const;
276 * Returns whether caching is enabled.
278 * @see startCaching()
281 bool isCaching() const;
284 * Returns whether the resource is observable.
287 bool isObservable() const;
290 * Starts monitoring the resource.
292 * Monitoring provides a feature to check the presence of a resource,
293 * even when the server is not announcing Presence using startPresnece.
295 * @param cb A Callback to get changed resource state.
297 * @throws InvalidParameterException If cb is an empty function or null.
298 * @throws BadRequestException If monitoring is already started.
300 * @note The callback will be invoked in an internal thread.
302 * @see StateChangedCallback
304 * @see isMonitoring()
305 * @see stopMonitoring()
308 void startMonitoring(StateChangedCallback cb);
311 * Stops monitoring the resource.
313 * It does nothing if monitoring is not started.
315 * @see startMonitoring()
318 void stopMonitoring();
321 * Returns the current state of the resource.
323 * @see startMonitoring
325 ResourceState getState() const;
328 * Starts caching attributes of the resource.
330 * This will start caching for the resource.
331 * Once caching started it will look for the data updation on the resource
332 * and updates the cache data accordingly.
334 * It is equivalent to calling startCaching(CacheUpdatedCallback) with an empty function.
336 * @see getCacheState()
337 * @see getCachedAttributes()
338 * @see getCachedAttribute(const std::string&) const
340 * @throws BadRequestException
346 * Starts caching attributes for the resource.
348 * This will start data caching for the resource.
349 * Once caching started it will look for the data updation on the resource and
350 * updates the cached data accordingly.
352 * @param cb If non-empty function, it will be invoked whenever the cache updated.
353 * @param mode if CacheMode is OBSERVE_ONLY, it will be invoked when receive observe response only.
355 * @throws BadRequestException If caching is already started.
357 * @note The callback will be invoked in an internal thread.
359 * @see CacheUpdatedCallback
360 * @see getCacheState()
361 * @see isCachedAvailable()
362 * @see getCachedAttributes()
363 * @see getCachedAttribute(const std::string&) const
366 void startCaching(CacheUpdatedCallback cb, CacheMode mode = CacheMode::OBSERVE_WITH_POLLING);
371 * It does nothing if caching is not started.
373 * @see startCaching()
374 * @see startCaching(CacheUpdatedCallback)
379 * Returns the current cache state.
382 CacheState getCacheState() const;
385 * Returns whether cached data is available.
387 * Cache will be available always once cache state had been CacheState::READY
388 * even if current state is CacheState::LOST_SIGNAL.
390 * @see getCacheState()
392 bool isCachedAvailable() const;
395 * Gets the cached RCSResourceAttributes data.
397 * @pre Cache should be available.
399 * @return The cached attributes.
401 * @throws BadRequestException If the precondition is not fulfilled.
403 * @see RCSResourceAttributes
404 * @see isCachedAvailable()
405 * @see startCaching()
406 * @see startCaching(CacheUpdatedCallback)
409 RCSResourceAttributes getCachedAttributes() const;
412 * Gets a particular cached a ResourceAttribute Value.
414 * @pre Cache should be available.
416 * @return A requested attribute value.
418 * @throws BadRequestException If the precondition is not fulfilled.
419 * @throws InvalidKeyException If @a key doesn't match the key of any value.
421 * @see RCSResourceAttributes::Value
422 * @see isCachedAvailable()
423 * @see startCaching()
424 * @see startCaching(CacheUpdatedCallback)
427 RCSResourceAttributes::Value getCachedAttribute(const std::string& key) const;
430 * Gets resource attributes directly from the server.
432 * This API send a get request to the resource of interest and provides
433 * the attributes to the caller in the RemoteAttributesGetCallback.
435 * @throws PlatformException If the operation failed
436 * @throws InvalidParameterException If cb is an empty function or null.
438 * @note The callback will be invoked in an internal thread.
440 void getRemoteAttributes(RemoteAttributesGetCallback cb);
443 * Gets resource representation with empty query parameters directly from the server.
445 * @param cb A callback to receive the response.
447 * @throws PlatformException If the operation failed
448 * @throws InvalidParameterException If cb is an empty function or null.
450 * @note The callback will be invoked in an internal thread.
452 void get(GetCallback cb);
455 * Gets resource representation directly from the server.
457 * The response could be different by the query parameters, it depends on server.
459 * @param queryParams Query parameters
460 * @param cb A callback to receive the response.
462 * @throws PlatformException If the operation failed
463 * @throws InvalidParameterException If cb is an empty function or null.
465 * @note The callback will be invoked in an internal thread.
467 void get(const RCSQueryParams& queryParams, GetCallback cb);
470 * Sends a set request with resource attributes to the server.
472 * The SetRequest behavior depends on the server, whether updating its attributes or not.
474 * @param attributes Attributes to set
475 * @param cb A callback to receive the response.
477 * @throws PlatformException If the operation failed
478 * @throws InvalidParameterException If cb is an empty function or null.
480 * @see RCSResourceObject
481 * @see RCSResourceObject::SetRequestHandlerPolicy
483 * @note The callback will be invoked in an internal thread.
485 void setRemoteAttributes(const RCSResourceAttributes& attributes,
486 RemoteAttributesSetCallback cb);
489 * Sends a set request with resource attributes to the server.
491 * The SetRequest behavior depends on query parameters and the server.
493 * @param attributes Attributes to set
494 * @param cb A callback to receive the response.
496 * @throws PlatformException If the operation failed
497 * @throws InvalidParameterException If cb is an empty function or null.
499 * @see RCSResourceObject
500 * @see RCSResourceObject::SetRequestHandlerPolicy
502 * @note The callback will be invoked in an internal thread.
504 void set(const RCSResourceAttributes& attributes, SetCallback cb);
507 * Sends a set request with resource attributes to the server.
509 * The SetRequest behavior depends on query parameters and the server.
511 * @param queryParams Query parameters
512 * @param attributes Attributes to set
513 * @param cb A callback to receive the response.
515 * @throws PlatformException If the operation failed
516 * @throws InvalidParameterException If cb is an empty function or null.
518 * @see RCSResourceObject
519 * @see RCSResourceObject::SetRequestHandlerPolicy
521 * @note The callback will be invoked in an internal thread.
523 void set(const RCSQueryParams& queryParams, const RCSResourceAttributes& attributes,
527 * Sends a set request with resource representation to the server.
529 * The SetRequest behavior depends on query parameters and the server.
531 * @param queryParams Query parameters
532 * @param rep Representation to set
533 * @param cb A callback to receive the response.
535 * @throws PlatformException If the operation failed
536 * @throws InvalidParameterException If cb is an empty function or null.
538 * @see RCSResourceObject
539 * @see RCSResourceObject::SetRequestHandlerPolicy
541 * @note The callback will be invoked in an internal thread.
543 void set(const RCSQueryParams& queryParams, const RCSRepresentation &rep,
547 * Returns the uri of the resource.
550 std::string getUri() const;
553 * Returns the address of the resource .
556 std::string getAddress() const;
559 * Returns the resource types of the resource.
562 std::vector< std::string > getTypes() const;
565 * Returns the resource interfaces of the resource.
568 std::vector< std::string > getInterfaces() const;
571 std::shared_ptr< PrimitiveResource > m_primitiveResource;
577 #endif // RCSREMOTERESOURCEOBJECT_H