1 //******************************************************************
3 // Copyright 2014 Intel Mobile Communications GmbH 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
28 #ifndef OC_RESOURCE_H_
29 #define OC_RESOURCE_H_
36 #include <ResourceInitException.h>
37 #include <IClientWrapper.h>
38 #include <InProcClientWrapper.h>
39 #include <OCRepresentation.h>
44 class OCResourceIdentifier;
45 std::ostream& operator <<(std::ostream& os, const OCResourceIdentifier& ri);
47 * @brief OCResourceIdentifier represents the identity information for a server. This
48 * object combined with the OCResource's URI property uniquely identify an
49 * OCResource on or across networks.
50 * Equality operators are implemented. However, internal representation is subject
51 * to change and thus should not be accessed or depended on.
53 class OCResourceIdentifier
55 friend class OCResource;
56 friend std::ostream& operator <<(std::ostream& os, const OCResourceIdentifier& ri);
59 OCResourceIdentifier() = delete;
61 OCResourceIdentifier(const OCResourceIdentifier&) = default;
63 #if defined(_MSC_VER) && (_MSC_VER < 1900)
64 OCResourceIdentifier(OCResourceIdentifier&& o):
65 m_resourceUri(std::move(o.m_resourceUri)),
66 m_representation(o.m_representation)
70 OCResourceIdentifier(OCResourceIdentifier&&) = default;
73 OCResourceIdentifier& operator=(const OCResourceIdentifier&) = delete;
75 OCResourceIdentifier& operator=(OCResourceIdentifier&&) = delete;
77 bool operator==(const OCResourceIdentifier &other) const;
79 bool operator!=(const OCResourceIdentifier &other) const;
81 bool operator<(const OCResourceIdentifier &other) const;
83 bool operator>(const OCResourceIdentifier &other) const;
85 bool operator<=(const OCResourceIdentifier &other) const;
87 bool operator>=(const OCResourceIdentifier &other) const;
91 OCResourceIdentifier(const std::string& wireServerIdentifier,
92 const std::string& resourceUri );
95 std::string m_representation;
96 const std::string& m_resourceUri;
100 * @brief OCResource represents an OC resource. A resource could be a light controller,
101 * temperature sensor, smoke detector, etc. A resource comes with a well-defined
102 * contract or interface onto which you can perform different operations, such as
103 * turning on the light, getting the current temperature or subscribing for event
104 * notifications from the smoke detector. A resource can be composed of one or
109 friend class OCPlatform_impl;
110 friend class ListenOCContainer;
112 typedef std::shared_ptr<OCResource> Ptr;
114 #if defined(_MSC_VER) && (_MSC_VER < 1900)
115 OCResource(OCResource&& o):
116 m_clientWrapper(std::move(o.m_clientWrapper)),
117 m_uri(std::move(o.m_uri)),
118 m_resourceId(std::move(o.m_resourceId)),
119 m_devAddr(std::move(o.m_devAddr)),
120 m_deviceName(std::move(o.m_deviceName)),
121 m_useHostString(o.m_useHostString),
122 m_property(o.m_property),
123 m_isCollection(o.m_isCollection),
124 m_resourceTypes(std::move(o.m_resourceTypes)),
125 m_interfaces(std::move(o.m_interfaces)),
126 m_children(std::move(m_children)),
127 m_observeHandle(std::move(m_observeHandle)),
128 m_headerOptions(std::move(m_headerOptions))
132 OCResource(OCResource&&) = default;
134 // Explicitly delete the copy ctor since VS2013 would try to generate one, and
135 // the standard says that defaulting the move ctor should delete the copy ctor.
136 OCResource(const OCResource&) = delete;
138 // We cannot support copy/move assigns since OCResourceIdentifier doesn't.
139 OCResource& operator=(OCResource&&) = delete;
140 OCResource& operator=(const OCResource&) = delete;
145 virtual ~OCResource(void);
148 * Function to get the attributes of a resource.
149 * @param queryParametersMap map which can have the query parameter name and value
150 * @param attributeHandler handles callback
151 * The callback function will be invoked with a map of attribute name and values.
152 * The callback function will also have the result from this Get operation
153 * This will have error codes
154 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
155 * @note OCStackResult is defined in ocstack.h.
157 OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
159 * Function to get the attributes of a resource.
160 * @param queryParametersMap map which can have the query parameter name and value
161 * @param attributeHandler handles callback
162 * The callback function will be invoked with a map of attribute name and values.
163 * The callback function will also have the result from this Get operation
164 * This will have error codes
165 * @param QoS the quality of communication
166 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
167 * @note OCStackResult is defined in ocstack.h.
169 OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
170 QualityOfService QoS);
173 * Function to get the attributes of a resource.
175 * @param resourceType resourceType of the resource operate on
176 * @param resourceInterface interface type of the resource to operate on
177 * @param queryParametersMap map which can have the query parameter name and value
178 * @param attributeHandler handles callback
179 * The callback function will be invoked with a map of attribute name and values.
180 * The callback function will be invoked with a list of URIs if 'get' is invoked on a
181 * resource container (list will be empty if not a container)
182 * The callback function will also have the result from this Get operation. This will
184 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
185 * @note OCStackResult is defined in ocstack.h.
187 * Consider resource "a/home" (with link interface and resource type as home) contains links
188 * to "a/kitchen" and "a/room".
189 * -# get("home", Link_Interface, &onGet)
191 * Callback onGet will receive a) Empty attribute map because there are no attributes for
192 * a/home b) list with
193 * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
195 * @note A resource may contain single or multiple resource types. Also, a resource may
196 * contain single or multiple interfaces.
197 * Currently, single GET request is allowed to do operate on single resource type or resource
198 * interface. In future, a single GET
199 * can operate on multiple resource types and interfaces.
200 * @note A client can traverse a tree or graph by doing successive GETs on the returned
201 * resources at a node.
204 OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
205 const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
207 * Function to get the attributes of a resource.
209 * @param resourceType resourceType of the resource operate on
210 * @param resourceInterface interface type of the resource to operate on
211 * @param queryParametersMap map which can have the query parameter name and value
212 * @param attributeHandler handles callback
213 * The callback function will be invoked with a map of attribute name and values.
214 * The callback function will be invoked with a list of URIs if 'get' is invoked on a
215 * resource container (list will be empty if not a container)
216 * The callback function will also have the result from this Get operation. This will
218 * @param QoS the quality of communication
219 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
220 * note OCStackResult is defined in ocstack.h.
222 * Consider resource "a/home" (with link interface and resource type as home) contains links
223 * to "a/kitchen" and "a/room".
224 * -# get("home", Link_Interface, &onGet)
226 * Callback onGet will receive a) Empty attribute map because there are no attributes for
227 * a/home b) list with
228 * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
230 * @note A resource may contain single or multiple resource types. Also, a resource may
231 * contain single or multiple interfaces.
232 * Currently, single GET request is allowed to do operate on single resource type or resource
233 * interface. In future, a single GET
234 * can operate on multiple resource types and interfaces.
235 * @note A client can traverse a tree or graph by doing successive GETs on the returned
236 * resources at a node.
239 OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
240 const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
241 QualityOfService QoS);
244 * Function to set the representation of a resource (via PUT)
246 * @param representation which can either have all the attribute names and values
247 (which will represent entire state of the resource) or a
248 * set of attribute names and values which needs to be modified
249 * The callback function will be invoked with a map of attribute name and values.
250 * The callback function will also have the result from this Put operation
251 * This will have error codes
252 * @param queryParametersMap map which can have the query parameter name and value
253 * @param attributeHandler attribute handler
254 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
255 * @note OCStackResult is defined in ocstack.h.
258 OCStackResult put(const OCRepresentation& representation,
259 const QueryParamsMap& queryParametersMap, PutCallback attributeHandler);
261 * Function to set the representation of a resource (via PUT)
263 * @param representation which can either have all the attribute names and values
264 (which will represent entire state of the resource) or a
265 * set of attribute names and values which needs to be modified
266 * The callback function will be invoked with a map of attribute name and values.
267 * The callback function will also have the result from this Put operation
268 * This will have error codes
269 * @param queryParametersMap map which can have the query parameter name and value
270 * @param attributeHandler attribute handler
271 * @param QoS the quality of communication
272 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
273 * @note OCStackResult is defined in ocstack.h.
276 OCStackResult put(const OCRepresentation& representation,
277 const QueryParamsMap& queryParametersMap, PutCallback attributeHandler,
278 QualityOfService QoS);
281 * Function to set the attributes of a resource (via PUT)
283 * @param resourceType resource type of the resource to operate on
284 * @param resourceInterface interface type of the resource to operate on
285 * @param representation representation of the resource
286 * @param queryParametersMap Map which can have the query parameter name and value
287 * @param attributeHandler attribute handler
288 * The callback function will be invoked with a map of attribute name and values.
289 * The callback function will also have the result from this Put operation
290 * This will have error codes.
291 * The Representation parameter maps which can either have all the attribute names
293 * (which will represent entire state of the resource) or a
294 * set of attribute names and values which needs to be modified
295 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
296 * @note OCStackResult is defined in ocstack.h.
299 OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
300 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
301 PutCallback attributeHandler);
303 * Function to set the attributes of a resource (via PUT)
304 * @param resourceType resource type of the resource to operate on
305 * @param resourceInterface interface type of the resource to operate on
306 * @param representation representation of the resource
307 * @param queryParametersMap Map which can have the query parameter name and value
308 * @param attributeHandler attribute handler
309 * The callback function will be invoked with a map of attribute name and values.
310 * The callback function will also have the result from this Put operation
311 * This will have error codes.
312 * The Representation parameter maps which can either have all the attribute names
314 * (which will represent entire state of the resource) or a
315 * set of attribute names and values which needs to be modified
316 * @param QoS the quality of communication
317 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
318 * @note OCStackResult is defined in ocstack.h.
321 OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
322 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
323 PutCallback attributeHandler, QualityOfService QoS);
326 * Function to post on a resource
328 * @param representation which can either have all the attribute names and values
329 * (which will represent entire state of the resource) or a
330 * set of attribute names and values which needs to be modified
331 * The callback function will be invoked with a map of attribute name and values.
332 * The callback function will also have the result from this Put operation
333 * This will have error codes
334 * @param queryParametersMap map which can have the query parameter name and value
335 * @param attributeHandler attribute handler
336 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
337 * @note OCStackResult is defined in ocstack.h.
339 OCStackResult post(const OCRepresentation& representation,
340 const QueryParamsMap& queryParametersMap, PostCallback attributeHandler);
342 * Function to post on a resource
344 * @param representation which can either have all the attribute names and values
345 * (which will represent entire state of the resource) or a
346 * set of attribute names and values which needs to be modified
347 * The callback function will be invoked with a map of attribute name and values.
348 * The callback function will also have the result from this Put operation
349 * This will have error codes
350 * @param queryParametersMap map which can have the query parameter name and value
351 * @param attributeHandler attribute handler
352 * @param QoS the quality of communication
353 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
354 * @note OCStackResult is defined in ocstack.h.
356 OCStackResult post(const OCRepresentation& representation,
357 const QueryParamsMap& queryParametersMap, PostCallback attributeHandler,
358 QualityOfService QoS);
361 * Function to post on a resource
363 * @param resourceType resource type of the resource to operate on
364 * @param resourceInterface interface type of the resource to operate on
365 * @param representation representation of the resource
366 * @param queryParametersMap Map which can have the query parameter name and value
367 * @param attributeHandler attribute handler
368 * The callback function will be invoked with a map of attribute name and values.
369 * The callback function will also have the result from this Put operation
370 * This will have error codes.
371 * The Representation parameter maps which can either have all the attribute names
373 * (which will represent entire state of the resource) or a
374 * set of attribute names and values which needs to be modified
375 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
376 * @note OCStackResult is defined in ocstack.h.
379 OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
380 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
381 PostCallback attributeHandler);
383 * Function to post on a resource
385 * @param resourceType resource type of the resource to operate on
386 * @param resourceInterface interface type of the resource to operate on
387 * @param representation representation of the resource
388 * @param queryParametersMap Map which can have the query parameter name and value
389 * @param attributeHandler attribute handler
390 * The callback function will be invoked with a map of attribute name and values.
391 * The callback function will also have the result from this Put operation
392 * This will have error codes.
393 * The Representation parameter maps which can either have all the attribute names
395 * (which will represent entire state of the resource) or a
396 * set of attribute names and values which needs to be modified
397 * @param QoS the quality of communication
398 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
399 * @note OCStackResult is defined in ocstack.h.
402 OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
403 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
404 PostCallback attributeHandler, QualityOfService QoS);
407 * Function to perform DELETE operation
409 * @param deleteHandler handles callback
410 * The callback function will have headerOptions and result from this Delete
411 * operation. This will have error codes
412 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
413 * @note OCStackResult is defined in ocstack.h.
416 OCStackResult deleteResource(DeleteCallback deleteHandler);
417 OCStackResult deleteResource(DeleteCallback deleteHandler, QualityOfService QoS);
420 * Function to set observation on the resource
422 * @param observeType allows the client to specify how it wants to observe.
423 * @param queryParametersMap map which can have the query parameter name and value
424 * @param observeHandler handles callback
425 * The callback function will be invoked with a map of attribute name and values.
426 * The callback function will also have the result from this observe operation
427 * This will have error codes
428 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
429 * @note OCStackResult is defined in ocstack.h.
432 OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
433 ObserveCallback observeHandler);
435 * Function to set observation on the resource
437 * @param observeType allows the client to specify how it wants to observe.
438 * @param queryParametersMap map which can have the query parameter name and value
439 * @param observeHandler handles callback
440 * The callback function will be invoked with a map of attribute name and values.
441 * The callback function will also have the result from this observe operation
442 * This will have error codes
443 * @param qos the quality of communication
444 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
445 * @note OCStackResult is defined in ocstack.h.
448 OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
449 ObserveCallback observeHandler, QualityOfService qos);
452 * Function to cancel the observation on the resource
454 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
455 * @note OCStackResult is defined in ocstack.h.
458 OCStackResult cancelObserve();
459 OCStackResult cancelObserve(QualityOfService qos);
462 * Function to set header information.
463 * @param headerOptions std::vector where header information(header optionID and optionData
466 * @note Once the headers information is set, it will be applicable to GET, PUT and observe
468 * setHeaderOptions can be used multiple times if headers need to be modifed by the client.
469 * Latest headers will be used to send in the request. <br>
470 * @note Initial support is only for two headers. If headerMap consists of more than two
471 * header options, they will be ignored. <br>
472 * Use unsetHeaderOptions API to clear the header information.
474 void setHeaderOptions(const HeaderOptions& headerOptions);
477 * Function to unset header options.
479 void unsetHeaderOptions();
482 * Function to get the host address of this resource
483 * @return std::string host address
484 * @note This might or might not be exposed in future due to security concerns
486 std::string host() const;
489 * Function to set host address information.
491 * @param host std::string host address
493 * CoAP over UDP prefix "coap://"
494 * CoAP over TCP prefix "coap+tcp://"
495 * CoAP over DTLS prefix "coaps://"
496 * CoAP over TLS prefix "coaps+tcp://"
497 * CoAP over RFCOMM prefix "coap+rfcomm://"
498 * CoAP over GATT prefix "coap+gatt://"
500 * IPv6 address "[1234::5678]"
501 * IPv4 address "192.168.1.1"
502 * optional port ":5683"
504 * @note This should be in the format coap://address:port.
505 * If host has different connectivity type with a given OCResource object
506 * which was discovered after calling findResource API, raise an exception on failure.
509 void setHost(const std::string& host);
512 * Function to get the URI for this resource
513 * @return std::string resource URI
515 std::string uri() const;
518 * Function to get the connectivity type of this resource
519 * @return enum connectivity type (flags and adapter)
521 OCConnectivityType connectivityType() const;
524 * Function to provide ability to check if this resource is observable or not
525 * @return bool true indicates resource is observable; false indicates resource is
528 bool isObservable() const;
530 OCDevAddr getDevAddr() const;
534 * Function to provide ability to check if this resource is publisher or not
535 * @return bool true indicates resource is publisher; false indicates resource is
538 bool isPublish() const;
542 * Function to get the list of resource types
543 * @return vector of resource types
545 std::vector<std::string> getResourceTypes() const;
548 * Function to get the list of resource interfaces
549 * @return vector of resource interface
551 std::vector<std::string> getResourceInterfaces(void) const;
553 // TODO-CA Revisit this since we are exposing two identifiers
555 * Function to get a unique identifier for this
556 * resource across network interfaces. This will
557 * be guaranteed unique for every resource-per-server
558 * independent of how this was discovered.
559 * @return OCResourceIdentifier object, which can
560 * be used for all comparison and hashing.
562 OCResourceIdentifier uniqueIdentifier() const;
565 * Function to get a string representation of the resource's server ID.
566 * This is unique per- server independent on how it was discovered.
567 * @note The format of the return value is subject to change and will
568 * likely change both in size and contents in the future.
570 std::string sid() const;
573 * Function to get a string representation of the human friendly name defined by the vendor.
574 * @note The format of the return value is subject to change and will
575 * likely change both in size and contents in the future.
577 std::string deviceName() const;
581 * Function to discovery Topics from MQ Broker.
583 * @param queryParametersMap map which can have the query parameter name and value
584 * @param attributeHandler handles callback
585 * @param qos the quality of communication
587 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
588 * @note OCStackResult is defined in ocstack.h.
591 OCStackResult discoveryMQTopics(const QueryParamsMap& queryParametersMap,
592 MQTopicCallback attributeHandler,
593 QualityOfService qos);
595 * Function to create Topic into MQ Broker.
596 * SubTopic is also created through this method.
598 * @param rep representation of the topic
599 * @param topicUri new uri of the topic which want to create
600 * @param queryParametersMap map which can have the query parameter name and value
601 * @param attributeHandler handles callback
602 * @param qos the quality of communication
604 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
605 * @note OCStackResult is defined in ocstack.h.
608 OCStackResult createMQTopic(const OCRepresentation& rep,
609 const std::string& topicUri,
610 const QueryParamsMap& queryParametersMap,
611 MQTopicCallback attributeHandler,
612 QualityOfService qos);
616 * Function to subscribe Topic to MQ Broker.
618 * @param observeType allows the client to specify how it wants to observe.
619 * @param queryParametersMap map which can have the query parameter name and value
620 * @param observeHandler handles callback
621 * @param qos the quality of communication
623 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
624 * @note OCStackResult is defined in ocstack.h.
627 OCStackResult subscribeMQTopic(ObserveType observeType,
628 const QueryParamsMap& queryParametersMap,
629 ObserveCallback observeHandler,
630 QualityOfService qos);
633 * Function to unsubscribe Topic to MQ Broker.
635 * @param qos the quality of communication
637 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
638 * @note OCStackResult is defined in ocstack.h.
641 OCStackResult unsubscribeMQTopic(QualityOfService qos);
644 * Function to request publish to MQ publisher.
645 * Publisher can confirm the request message as key:"req_pub" and value:"true".
647 * @param queryParametersMap map which can have the query parameter name and value
648 * @param attributeHandler handles callback
649 * @param qos the quality of communication
651 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
652 * @note OCStackResult is defined in ocstack.h.
655 OCStackResult requestMQPublish(const QueryParamsMap& queryParametersMap,
656 PostCallback attributeHandler,
657 QualityOfService qos);
661 * Function to publish Topic information into MQ Broker.
663 * @param rep representation of the topic
664 * @param queryParametersMap map which can have the query parameter name and value
665 * @param attributeHandler handles callback
666 * @param qos the quality of communication
668 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
669 * @note OCStackResult is defined in ocstack.h.
672 OCStackResult publishMQTopic(const OCRepresentation& rep,
673 const QueryParamsMap& queryParametersMap,
674 PostCallback attributeHandler,
675 QualityOfService qos);
677 // overloaded operators allow for putting into a 'set'
678 // the uniqueidentifier allows for putting into a hash
679 bool operator==(const OCResource &other) const;
681 bool operator!=(const OCResource &other) const;
683 bool operator<(const OCResource &other) const;
685 bool operator>(const OCResource &other) const;
687 bool operator<=(const OCResource &other) const;
689 bool operator>=(const OCResource &other) const;
692 std::weak_ptr<IClientWrapper> m_clientWrapper;
694 OCResourceIdentifier m_resourceId;
696 bool m_useHostString;
699 std::vector<std::string> m_resourceTypes;
700 std::vector<std::string> m_interfaces;
701 std::vector<std::string> m_children;
702 OCDoHandle m_observeHandle;
703 std::string m_deviceName;
704 HeaderOptions m_headerOptions;
707 OCResource(std::weak_ptr<IClientWrapper> clientWrapper,
708 const OCDevAddr& devAddr, const std::string& uri,
709 const std::string& serverId, uint8_t property,
710 const std::vector<std::string>& resourceTypes,
711 const std::vector<std::string>& interfaces,
712 const std::string& deviceName);
714 OCResource(std::weak_ptr<IClientWrapper> clientWrapper,
715 const std::string& host, const std::string& uri,
716 const std::string& serverId,
717 OCConnectivityType connectivityType, uint8_t property,
718 const std::vector<std::string>& resourceTypes,
719 const std::vector<std::string>& interfaces,
720 const std::string& deviceName);
725 #endif // OC_RESOURCE_H