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 class OCResourceIdentifier;
43 ostream& operator <<(ostream& os, const OCResourceIdentifier& ri);
45 * @brief OCResourceIdentifier represents the identity information for a server. This
46 * object combined with the OCResource's URI property uniquely identify an
47 * OCResource on or across networks.
48 * Equality operators are implemented. However, internal representation is subject
49 * to change and thus should not be accessed or depended on.
51 class OCResourceIdentifier
53 friend class OCResource;
54 friend ostream& operator <<(ostream& os, const OCResourceIdentifier& ri);
57 bool operator==(const OCResourceIdentifier &other) const;
59 bool operator!=(const OCResourceIdentifier &other) const;
61 bool operator<(const OCResourceIdentifier &other) const;
63 bool operator>(const OCResourceIdentifier &other) const;
65 bool operator<=(const OCResourceIdentifier &other) const;
67 bool operator>=(const OCResourceIdentifier &other) const;
71 OCResourceIdentifier(const std::string& wireServerIdentifier,
72 const std::string& resourceUri );
75 uint32_t m_representation;
76 const std::string& m_resourceUri;
80 * @brief OCResource represents an OC resource. A resource could be a light controller,
81 * temperature sensor, smoke detector, etc. A resource comes with a well-defined
82 * contract or interface onto which you can perform different operations, such as
83 * turning on the light, getting the current temperature or subscribing for event
84 * notifications from the smoke detector. A resource can be composed of one or
89 friend class OCPlatform_impl;
90 friend class ListenOCContainer;
92 typedef std::shared_ptr<OCResource> Ptr;
96 virtual ~OCResource(void);
99 * Function to get the attributes of a resource.
100 * @param queryParametersMap map which can have the query parameter name and value
101 * @param attributeHandler handles callback
102 * The callback function will be invoked with a map of attribute name and values.
103 * The callback function will also have the result from this Get operation
104 * This will have error codes
105 * @param QualityOfService the quality of communication
106 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
107 * NOTE: OCStackResult is defined in ocstack.h.
109 OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
110 OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
111 QualityOfService QoS);
114 * Function to get the attributes of a resource.
116 * @param resourceType resourceType of the resource operate on
117 * @param resourceInterface interface type of the resource to operate on
118 * @param queryParametersMap map which can have the query parameter name and value
119 * @param attributeHandler handles callback
120 * The callback function will be invoked with a map of attribute name and values.
121 * The callback function will be invoked with a list of URIs if 'get' is invoked on a
122 * resource container (list will be empty if not a container)
123 * The callback function will also have the result from this Get operation. This will
125 * @param QualityOfService the quality of communication
126 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
127 * NOTE: OCStackResult is defined in ocstack.h.<br>
128 * <b>Example:</b><br>
129 * Consider resource "a/home" (with link interface and resource type as home) contains links
130 * to "a/kitchen" and "a/room".
131 * Step 1: get("home", Link_Interface, &onGet)<br>
132 * Callback onGet will receive a) Empty attribute map because there are no attributes for
133 * a/home b) list with
134 * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
136 * NOTE: A resource may contain single or multiple resource types. Also, a resource may
137 * contain single or multiple interfaces.<br>
138 * Currently, single GET request is allowed to do operate on single resource type or resource
139 * interface. In future, a single GET <br>
140 * can operate on multiple resource types and interfaces. <br>
141 * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned
142 * resources at a node.<br>
144 OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
145 const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
146 OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
147 const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
148 QualityOfService QoS);
151 * Function to set the representation of a resource (via PUT)
152 * @param representation which can either have all the attribute names and values
153 (which will represent entire state of the resource) or a
154 * set of attribute names and values which needs to be modified
155 * The callback function will be invoked with a map of attribute name and values.
156 * The callback function will also have the result from this Put operation
157 * This will have error codes
158 * @param queryParametersMap map which can have the query parameter name and value
159 * @param attributeHandler attribute handler
160 * @param QualityOfService the quality of communication
161 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
162 * NOTE: OCStackResult is defined in ocstack.h.
164 OCStackResult put(const OCRepresentation& representation,
165 const QueryParamsMap& queryParametersMap, PutCallback attributeHandler);
166 OCStackResult put(const OCRepresentation& representation,
167 const QueryParamsMap& queryParametersMap, PutCallback attributeHandler,
168 QualityOfService QoS);
171 * Function to set the attributes of a resource (via PUT)
172 * @param resourceType resource type of the resource to operate on
173 * @param resourceInterface interface type of the resource to operate on
174 * @param representation representation of the resource
175 * @param queryParametersMap Map which can have the query parameter name and value
176 * @param attributeHandler attribute handler
177 * The callback function will be invoked with a map of attribute name and values.
178 * The callback function will also have the result from this Put operation
179 * This will have error codes.
180 * The Representation parameter maps which can either have all the attribute names
182 * (which will represent entire state of the resource) or a
183 * set of attribute names and values which needs to be modified
184 * @param QualityOfService the quality of communication
185 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
186 * NOTE: OCStackResult is defined in ocstack.h. <br>
188 OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
189 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
190 PutCallback attributeHandler);
191 OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
192 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
193 PutCallback attributeHandler, QualityOfService QoS);
196 * Function to post on a resource
197 * @param representation which can either have all the attribute names and values
198 (which will represent entire state of the resource) or a
199 * set of attribute names and values which needs to be modified
200 * The callback function will be invoked with a map of attribute name and values.
201 * The callback function will also have the result from this Put operation
202 * This will have error codes
203 * @param queryParametersMap map which can have the query parameter name and value
204 * @param attributeHandler attribute handler
205 * @param QualityOfService the quality of communication
206 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
207 * NOTE: OCStackResult is defined in ocstack.h.
209 OCStackResult post(const OCRepresentation& representation,
210 const QueryParamsMap& queryParametersMap, PostCallback attributeHandler);
211 OCStackResult post(const OCRepresentation& representation,
212 const QueryParamsMap& queryParametersMap, PostCallback attributeHandler,
213 QualityOfService QoS);
216 * Function to post on a resource
217 * @param resourceType resource type of the resource to operate on
218 * @param resourceInterface interface type of the resource to operate on
219 * @param representation representation of the resource
220 * @param queryParametersMap Map which can have the query parameter name and value
221 * @param attributeHandler attribute handler
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 Put operation
224 * This will have error codes.
225 * The Representation parameter maps which can either have all the attribute names
227 * (which will represent entire state of the resource) or a
228 * set of attribute names and values which needs to be modified
229 * @param QualityOfService the quality of communication
230 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
231 * NOTE: OCStackResult is defined in ocstack.h. <br>
233 OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
234 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
235 PostCallback attributeHandler);
236 OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
237 const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
238 PostCallback attributeHandler, QualityOfService QoS);
241 * Function to perform DELETE operation
242 * @param observeHandler handles callback
243 * The callback function will have headerOptions and result from this Delete
244 * operation. This will have error codes
245 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
246 * NOTE: OCStackResult is defined in ocstack.h.
248 OCStackResult deleteResource(DeleteCallback deleteHandler);
249 OCStackResult deleteResource(DeleteCallback deleteHandler, QualityOfService QoS);
252 * Function to set observation on the resource
253 * @param observeType allows the client to specify how it wants to observe.
254 * @param queryParametersMap map which can have the query parameter name and value
255 * @param observeHandler handles callback
256 * The callback function will be invoked with a map of attribute name and values.
257 * The callback function will also have the result from this observe operation
258 * This will have error codes
259 * @param QualityOfService the quality of communication
260 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
261 * NOTE: OCStackResult is defined in ocstack.h.
263 OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
264 ObserveCallback observeHandler);
265 OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
266 ObserveCallback observeHandler, QualityOfService qos);
269 * Function to cancel the observation on the resource
270 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
271 * NOTE: OCStackResult is defined in ocstack.h.
273 OCStackResult cancelObserve();
274 OCStackResult cancelObserve(QualityOfService qos);
277 * Function to set header information.
278 * @param headerOptions std::vector where header information(header optionID and optionData
281 * NOTE: Once the headers information is set, it will be applicable to GET, PUT and observe
283 * setHeaderOptions can be used multiple times if headers need to be modifed by the client.
284 * Latest headers will be used to send in the request. <br>
285 * NOTE: Initial support is only for two headers. If headerMap consists of more than two
286 * header options, they will be ignored. <br>
287 * Use unsetHeaderOptions API to clear the header information.
289 void setHeaderOptions(const HeaderOptions& headerOptions)
291 m_headerOptions = headerOptions;
295 * Function to unset header options.
297 void unsetHeaderOptions()
299 m_headerOptions.clear();
303 * Function to get the host address of this resource
304 * @return std::string host address
305 * NOTE: This might or might not be exposed in future due to security concerns
307 std::string host() const;
310 * Function to get the URI for this resource
311 * @return std::string resource URI
313 std::string uri() const;
316 * Function to get the connectivity type of this resource
317 * @return uint8_t connectivity type
319 OCConnectivityType connectivityType() const;
322 * Function to provide ability to check if this resource is observable or not
323 * @return bool true indicates resource is observable; false indicates resource is
326 bool isObservable() const;
329 * Function to get the list of resource types
330 * @return vector of resource types
332 std::vector<std::string> getResourceTypes() const
334 return m_resourceTypes;
338 * Function to get the list of resource interfaces
339 * @return vector of resource interface
341 std::vector<std::string> getResourceInterfaces(void) const
346 // TODO-CA Revisit this since we are exposing two identifiers
348 * Function to get a unqiue identifier for this
349 * resource across network interfaces. This will
350 * be guaranteed unique for every resource-per-server
351 * independent of how this was discovered.
352 * @return OCResourceIdentifier object, which can
353 * be used for all comparison and hashing.
355 OCResourceIdentifier uniqueIdentifier() const;
358 * Function to get a string representation of the resource's server ID.
359 * This is unique per- server independent on how it was discovered.
360 * Note: The format of the return value is subject to change and will
361 * likely change both in size and contents in the future.
363 std::string sid() const;
365 // overloaded operators allow for putting into a 'set'
366 // the uniqueidentifier allows for putting into a hash
367 bool operator==(const OCResource &other) const;
369 bool operator!=(const OCResource &other) const;
371 bool operator<(const OCResource &other) const;
373 bool operator>(const OCResource &other) const;
375 bool operator<=(const OCResource &other) const;
377 bool operator>=(const OCResource &other) const;
380 std::weak_ptr<IClientWrapper> m_clientWrapper;
382 OCResourceIdentifier m_resourceId;
384 OCConnectivityType m_connectivityType;
387 std::vector<std::string> m_resourceTypes;
388 std::vector<std::string> m_interfaces;
389 std::vector<std::string> m_children;
390 OCDoHandle m_observeHandle;
391 HeaderOptions m_headerOptions;
394 OCResource(std::weak_ptr<IClientWrapper> clientWrapper, const std::string& host,
395 const std::string& uri, const std::string& serverId,
396 OCConnectivityType m_connectivityType, bool observable,
397 const std::vector<std::string>& resourceTypes,
398 const std::vector<std::string>& interfaces);
403 #endif //__OCRESOURCE_H