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 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
21 /// @file OCResource.h
23 /// @brief This file contains the declaration of classes and its members related to
26 #ifndef __OCRESOURCE_H
27 #define __OCRESOURCE_H
33 #include <boost/property_tree/ptree.hpp>
34 #include <boost/property_tree/json_parser.hpp>
37 #include <ResourceInitException.h>
38 #include <IClientWrapper.h>
39 #include <InProcClientWrapper.h>
40 #include <OCRepresentation.h>
45 * @brief OCResource represents an OC resource. A resource could be a light controller,
46 * temperature sensor, smoke detector, etc. A resource comes with a well-defined
47 * contract or interface onto which you can perform different operations, such as
48 * turning on the light, getting the current temperature or subscribing for event
49 * notifications from the smoke detector. A resource can be composed of one or
54 friend class OCPlatform_impl;
55 friend class InProcClientWrapper;
58 typedef std::shared_ptr<OCResource> Ptr;
62 virtual ~OCResource(void);
65 * Function to get the attributes of a resource.
66 * @param queryParametersMap map which can have the query parameter name and value
67 * @param attributeHandler handles callback
68 * The callback function will be invoked with a map of attribute name and values.
69 * The callback function will also have the result from this Get operation
70 * This will have error codes
71 * @param QualityOfService the quality of communication
72 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
73 * NOTE: OCStackResult is defined in ocstack.h.
75 OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
76 OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
77 QualityOfService QoS);
80 * Function to get the attributes of a resource.
82 * @param resourceType resourceType of the resource operate on
83 * @param resourceInterface interface type of the resource to operate on
84 * @param queryParametersMap map which can have the query parameter name and value
85 * @param attributeHandler handles callback
86 * The callback function will be invoked with a map of attribute name and values.
87 * The callback function will be invoked with a list of URIs if 'get' is invoked on a
88 * resource container (list will be empty if not a container)
89 * The callback function will also have the result from this Get operation. This will
91 * @param QualityOfService the quality of communication
92 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
93 * NOTE: OCStackResult is defined in ocstack.h.<br>
95 * Consider resource "a/home" (with link interface and resource type as home) contains links
96 * to "a/kitchen" and "a/room".
97 * Step 1: get("home", Link_Interface, &onGet)<br>
98 * Callback onGet will receive a) Empty attribute map because there are no attributes for
100 * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
102 * NOTE: A resource may contain single or multiple resource types. Also, a resource may
103 * contain single or multiple interfaces.<br>
104 * Currently, single GET request is allowed to do operate on single resource type or resource
105 * interface. In future, a single GET <br>
106 * can operate on multiple resource types and interfaces. <br>
107 * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned
108 * resources at a node.<br>
110 OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
111 const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
112 OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
113 const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
114 QualityOfService QoS);
117 * Function to set the representation of a resource (via PUT)
118 * @param representation which can either have all the attribute names and values
119 (which will represent entire state of the resource) or a
120 * set of attribute names and values which needs to be modified
121 * The callback function will be invoked with a map of attribute name and values.
122 * The callback function will also have the result from this Put operation
123 * This will have error codes
124 * @param queryParametersMap map which can have the query parameter name and value
125 * @param attributeHandler attribute handler
126 * @param QualityOfService the quality of communication
127 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
128 * NOTE: OCStackResult is defined in ocstack.h.
130 OCStackResult put(const OCRepresentation& representation,
131 const QueryParamsMap& queryParametersMap, PutCallback attributeHandler);
132 OCStackResult put(const OCRepresentation& representation,
133 const QueryParamsMap& queryParametersMap, PutCallback attributeHandler,
134 QualityOfService QoS);
137 * Function to set the attributes of a resource (via PUT)
138 * @param resourceType resource type of the resource to operate on
139 * @param resourceInterface interface type of the resource to operate on
140 * @param representation representation of the resource
141 * @param queryParametersMap Map which can have the query parameter name and value
142 * @param attributeHandler attribute handler
143 * The callback function will be invoked with a map of attribute name and values.
144 * The callback function will also have the result from this Put operation
145 * This will have error codes.
146 * The Representation parameter maps which can either have all the attribute names
148 * (which will represent entire state of the resource) or a
149 * set of attribute names and values which needs to be modified
150 * @param QualityOfService the quality of communication
151 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
152 * NOTE: OCStackResult is defined in ocstack.h. <br>
154 OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
155 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
156 PutCallback attributeHandler);
157 OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
158 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
159 PutCallback attributeHandler, QualityOfService QoS);
162 * Function to post on a resource
163 * @param representation which can either have all the attribute names and values
164 (which will represent entire state of the resource) or a
165 * set of attribute names and values which needs to be modified
166 * The callback function will be invoked with a map of attribute name and values.
167 * The callback function will also have the result from this Put operation
168 * This will have error codes
169 * @param queryParametersMap map which can have the query parameter name and value
170 * @param attributeHandler attribute handler
171 * @param QualityOfService the quality of communication
172 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
173 * NOTE: OCStackResult is defined in ocstack.h.
175 OCStackResult post(const OCRepresentation& representation,
176 const QueryParamsMap& queryParametersMap, PostCallback attributeHandler);
177 OCStackResult post(const OCRepresentation& representation,
178 const QueryParamsMap& queryParametersMap, PostCallback attributeHandler,
179 QualityOfService QoS);
182 * Function to post on a resource
183 * @param resourceType resource type of the resource to operate on
184 * @param resourceInterface interface type of the resource to operate on
185 * @param representation representation of the resource
186 * @param queryParametersMap Map which can have the query parameter name and value
187 * @param attributeHandler attribute handler
188 * The callback function will be invoked with a map of attribute name and values.
189 * The callback function will also have the result from this Put operation
190 * This will have error codes.
191 * The Representation parameter maps which can either have all the attribute names
193 * (which will represent entire state of the resource) or a
194 * set of attribute names and values which needs to be modified
195 * @param QualityOfService the quality of communication
196 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
197 * NOTE: OCStackResult is defined in ocstack.h. <br>
199 OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
200 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
201 PostCallback attributeHandler);
202 OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
203 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
204 PostCallback attributeHandler, QualityOfService QoS);
207 * Function to perform DELETE operation
208 * @param observeHandler handles callback
209 * The callback function will have headerOptions and result from this Delete
210 * operation. This will have error codes
211 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
212 * NOTE: OCStackResult is defined in ocstack.h.
214 OCStackResult deleteResource(DeleteCallback deleteHandler);
215 OCStackResult deleteResource(DeleteCallback deleteHandler, QualityOfService QoS);
218 * Function to set observation on the resource
219 * @param observeType allows the client to specify how it wants to observe.
220 * @param queryParametersMap map which can have the query parameter name and value
221 * @param observeHandler handles callback
222 * The callback function will be invoked with a map of attribute name and values.
223 * The callback function will also have the result from this observe operation
224 * This will have error codes
225 * @param QualityOfService the quality of communication
226 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
227 * NOTE: OCStackResult is defined in ocstack.h.
229 OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
230 ObserveCallback observeHandler);
231 OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
232 ObserveCallback observeHandler, QualityOfService qos);
235 * Function to cancel the observation on the resource
236 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
237 * NOTE: OCStackResult is defined in ocstack.h.
239 OCStackResult cancelObserve();
240 OCStackResult cancelObserve(QualityOfService qos);
243 * Function to set header information.
244 * @param headerOptions std::vector where header information(header optionID and optionData
247 * NOTE: Once the headers information is set, it will be applicable to GET, PUT and observe
249 * setHeaderOptions can be used multiple times if headers need to be modifed by the client.
250 * Latest headers will be used to send in the request. <br>
251 * NOTE: Initial support is only for two headers. If headerMap consists of more than two
252 * header options, they will be ignored. <br>
253 * Use unsetHeaderOptions API to clear the header information.
255 void setHeaderOptions(const HeaderOptions& headerOptions)
257 m_headerOptions = headerOptions;
261 * Function to unset header options.
263 void unsetHeaderOptions()
265 m_headerOptions.clear();
269 * Function to get the host address of this resource
270 * @return std::string host address
271 * NOTE: This might or might not be exposed in future due to security concerns
273 std::string host() const;
276 * Function to get the URI for this resource
277 * @return std::string resource URI
279 std::string uri() const;
282 * Function to provide ability to check if this resource is observable or not
283 * @return bool true indicates resource is observable; false indicates resource is
286 bool isObservable() const;
289 * Function to get the list of resource types
290 * @return vector of resource types
292 std::vector<std::string> getResourceTypes() const
294 return m_resourceTypes;
298 * Function to get the list of resource interfaces
299 * @return vector of resource interface
301 std::vector<std::string> getResourceInterfaces(void) const
307 std::weak_ptr<IClientWrapper> m_clientWrapper;
312 std::vector<std::string> m_resourceTypes;
313 std::vector<std::string> m_interfaces;
314 std::vector<std::string> m_children;
315 OCDoHandle m_observeHandle;
316 HeaderOptions m_headerOptions;
319 OCResource(std::weak_ptr<IClientWrapper> clientWrapper, const std::string& host,
320 const std::string& uri, bool observable, const std::vector<std::string>& resourceTypes,
321 const std::vector<std::string>& interfaces);
326 #endif //__OCRESOURCE_H