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"
38 namespace HeaderOption
49 class RCSRepresentation;
51 typedef std::vector< OC::HeaderOption::OCHeaderOption > HeaderOpts;
54 * The states of caching.
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. */
69 * The states of monitoring.
71 * @see startMonitoring
74 enum class ResourceState
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. */
84 class PrimitiveResource;
87 * This is to specify query parameters for requests to the server.
89 * @see RCSRemoteResourceObject
94 typedef std::unordered_map< std::string, std::string > Map;
99 * Sets an interface of the resource to operate on
101 * @param interface interface
103 RCSQueryParams& setResourceInterface(std::string interface);
106 * Sets a resource type of the resource to operate on
108 * @param type resource type
110 RCSQueryParams& setResourceType(std::string type);
113 * Sets a resource type of the resource to operate on
115 * @param key key to be inserted
116 * @param value value to be inserted
118 * @note "rt" and "if" are reserved, so you should avoid them as a key.
121 RCSQueryParams& put(std::string key, std::string value);
124 * Returns the resource interface.
126 std::string getResourceInterface() const;
129 * Returns the resource type.
131 std::string getResourceType() const;
136 * @param key key of the element whose mapped value is accessed.
138 * @throws InvalidKeyException If @a key doesn't match the key of any value.
140 std::string get(const std::string& key) const;
143 * Returns all params.
145 const Map& getAll() const;
148 std::string m_resourceInterface;
149 std::string m_resourceType;
151 std::unordered_map< std::string, std::string > m_map;
156 * This represents a remote resource and provides simple ways to interact with it.
157 * Basically this is a client of a remote resource that runs on other device.
159 * The class supports features to help get information of a remote resource
160 * such as monitoring and caching.
162 * @see RCSDiscoveryManager
165 class RCSRemoteResourceObject
168 typedef std::shared_ptr< RCSRemoteResourceObject > Ptr;
171 * Callback definition to be invoked when monitoring state is changed.
173 * @see startMonitioring
176 typedef std::function< void(ResourceState) > StateChangedCallback;
179 * Callback definition to be invoked when cache is updated.
181 * @param attrs the updated attributes
183 typedef std::function< void(const RCSResourceAttributes& attrs) > CacheUpdatedCallback;
186 * Callback definition to be invoked when the response of getRemoteAttributes is
189 * @param attrs the result attributes
190 * @param eCode the error code received from the resource
192 * @see getRemoteAttributes
194 typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
195 RemoteAttributesGetCallback;
198 * Callback definition to be invoked when the response of get is received.
201 * @param rep the result representation
202 * @param eCode the error code received from the resource
206 typedef std::function< void(const HeaderOpts& headerOpts,
207 const RCSRepresentation& rep, int eCode) > GetCallback;
210 * Callback definition to be invoked when the response of setRemoteAttributes is
213 * @param attrs the result attributes
214 * @param eCode the error code received from the resource
216 * @see setRemoteAttributes
218 typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
219 RemoteAttributesSetCallback;
222 * Callback definition to be invoked when the response of set is received.
225 * @param rep the result representation
226 * @param eCode the error code received from the resource
230 typedef std::function< void(const HeaderOpts& headerOpts,
231 const RCSRepresentation& rep, int eCode) > SetCallback;
235 typedef unsigned int BrokerID;
239 RCSRemoteResourceObject(std::shared_ptr< PrimitiveResource >);
242 ~RCSRemoteResourceObject();
245 * Creates an instance from an OCResource instance.
247 * @throw RCSInvalidParameterException If ocResource is nullptr.
249 static RCSRemoteResourceObject::Ptr fromOCResource(
250 std::shared_ptr< OC::OCResource > ocResource);
253 * Returns whether monitoring is enabled.
255 * @see startMonitoring()
257 bool isMonitoring() const;
260 * Returns whether caching is enabled.
262 * @see startCaching()
265 bool isCaching() const;
268 * Returns whether the resource is observable.
271 bool isObservable() const;
274 * Starts monitoring the resource.
276 * Monitoring provides a feature to check the presence of a resource,
277 * even when the server is not announcing Presence using startPresnece.
279 * @param cb A Callback to get changed resource state.
281 * @throws InvalidParameterException If cb is an empty function or null.
282 * @throws BadRequestException If monitoring is already started.
284 * @note The callback will be invoked in an internal thread.
286 * @see StateChangedCallback
288 * @see isMonitoring()
289 * @see stopMonitoring()
292 void startMonitoring(StateChangedCallback cb);
295 * Stops monitoring the resource.
297 * It does nothing if monitoring is not started.
299 * @see startMonitoring()
302 void stopMonitoring();
305 * Returns the current state of the resource.
307 * @see startMonitoring
309 ResourceState getState() const;
312 * Starts caching attributes of the resource.
314 * This will start caching for the resource.
315 * Once caching started it will look for the data updation on the resource
316 * and updates the cache data accordingly.
318 * It is equivalent to calling startCaching(CacheUpdatedCallback) with an empty function.
320 * @see getCacheState()
321 * @see getCachedAttributes()
322 * @see getCachedAttribute(const std::string&) const
324 * @throws BadRequestException
330 * Starts caching attributes for the resource.
332 * This will start data caching for the resource.
333 * Once caching started it will look for the data updation on the resource and
334 * updates the cached data accordingly.
336 * @param cb If non-empty function, it will be invoked whenever the cache updated.
338 * @throws BadRequestException If caching is already started.
340 * @note The callback will be invoked in an internal thread.
342 * @see CacheUpdatedCallback
343 * @see getCacheState()
344 * @see isCachedAvailable()
345 * @see getCachedAttributes()
346 * @see getCachedAttribute(const std::string&) const
349 void startCaching(CacheUpdatedCallback cb);
354 * It does nothing if caching is not started.
356 * @see startCaching()
357 * @see startCaching(CacheUpdatedCallback)
362 * Returns the current cache state.
365 CacheState getCacheState() const;
368 * Returns whether cached data is available.
370 * Cache will be available always once cache state had been CacheState::READY
371 * even if current state is CacheState::LOST_SIGNAL.
373 * @see getCacheState()
375 bool isCachedAvailable() const;
378 * Gets the cached RCSResourceAttributes data.
380 * @pre Cache should be available.
382 * @return The cached attributes.
384 * @throws BadRequestException If the precondition is not fulfilled.
386 * @see RCSResourceAttributes
387 * @see isCachedAvailable()
388 * @see startCaching()
389 * @see startCaching(CacheUpdatedCallback)
392 RCSResourceAttributes getCachedAttributes() const;
395 * Gets a particular cached a ResourceAttribute Value.
397 * @pre Cache should be available.
399 * @return A requested attribute value.
401 * @throws BadRequestException If the precondition is not fulfilled.
402 * @throws InvalidKeyException If @a key doesn't match the key of any value.
404 * @see RCSResourceAttributes::Value
405 * @see isCachedAvailable()
406 * @see startCaching()
407 * @see startCaching(CacheUpdatedCallback)
410 RCSResourceAttributes::Value getCachedAttribute(const std::string& key) const;
413 * Gets resource attributes directly from the server.
415 * This API send a get request to the resource of interest and provides
416 * the attributes to the caller in the RemoteAttributesGetCallback.
418 * @throws PlatformException If the operation failed
419 * @throws InvalidParameterException If cb is an empty function or null.
421 * @note The callback will be invoked in an internal thread.
423 void getRemoteAttributes(RemoteAttributesGetCallback cb);
426 * Gets resource representation with empty query parameters directly from the server.
428 * @param cb A callback to receive the response.
430 * @throws PlatformException If the operation failed
431 * @throws InvalidParameterException If cb is an empty function or null.
433 * @note The callback will be invoked in an internal thread.
435 void get(GetCallback cb);
438 * Gets resource representation directly from the server.
440 * The response could be different by the query parameters, it depends on server.
442 * @param queryParams Query parameters
443 * @param cb A callback to receive the response.
445 * @throws PlatformException If the operation failed
446 * @throws InvalidParameterException If cb is an empty function or null.
448 * @note The callback will be invoked in an internal thread.
450 void get(const RCSQueryParams& queryParams, GetCallback cb);
453 * Sends a set request with resource attributes to the server.
455 * The SetRequest behavior depends on the server, whether updating its attributes or not.
457 * @param attributes Attributes to set
458 * @param cb A callback to receive the response.
460 * @throws PlatformException If the operation failed
461 * @throws InvalidParameterException If cb is an empty function or null.
463 * @see RCSResourceObject
464 * @see RCSResourceObject::SetRequestHandlerPolicy
466 * @note The callback will be invoked in an internal thread.
468 void setRemoteAttributes(const RCSResourceAttributes& attributes,
469 RemoteAttributesSetCallback cb);
472 * Sends a set request with resource attributes to the server.
474 * The SetRequest behavior depends on query parameters and the server.
476 * @param attributes Attributes to set
477 * @param cb A callback to receive the response.
479 * @throws PlatformException If the operation failed
480 * @throws InvalidParameterException If cb is an empty function or null.
482 * @see RCSResourceObject
483 * @see RCSResourceObject::SetRequestHandlerPolicy
485 * @note The callback will be invoked in an internal thread.
487 void set(const RCSResourceAttributes& attributes, SetCallback cb);
490 * Sends a set request with resource attributes to the server.
492 * The SetRequest behavior depends on query parameters and the server.
494 * @param queryParams Query parameters
495 * @param attributes Attributes to set
496 * @param cb A callback to receive the response.
498 * @throws PlatformException If the operation failed
499 * @throws InvalidParameterException If cb is an empty function or null.
501 * @see RCSResourceObject
502 * @see RCSResourceObject::SetRequestHandlerPolicy
504 * @note The callback will be invoked in an internal thread.
506 void set(const RCSQueryParams& queryParams, const RCSResourceAttributes& attributes,
510 * Returns the uri of the resource.
513 std::string getUri() const;
516 * Returns the address of the resource .
519 std::string getAddress() const;
522 * Returns the resource types of the resource.
525 std::vector< std::string > getTypes() const;
528 * Returns the resource interfaces of the resource.
531 std::vector< std::string > getInterfaces() const;
534 std::shared_ptr< PrimitiveResource > m_primitiveResource;
540 #endif // RCSREMOTERESOURCEOBJECT_H