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_useHostString(o.m_useHostString),
121 m_property(o.m_property),
122 m_isCollection(o.m_isCollection),
123 m_resourceTypes(std::move(o.m_resourceTypes)),
124 m_interfaces(std::move(o.m_interfaces)),
125 m_children(std::move(m_children)),
126 m_endpoints(std::move(m_endpoints)),
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 get the endpoints information of this resource
490 * @return std::vector<std::string> endpoints information
492 std::vector<std::string> getAllHosts() const;
495 * Function to get the URI for this resource
496 * @return std::string resource URI
498 std::string uri() const;
501 * Function to get the connectivity type of this resource
502 * @return enum connectivity type (flags and adapter)
504 OCConnectivityType connectivityType() const;
507 * Function to provide ability to check if this resource is observable or not
508 * @return bool true indicates resource is observable; false indicates resource is
511 bool isObservable() const;
514 * Function to change host of this reource
515 * @return std::string New host Address.
518 std::string setHost(const std::string& host);
521 * Function to provide ability to check if this resource is publisher or not
522 * @return bool true indicates resource is publisher; false indicates resource is
525 bool isPublish() const;
529 * Function to get the list of resource types
530 * @return vector of resource types
532 std::vector<std::string> getResourceTypes() const;
535 * Function to get the list of resource interfaces
536 * @return vector of resource interface
538 std::vector<std::string> getResourceInterfaces(void) const;
540 // TODO-CA Revisit this since we are exposing two identifiers
542 * Function to get a unique identifier for this
543 * resource across network interfaces. This will
544 * be guaranteed unique for every resource-per-server
545 * independent of how this was discovered.
546 * @return OCResourceIdentifier object, which can
547 * be used for all comparison and hashing.
549 OCResourceIdentifier uniqueIdentifier() const;
552 * Function to get a string representation of the resource's server ID.
553 * This is unique per- server independent on how it was discovered.
555 std::string sid() const;
559 * Function to discovery Topics from MQ Broker.
561 * @param queryParametersMap map which can have the query parameter name and value
562 * @param attributeHandler handles callback
563 * @param qos the quality of communication
565 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
566 * @note OCStackResult is defined in ocstack.h.
569 OCStackResult discoveryMQTopics(const QueryParamsMap& queryParametersMap,
570 MQTopicCallback attributeHandler,
571 QualityOfService qos);
573 * Function to create Topic into MQ Broker.
574 * SubTopic is also created through this method.
576 * @param rep representation of the topic
577 * @param topicUri new uri of the topic which want to create
578 * @param queryParametersMap map which can have the query parameter name and value
579 * @param attributeHandler handles callback
580 * @param qos the quality of communication
582 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
583 * @note OCStackResult is defined in ocstack.h.
586 OCStackResult createMQTopic(const OCRepresentation& rep,
587 const std::string& topicUri,
588 const QueryParamsMap& queryParametersMap,
589 MQTopicCallback attributeHandler,
590 QualityOfService qos);
594 * Function to subscribe Topic to MQ Broker.
596 * @param observeType allows the client to specify how it wants to observe.
597 * @param queryParametersMap map which can have the query parameter name and value
598 * @param observeHandler handles callback
599 * @param qos the quality of communication
601 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
602 * @note OCStackResult is defined in ocstack.h.
605 OCStackResult subscribeMQTopic(ObserveType observeType,
606 const QueryParamsMap& queryParametersMap,
607 ObserveCallback observeHandler,
608 QualityOfService qos);
611 * Function to unsubscribe Topic to MQ Broker.
613 * @param qos the quality of communication
615 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
616 * @note OCStackResult is defined in ocstack.h.
619 OCStackResult unsubscribeMQTopic(QualityOfService qos);
622 * Function to request publish to MQ publisher.
623 * Publisher can confirm the request message as key:"req_pub" and value:"true".
625 * @param queryParametersMap map which can have the query parameter name and value
626 * @param attributeHandler handles callback
627 * @param qos the quality of communication
629 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
630 * @note OCStackResult is defined in ocstack.h.
633 OCStackResult requestMQPublish(const QueryParamsMap& queryParametersMap,
634 PostCallback attributeHandler,
635 QualityOfService qos);
639 * Function to publish Topic information into MQ Broker.
641 * @param rep representation of the topic
642 * @param queryParametersMap map which can have the query parameter name and value
643 * @param attributeHandler handles callback
644 * @param qos the quality of communication
646 * @return Returns ::OC_STACK_OK on success, some other value upon failure.
647 * @note OCStackResult is defined in ocstack.h.
650 OCStackResult publishMQTopic(const OCRepresentation& rep,
651 const QueryParamsMap& queryParametersMap,
652 PostCallback attributeHandler,
653 QualityOfService qos);
655 // overloaded operators allow for putting into a 'set'
656 // the uniqueidentifier allows for putting into a hash
657 bool operator==(const OCResource &other) const;
659 bool operator!=(const OCResource &other) const;
661 bool operator<(const OCResource &other) const;
663 bool operator>(const OCResource &other) const;
665 bool operator<=(const OCResource &other) const;
667 bool operator>=(const OCResource &other) const;
670 std::weak_ptr<IClientWrapper> m_clientWrapper;
672 OCResourceIdentifier m_resourceId;
674 bool m_useHostString;
677 std::vector<std::string> m_resourceTypes;
678 std::vector<std::string> m_interfaces;
679 std::vector<std::string> m_children;
680 std::vector<std::string> m_endpoints;
681 OCDoHandle m_observeHandle;
682 HeaderOptions m_headerOptions;
685 OCResource(std::weak_ptr<IClientWrapper> clientWrapper,
686 const OCDevAddr& devAddr, const std::string& uri,
687 const std::string& serverId, uint8_t property,
688 const std::vector<std::string>& resourceTypes,
689 const std::vector<std::string>& interfaces);
691 OCResource(std::weak_ptr<IClientWrapper> clientWrapper,
692 const OCDevAddr& devAddr, const std::string& uri,
693 const std::string& serverId, uint8_t property,
694 const std::vector<std::string>& resourceTypes,
695 const std::vector<std::string>& interfaces,
696 const std::vector<std::string>& endpoints);
698 OCResource(std::weak_ptr<IClientWrapper> clientWrapper,
699 const std::string& host, const std::string& uri,
700 const std::string& serverId,
701 OCConnectivityType connectivityType, uint8_t property,
702 const std::vector<std::string>& resourceTypes,
703 const std::vector<std::string>& interfaces);
705 OCResource(std::weak_ptr<IClientWrapper> clientWrapper,
706 const std::string& host, const std::string& uri,
707 const std::string& serverId,
708 OCConnectivityType connectivityType, uint8_t property,
709 const std::vector<std::string>& resourceTypes,
710 const std::vector<std::string>& interfaces,
711 const std::vector<std::string>& endpoints);
716 #endif // OC_RESOURCE_H