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;
55 friend class InProcClientWrapper;
57 typedef std::shared_ptr<OCResource> Ptr;
61 virtual ~OCResource(void);
64 * Function to get the attributes of a resource.
65 * @param queryParametersMap map which can have the query parameter name and value
66 * @param attributeHandler handles callback
67 * The callback function will be invoked with a map of attribute name and values.
68 * The callback function will also have the result from this Get operation
69 * This will have error codes
70 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
71 * NOTE: OCStackResult is defined in ocstack.h.
73 OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
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 resource container
84 * (list will be empty if not a container)
85 * The callback function will also have the result from this Get operation. This will have error codes
86 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
87 * NOTE: OCStackResult is defined in ocstack.h.<br>
89 * Consider resource "a/home" (with link interface and resource type as home) contains links to "a/kitchen" and "a/room".
90 * Step 1: get("home", Link_Interface, &onGet)<br>
91 * Callback onGet will receive a) Empty attribute map because there are no attributes for a/home b) list with
92 * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET operation<br>
93 * NOTE: A resource may contain single or multiple resource types. Also, a resource may contain single or multiple interfaces.<br>
94 * Currently, single GET request is allowed to do operate on single resource type or resource interface. In future, a single GET <br>
95 * can operate on multiple resource types and interfaces. <br>
96 * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned resources at a node.<br>
98 OCStackResult get(const std::string& resourceType, const std::string& resourceInterface, const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
101 * Function to set the attributes of a resource (via PUT)
102 * @param attributeMap Map which can either have all the attribute names and values
103 (which will represent entire state of the resource) or a
104 * set of attribute names and values which needs to be modified
105 * The callback function will be invoked with a map of attribute name and values.
106 * The callback function will also have the result from this Put operation
107 * This will have error codes
108 * @param queryParametersMap map which can have the query parameter name and value
109 * @param attributeHandler attribute handler
110 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
111 * NOTE: OCStackResult is defined in ocstack.h.
113 OCStackResult put(const OCRepresentation& attributeMap, const QueryParamsMap& queryParametersMap,
114 PutCallback attributeHandler);
117 * Function to set the attributes of a resource (via PUT)
118 * @param resourceType resource type of the resource to operate on
119 * @param resourceInterface interface type of the resource to operate on
120 * @param attributeMap attribute map
121 * @param queryParametersMap Map which can have the query parameter name and value
122 * @param attributeHandler attribute handler
123 * The callback function will be invoked with a map of attribute name and values.
124 * The callback function will also have the result from this Put operation
125 * This will have error codes.
126 * The AttributeMap parameter maps which can either have all the attribute names and values
127 * (which will represent entire state of the resource) or a
128 * set of attribute names and values which needs to be modified
129 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
130 * NOTE: OCStackResult is defined in ocstack.h. <br>
132 OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
133 const OCRepresentation& attributeMap, const QueryParamsMap& queryParametersMap,
134 PutCallback attributeHandler);
137 * Function to set observation on the resource
138 * @param observeType allows the client to specify how it wants to observe.
139 * @param queryParametersMap map which can have the query parameter name and value
140 * @param observeHandler handles callback
141 * The callback function will be invoked with a map of attribute name and values.
142 * The callback function will also have the result from this observe operation
143 * This will have error codes
144 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
145 * NOTE: OCStackResult is defined in ocstack.h.
147 OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
148 ObserveCallback observeHandler);
151 * Function to cancel the observation on the resource
152 * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
153 * NOTE: OCStackResult is defined in ocstack.h.
155 OCStackResult cancelObserve();
158 * Function to get the host address of this resource
159 * @return std::string host address
160 * NOTE: This might or might not be exposed in future due to security concerns
162 std::string host() const;
165 * Function to get the URI for this resource
166 * @return std::string resource URI
168 std::string uri() const;
171 * Function to provide ability to check if this resource is observable or not
172 * @return bool true indicates resource is observable; false indicates resource is
175 bool isObservable() const;
178 * Function to get the list of resource types
179 * @return vector of resource types
181 std::vector<std::string> getResourceTypes() const
183 return m_resourceTypes;
187 * Function to get the list of resource interfaces
188 * @return vector of resource interface
190 std::vector<std::string> getResourceInterfaces(void) const
196 std::weak_ptr<IClientWrapper> m_clientWrapper;
201 std::vector<std::string> m_resourceTypes;
202 std::vector<std::string> m_interfaces;
203 std::vector<std::string> m_children;
204 OCDoHandle m_observeHandle;
207 OCResource(std::weak_ptr<IClientWrapper> clientWrapper, const std::string& host, const std::string& uri,
208 bool observable, const std::vector<std::string>& resourceTypes, const std::vector<std::string>& interfaces);
213 #endif //__OCRESOURCE_H