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"
39 * The states of caching.
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. */
54 * The states of monitoring.
56 * @see startMonitoring
59 enum class ResourceState
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. */
69 class PrimitiveResource;
73 * This represents a remote resource and provides simple ways to interact with it.
74 * Basically this is a client of a remote resource that runs on other device.
76 * The class supports features to help get information of a remote resource
77 * such as monitoring and caching.
79 * @see RCSDiscoveryManager
82 class RCSRemoteResourceObject
85 typedef std::shared_ptr< RCSRemoteResourceObject > Ptr;
88 * Callback definition to be invoked when monitoring state is changed.
90 * @see startMonitioring
93 typedef std::function< void(ResourceState) > StateChangedCallback;
96 * Callback definition to be invoked when cache is updated.
98 * @param attrs the updated attributes
100 typedef std::function< void(const RCSResourceAttributes& attrs) > CacheUpdatedCallback;
103 * Callback definition to be invoked when the response of getRemoteAttributes is
106 * @param attrs the result attributes
107 * @param eCode the error code received from the resource
109 * @see getRemoteAttributes
111 typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
112 RemoteAttributesGetCallback;
115 * Callback definition to be invoked when the response of setRemoteAttributes is
118 * @param attrs the result attributes
119 * @param eCode the error code received from the resource
121 * @see setRemoteAttributes
123 typedef std::function< void(const RCSResourceAttributes&, int) >
124 RemoteAttributesSetCallback;
128 typedef unsigned int BrokerID;
132 RCSRemoteResourceObject(std::shared_ptr< PrimitiveResource >);
135 ~RCSRemoteResourceObject();
138 * Returns whether monitoring is enabled.
140 * @see startMonitoring()
142 bool isMonitoring() const;
145 * Returns whether caching is enabled.
147 * @see startCaching()
150 bool isCaching() const;
153 * Returns whether the resource is observable.
156 bool isObservable() const;
159 * Starts monitoring the resource.
161 * Monitoring provides a feature to check the presence of a resource,
162 * even when the server is not announcing Presence using startPresnece.
164 * @param cb A Callback to get changed resource state.
166 * @throws InvalidParameterException If cb is an empty function or null.
167 * @throws BadRequestException If monitoring is already started.
169 * @note The callback will be invoked in an internal thread.
171 * @see StateChangedCallback
173 * @see isMonitoring()
174 * @see stopMonitoring()
177 void startMonitoring(StateChangedCallback cb);
180 * Stops monitoring the resource.
182 * It does nothing if monitoring is not started.
184 * @see startMonitoring()
187 void stopMonitoring();
190 * Returns the current state of the resource.
192 * @see startMonitoring
194 ResourceState getState() const;
197 * Starts caching attributes of the resource.
199 * This will start caching for the resource.
200 * Once caching started it will look for the data updation on the resource
201 * and updates the cache data accordingly.
203 * It is equivalent to calling startCaching(CacheUpdatedCallback) with an empty function.
205 * @see getCacheState()
206 * @see getCachedAttributes()
207 * @see getCachedAttribute(const std::string&) const
209 * @throws BadRequestException
215 * Starts caching attributes for the resource.
217 * This will start data caching for the resource.
218 * Once caching started it will look for the data updation on the resource and
219 * updates the cached data accordingly.
221 * @param cb If non-empty function, it will be invoked whenever the cache updated.
223 * @throws BadRequestException If caching is already started.
225 * @note The callback will be invoked in an internal thread.
227 * @see CacheUpdatedCallback
228 * @see getCacheState()
229 * @see isCachedAvailable()
230 * @see getCachedAttributes()
231 * @see getCachedAttribute(const std::string&) const
234 void startCaching(CacheUpdatedCallback cb);
239 * It does nothing if caching is not started.
241 * @see startCaching()
242 * @see startCaching(CacheUpdatedCallback)
247 * Returns the current cache state.
250 CacheState getCacheState() const;
253 * Returns whether cached data is available.
255 * Cache will be available always once cache state had been CacheState::READY
256 * even if current state is CacheState::LOST_SIGNAL.
258 * @see getCacheState()
260 bool isCachedAvailable() const;
263 * Gets the cached RCSResourceAttributes data.
265 * @pre Cache should be available.
267 * @return The cached attributes.
269 * @throws BadRequestException If the precondition is not fulfilled.
271 * @see RCSResourceAttributes
272 * @see isCachedAvailable()
273 * @see startCaching()
274 * @see startCaching(CacheUpdatedCallback)
277 RCSResourceAttributes getCachedAttributes() const;
280 * Gets a particular cached a ResourceAttribute Value.
282 * @pre Cache should be available.
284 * @return A requested attribute value.
286 * @throws BadRequestException If the precondition is not fulfilled.
287 * @throws InvalidKeyException If @a key doesn't match the key of any value.
289 * @see RCSResourceAttributes::Value
290 * @see isCachedAvailable()
291 * @see startCaching()
292 * @see startCaching(CacheUpdatedCallback)
295 RCSResourceAttributes::Value getCachedAttribute(const std::string& key) const;
298 * Gets resource attributes directly from the server.
300 * This API send a get request to the resource of interest and provides
301 * the attributes to the caller in the RemoteAttributesReceivedCallback.
303 * @throws PlatformException If the operation failed
304 * @throws InvalidParameterException If cb is an empty function or null.
306 * @see RCSResourceAttributes::Value
308 * @note The callback will be invoked in an internal thread.
310 void getRemoteAttributes(RemoteAttributesGetCallback cb);
313 * Sends a set request with resource attributes to the server.
315 * The SetRequest behavior depends on the server, whether updating its attributes or not.
317 * @param attributes Attributes to set
318 * @param cb A callback to receive the response.
320 * @throws PlatformException If the operation failed
321 * @throws InvalidParameterException If cb is an empty function or null.
323 * @see RCSResourceObject
324 * @see RCSResourceObject::SetRequestHandlerPolicy
326 * @note The callback will be invoked in an internal thread.
328 void setRemoteAttributes(const RCSResourceAttributes& attributes,
329 RemoteAttributesSetCallback cb);
332 * Returns the uri of the resource.
335 std::string getUri() const;
338 * Returns the address of the resource .
341 std::string getAddress() const;
344 * Returns the resource types of the resource.
347 std::vector< std::string > getTypes() const;
350 * Returns the resource interfaces of the resource.
353 std::vector< std::string > getInterfaces() const;
356 std::shared_ptr< PrimitiveResource > m_primitiveResource;
362 #endif // RCSREMOTERESOURCEOBJECT_H