Use `URI` all caps in documentation
[iotivity.git] / 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 #include "RCSRepresentation.h"
34
35 namespace OC
36 {
37     class OCResource;
38
39     namespace HeaderOption
40     {
41         class OCHeaderOption;
42     }
43 }
44
45 namespace OIC
46 {
47     namespace Service
48     {
49
50         class RCSRepresentation;
51
52         typedef std::vector< OC::HeaderOption::OCHeaderOption > HeaderOpts;
53
54         /**
55          * The states of caching.
56          *
57          * @see startCaching
58          * @see getCacheState
59          */
60         enum class CacheState
61         {
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. */
67         };
68
69         enum class CacheMode
70         {
71             OBSERVE_ONLY,
72             OBSERVE_WITH_POLLING
73         };
74
75         /**
76          * The states of monitoring.
77          *
78          * @see startMonitoring
79          * @see getState
80          */
81         enum class ResourceState
82         {
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. */
89         };
90
91         class PrimitiveResource;
92
93         /**
94          * This is to specify query parameters for requests to the server.
95          *
96          * @see RCSRemoteResourceObject
97          */
98         class RCSQueryParams
99         {
100         public:
101             typedef std::unordered_map< std::string, std::string > Map;
102
103         public:
104
105             /**
106              * Sets an interface of the resource to operate on
107              *
108              * @param interface interface
109              */
110             RCSQueryParams& setResourceInterface(std::string interface);
111
112             /**
113              * Sets a resource type of the resource to operate on
114              *
115              * @param type resource type
116              */
117             RCSQueryParams& setResourceType(std::string type);
118
119             /**
120              * Sets a resource type of the resource to operate on
121              *
122              * @param key key to be inserted
123              * @param value value to be inserted
124              *
125              * @note "rt" and "if" are reserved, so you should avoid them as a key.
126              *
127              */
128             RCSQueryParams& put(std::string key, std::string value);
129
130             /**
131              * Returns the resource interface.
132              */
133             std::string getResourceInterface() const;
134
135             /**
136              * Returns the resource type.
137              */
138             std::string getResourceType() const;
139
140             /**
141              * Returns a value.
142              *
143              * @param key key of the element whose mapped value is accessed.
144              *
145              * @throws InvalidKeyException If @a key doesn't match the key of any value.
146              */
147             std::string get(const std::string& key) const;
148
149             /**
150              * Returns all params.
151              */
152             const Map& getAll() const;
153
154         private:
155             std::string m_resourceInterface;
156             std::string m_resourceType;
157
158             std::unordered_map< std::string, std::string > m_map;
159         };
160
161         /**
162          *
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.
165          *
166          * The class supports features to help get information of a remote resource
167          * such as monitoring and caching.
168          *
169          * @see RCSDiscoveryManager
170          *
171          */
172         class RCSRemoteResourceObject
173         {
174         public:
175             typedef std::shared_ptr< RCSRemoteResourceObject > Ptr;
176
177             /**
178              * Callback definition to be invoked when monitoring state is changed.
179              *
180              * @see startMonitioring
181              * @see ResourceState
182              */
183             typedef std::function< void(ResourceState) > StateChangedCallback;
184
185             /**
186              * Callback definition to be invoked when cache is updated.
187              *
188              * @param attrs the updated attributes
189              */
190             typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
191                 CacheUpdatedCallback;
192
193             /**
194              * Callback definition to be invoked when the response of getRemoteAttributes is
195              * received.
196              *
197              * @param attrs the result attributes
198              * @param eCode the error code received from the resource
199              *
200              * @see getRemoteAttributes
201              */
202             typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
203                 RemoteAttributesGetCallback;
204
205             /**
206              * Callback definition to be invoked when the response of get is received.
207              *
208              * @param HeaderOpts
209              * @param rep the result representation
210              * @param eCode the error code received from the resource
211              *
212              * @see get
213              */
214             typedef std::function< void(const HeaderOpts& headerOpts,
215                     const RCSRepresentation& rep, int eCode) > GetCallback;
216
217             /**
218              * Callback definition to be invoked when the response of setRemoteAttributes is
219              * received.
220              *
221              * @param attrs the result attributes
222              * @param eCode the error code received from the resource
223              *
224              * @see setRemoteAttributes
225              */
226             typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) >
227                 RemoteAttributesSetCallback;
228
229             /**
230              * Callback definition to be invoked when the response of set is received.
231              *
232              * @param HeaderOpts
233              * @param rep the result representation
234              * @param eCode the error code received from the resource
235              *
236              * @see set
237              */
238             typedef std::function< void(const HeaderOpts& headerOpts,
239                     const RCSRepresentation& rep, int eCode) > SetCallback;
240
241         private:
242             typedef int CacheID;
243             typedef unsigned int BrokerID;
244
245         public:
246             //! @cond
247             RCSRemoteResourceObject(std::shared_ptr< PrimitiveResource >);
248             //! @endcond
249
250             ~RCSRemoteResourceObject();
251
252             /**
253              * Creates an instance from an OCResource instance.
254              *
255              * @throw RCSInvalidParameterException If ocResource is nullptr.
256              */
257             static RCSRemoteResourceObject::Ptr fromOCResource(
258                     std::shared_ptr< OC::OCResource > ocResource);
259
260             /**
261              * Returns an equivalent OCResource using RCSRemoteResourceObject instance.
262              *
263              * @throw RCSInvalidParameterException If rcsResource is nullptr.
264              */
265             static std::shared_ptr< OC::OCResource > toOCResource(
266                     RCSRemoteResourceObject::Ptr rcsResource);
267
268             /**
269              * Returns whether monitoring is enabled.
270              *
271              * @see startMonitoring()
272              */
273             bool isMonitoring() const;
274
275             /**
276              * Returns whether caching is enabled.
277              *
278              * @see startCaching()
279              */
280
281             bool isCaching() const;
282
283             /**
284              * Returns whether the resource is observable.
285              *
286              */
287             bool isObservable() const;
288
289             /**
290              * Starts monitoring the resource.
291              *
292              * Monitoring provides a feature to check the presence of a resource,
293              * even when the server is not announcing Presence using startPresnece.
294              *
295              * @param cb A Callback to get changed resource state.
296              *
297              * @throws InvalidParameterException If cb is an empty function or null.
298              * @throws BadRequestException If monitoring is already started.
299              *
300              * @note The callback will be invoked in an internal thread.
301              *
302              * @see StateChangedCallback
303              * @see ResourceState
304              * @see isMonitoring()
305              * @see stopMonitoring()
306              *
307              */
308             void startMonitoring(StateChangedCallback cb);
309
310             /**
311              * Stops monitoring the resource.
312              *
313              * It does nothing if monitoring is not started.
314              *
315              * @see startMonitoring()
316              *
317              */
318             void stopMonitoring();
319
320             /**
321              * Returns the current state of the resource.
322              *
323              * @see startMonitoring
324              */
325             ResourceState getState() const;
326
327             /**
328              * Starts caching attributes of the resource.
329              *
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.
333              *
334              * It is equivalent to calling startCaching(CacheUpdatedCallback) with an empty function.
335              *
336              * @see getCacheState()
337              * @see getCachedAttributes()
338              * @see getCachedAttribute(const std::string&) const
339              *
340              * @throws BadRequestException
341              *
342              */
343             void startCaching();
344
345             /**
346              * Starts caching attributes for the resource.
347              *
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.
351              *
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.
354              *
355              * @throws BadRequestException If caching is already started.
356              *
357              * @note The callback will be invoked in an internal thread.
358              *
359              * @see CacheUpdatedCallback
360              * @see getCacheState()
361              * @see isCachedAvailable()
362              * @see getCachedAttributes()
363              * @see getCachedAttribute(const std::string&) const
364              *
365              */
366             void startCaching(CacheUpdatedCallback cb, CacheMode mode = CacheMode::OBSERVE_WITH_POLLING);
367
368             /**
369              * Stops caching.
370              *
371              * It does nothing if caching is not started.
372              *
373              * @see startCaching()
374              * @see startCaching(CacheUpdatedCallback)
375              */
376             void stopCaching();
377
378             /**
379              * Returns the current cache state.
380              *
381              */
382             CacheState getCacheState() const;
383
384             /**
385              * Returns whether cached data is available.
386              *
387              * Cache will be available always once cache state had been CacheState::READY
388              * even if current state is CacheState::LOST_SIGNAL.
389              *
390              * @see getCacheState()
391              */
392             bool isCachedAvailable() const;
393
394             /**
395              * Gets the cached RCSResourceAttributes data.
396              *
397              * @pre Cache should be available.
398              *
399              * @return The cached attributes.
400              *
401              * @throws BadRequestException If the precondition is not fulfilled.
402              *
403              * @see RCSResourceAttributes
404              * @see isCachedAvailable()
405              * @see startCaching()
406              * @see startCaching(CacheUpdatedCallback)
407              *
408              */
409             RCSResourceAttributes getCachedAttributes() const;
410
411             /**
412              * Gets a particular cached a ResourceAttribute Value.
413              *
414              * @pre Cache should be available.
415              *
416              * @return A requested attribute value.
417              *
418              * @throws BadRequestException If the precondition is not fulfilled.
419              * @throws InvalidKeyException If @a key doesn't match the key of any value.
420              *
421              * @see RCSResourceAttributes::Value
422              * @see isCachedAvailable()
423              * @see startCaching()
424              * @see startCaching(CacheUpdatedCallback)
425              *
426              */
427             RCSResourceAttributes::Value getCachedAttribute(const std::string& key) const;
428
429             /**
430              * Gets resource attributes directly from the server.
431              *
432              * This API send a get request to the resource of interest and provides
433              * the attributes to the caller in the RemoteAttributesGetCallback.
434              *
435              * @throws PlatformException If the operation failed
436              * @throws InvalidParameterException If cb is an empty function or null.
437              *
438              * @note The callback will be invoked in an internal thread.
439              */
440             void getRemoteAttributes(RemoteAttributesGetCallback cb);
441
442             /**
443              * Gets resource representation with empty query parameters directly from the server.
444              *
445              * @param cb A callback to receive the response.
446              *
447              * @throws PlatformException If the operation failed
448              * @throws InvalidParameterException If cb is an empty function or null.
449              *
450              * @note The callback will be invoked in an internal thread.
451              */
452             void get(GetCallback cb);
453
454             /**
455              * Gets resource representation directly from the server.
456              *
457              * The response could be different by the query parameters, it depends on server.
458              *
459              * @param queryParams Query parameters
460              * @param cb A callback to receive the response.
461              *
462              * @throws PlatformException If the operation failed
463              * @throws InvalidParameterException If cb is an empty function or null.
464              *
465              * @note The callback will be invoked in an internal thread.
466              */
467             void get(const RCSQueryParams& queryParams, GetCallback cb);
468
469             /**
470              * Sends a set request with resource attributes to the server.
471              *
472              * The SetRequest behavior depends on the server, whether updating its attributes or not.
473              *
474              * @param attributes Attributes to set
475              * @param cb A callback to receive the response.
476              *
477              * @throws PlatformException If the operation failed
478              * @throws InvalidParameterException If cb is an empty function or null.
479              *
480              * @see RCSResourceObject
481              * @see RCSResourceObject::SetRequestHandlerPolicy
482              *
483              * @note The callback will be invoked in an internal thread.
484              */
485             void setRemoteAttributes(const RCSResourceAttributes& attributes,
486                     RemoteAttributesSetCallback cb);
487
488             /**
489              * Sends a set request with resource attributes to the server.
490              *
491              * The SetRequest behavior depends on query parameters and the server.
492              *
493              * @param attributes Attributes to set
494              * @param cb A callback to receive the response.
495              *
496              * @throws PlatformException If the operation failed
497              * @throws InvalidParameterException If cb is an empty function or null.
498              *
499              * @see RCSResourceObject
500              * @see RCSResourceObject::SetRequestHandlerPolicy
501              *
502              * @note The callback will be invoked in an internal thread.
503              */
504             void set(const RCSResourceAttributes& attributes, SetCallback cb);
505
506             /**
507              * Sends a set request with resource attributes to the server.
508              *
509              * The SetRequest behavior depends on query parameters and the server.
510              *
511              * @param queryParams Query parameters
512              * @param attributes Attributes to set
513              * @param cb A callback to receive the response.
514              *
515              * @throws PlatformException If the operation failed
516              * @throws InvalidParameterException If cb is an empty function or null.
517              *
518              * @see RCSResourceObject
519              * @see RCSResourceObject::SetRequestHandlerPolicy
520              *
521              * @note The callback will be invoked in an internal thread.
522              */
523             void set(const RCSQueryParams& queryParams, const RCSResourceAttributes& attributes,
524                     SetCallback cb);
525
526             /**
527              * Sends a set request with resource representation to the server.
528              *
529              * The SetRequest behavior depends on query parameters and the server.
530              *
531              * @param queryParams Query parameters
532              * @param rep Representation to set
533              * @param cb A callback to receive the response.
534              *
535              * @throws PlatformException If the operation failed
536              * @throws InvalidParameterException If cb is an empty function or null.
537              *
538              * @see RCSResourceObject
539              * @see RCSResourceObject::SetRequestHandlerPolicy
540              *
541              * @note The callback will be invoked in an internal thread.
542              */
543             void set(const RCSQueryParams& queryParams, const RCSRepresentation &rep,
544                     SetCallback cb);
545
546             /**
547              * Returns the URI of the resource.
548              *
549              */
550             std::string getUri() const;
551
552             /**
553              * Returns the address of the resource .
554              *
555              */
556             std::string getAddress() const;
557
558             /**
559              * Returns the resource types of the resource.
560              *
561              */
562             std::vector< std::string > getTypes() const;
563
564             /**
565              * Returns the resource interfaces of the resource.
566              *
567              */
568             std::vector< std::string > getInterfaces() const;
569
570         private:
571             std::shared_ptr< PrimitiveResource > m_primitiveResource;
572             CacheID m_cacheId;
573             BrokerID m_brokerId;
574         };
575     }
576 }
577 #endif // RCSREMOTERESOURCEOBJECT_H