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
34 #include <ResourceInitException.h>
35 #include <IClientWrapper.h>
36 #include <InProcClientWrapper.h>
37 #include <OCRepresentation.h>
42 * @brief OCResource represents an OC resource. A resource could be a light controller,
43 * temperature sensor, smoke detector, etc. A resource comes with a well-defined
44 * contract or interface onto which you can perform different operations, such as
45 * turning on the light, getting the current temperature or subscribing for event
46 * notifications from the smoke detector. A resource can be composed of one or
51 friend class OCPlatform_impl;
52 friend class ListenOCContainer;
54 typedef std::shared_ptr<OCResource> Ptr;
58 virtual ~OCResource(void);
61 * Function to get the attributes of a resource.
62 * @param queryParametersMap map which can have the query parameter name and value
63 * @param attributeHandler handles callback
64 * The callback function will be invoked with a map of attribute name and values.
65 * The callback function will also have the result from this Get operation
66 * This will have error codes
67 * @param QualityOfService the quality of communication
68 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
69 * NOTE: OCStackResult is defined in ocstack.h.
71 OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
72 OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
73 QualityOfService QoS);
76 * Function to get the attributes of a resource.
78 * @param resourceType resourceType of the resource operate on
79 * @param resourceInterface interface type of the resource to operate on
80 * @param queryParametersMap map which can have the query parameter name and value
81 * @param attributeHandler handles callback
82 * The callback function will be invoked with a map of attribute name and values.
83 * The callback function will be invoked with a list of URIs if 'get' is invoked on a
84 * resource container (list will be empty if not a container)
85 * The callback function will also have the result from this Get operation. This will
87 * @param QualityOfService the quality of communication
88 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
89 * NOTE: OCStackResult is defined in ocstack.h.<br>
91 * Consider resource "a/home" (with link interface and resource type as home) contains links
92 * to "a/kitchen" and "a/room".
93 * Step 1: get("home", Link_Interface, &onGet)<br>
94 * Callback onGet will receive a) Empty attribute map because there are no attributes for
96 * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
98 * NOTE: A resource may contain single or multiple resource types. Also, a resource may
99 * contain single or multiple interfaces.<br>
100 * Currently, single GET request is allowed to do operate on single resource type or resource
101 * interface. In future, a single GET <br>
102 * can operate on multiple resource types and interfaces. <br>
103 * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned
104 * resources at a node.<br>
106 OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
107 const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
108 OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
109 const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
110 QualityOfService QoS);
113 * Function to set the representation of a resource (via PUT)
114 * @param representation which can either have all the attribute names and values
115 (which will represent entire state of the resource) or a
116 * set of attribute names and values which needs to be modified
117 * The callback function will be invoked with a map of attribute name and values.
118 * The callback function will also have the result from this Put operation
119 * This will have error codes
120 * @param queryParametersMap map which can have the query parameter name and value
121 * @param attributeHandler attribute handler
122 * @param QualityOfService the quality of communication
123 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
124 * NOTE: OCStackResult is defined in ocstack.h.
126 OCStackResult put(const OCRepresentation& representation,
127 const QueryParamsMap& queryParametersMap, PutCallback attributeHandler);
128 OCStackResult put(const OCRepresentation& representation,
129 const QueryParamsMap& queryParametersMap, PutCallback attributeHandler,
130 QualityOfService QoS);
133 * Function to set the attributes of a resource (via PUT)
134 * @param resourceType resource type of the resource to operate on
135 * @param resourceInterface interface type of the resource to operate on
136 * @param representation representation of the resource
137 * @param queryParametersMap Map which can have the query parameter name and value
138 * @param attributeHandler attribute handler
139 * The callback function will be invoked with a map of attribute name and values.
140 * The callback function will also have the result from this Put operation
141 * This will have error codes.
142 * The Representation parameter maps which can either have all the attribute names
144 * (which will represent entire state of the resource) or a
145 * set of attribute names and values which needs to be modified
146 * @param QualityOfService the quality of communication
147 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
148 * NOTE: OCStackResult is defined in ocstack.h. <br>
150 OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
151 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
152 PutCallback attributeHandler);
153 OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
154 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
155 PutCallback attributeHandler, QualityOfService QoS);
158 * Function to post on a resource
159 * @param representation which can either have all the attribute names and values
160 (which will represent entire state of the resource) or a
161 * set of attribute names and values which needs to be modified
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 Put operation
164 * This will have error codes
165 * @param queryParametersMap map which can have the query parameter name and value
166 * @param attributeHandler attribute handler
167 * @param QualityOfService the quality of communication
168 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
169 * NOTE: OCStackResult is defined in ocstack.h.
171 OCStackResult post(const OCRepresentation& representation,
172 const QueryParamsMap& queryParametersMap, PostCallback attributeHandler);
173 OCStackResult post(const OCRepresentation& representation,
174 const QueryParamsMap& queryParametersMap, PostCallback attributeHandler,
175 QualityOfService QoS);
178 * Function to post on a resource
179 * @param resourceType resource type of the resource to operate on
180 * @param resourceInterface interface type of the resource to operate on
181 * @param representation representation of the resource
182 * @param queryParametersMap Map which can have the query parameter name and value
183 * @param attributeHandler attribute handler
184 * The callback function will be invoked with a map of attribute name and values.
185 * The callback function will also have the result from this Put operation
186 * This will have error codes.
187 * The Representation parameter maps which can either have all the attribute names
189 * (which will represent entire state of the resource) or a
190 * set of attribute names and values which needs to be modified
191 * @param QualityOfService the quality of communication
192 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
193 * NOTE: OCStackResult is defined in ocstack.h. <br>
195 OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
196 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
197 PostCallback attributeHandler);
198 OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
199 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
200 PostCallback attributeHandler, QualityOfService QoS);
203 * Function to perform DELETE operation
204 * @param observeHandler handles callback
205 * The callback function will have headerOptions and result from this Delete
206 * operation. This will have error codes
207 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
208 * NOTE: OCStackResult is defined in ocstack.h.
210 OCStackResult deleteResource(DeleteCallback deleteHandler);
211 OCStackResult deleteResource(DeleteCallback deleteHandler, QualityOfService QoS);
214 * Function to set observation on the resource
215 * @param observeType allows the client to specify how it wants to observe.
216 * @param queryParametersMap map which can have the query parameter name and value
217 * @param observeHandler handles callback
218 * The callback function will be invoked with a map of attribute name and values.
219 * The callback function will also have the result from this observe operation
220 * This will have error codes
221 * @param QualityOfService the quality of communication
222 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
223 * NOTE: OCStackResult is defined in ocstack.h.
225 OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
226 ObserveCallback observeHandler);
227 OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
228 ObserveCallback observeHandler, QualityOfService qos);
231 * Function to cancel the observation on the resource
232 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
233 * NOTE: OCStackResult is defined in ocstack.h.
235 OCStackResult cancelObserve();
236 OCStackResult cancelObserve(QualityOfService qos);
239 * Function to set header information.
240 * @param headerOptions std::vector where header information(header optionID and optionData
243 * NOTE: Once the headers information is set, it will be applicable to GET, PUT and observe
245 * setHeaderOptions can be used multiple times if headers need to be modifed by the client.
246 * Latest headers will be used to send in the request. <br>
247 * NOTE: Initial support is only for two headers. If headerMap consists of more than two
248 * header options, they will be ignored. <br>
249 * Use unsetHeaderOptions API to clear the header information.
251 void setHeaderOptions(const HeaderOptions& headerOptions)
253 m_headerOptions = headerOptions;
257 * Function to unset header options.
259 void unsetHeaderOptions()
261 m_headerOptions.clear();
265 * Function to get the host address of this resource
266 * @return std::string host address
267 * NOTE: This might or might not be exposed in future due to security concerns
269 std::string host() const;
272 * Function to get the URI for this resource
273 * @return std::string resource URI
275 std::string uri() const;
278 * Function to provide ability to check if this resource is observable or not
279 * @return bool true indicates resource is observable; false indicates resource is
282 bool isObservable() const;
285 * Function to get the list of resource types
286 * @return vector of resource types
288 std::vector<std::string> getResourceTypes() const
290 return m_resourceTypes;
294 * Function to get the list of resource interfaces
295 * @return vector of resource interface
297 std::vector<std::string> getResourceInterfaces(void) const
303 std::weak_ptr<IClientWrapper> m_clientWrapper;
308 std::vector<std::string> m_resourceTypes;
309 std::vector<std::string> m_interfaces;
310 std::vector<std::string> m_children;
311 OCDoHandle m_observeHandle;
312 HeaderOptions m_headerOptions;
315 OCResource(std::weak_ptr<IClientWrapper> clientWrapper, const std::string& host,
316 const std::string& uri, bool observable, const std::vector<std::string>& resourceTypes,
317 const std::vector<std::string>& interfaces);
322 #endif //__OCRESOURCE_H