2 * Copyright (c) 2018 Samsung Electronics Co., Ltd.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an AS IS BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_RESOURCE_H__
18 #define __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_RESOURCE_H__
24 #include <smartthings_payload.h>
31 * @file smartthings_resource.h
35 * @addtogroup CAPI_SMARTTHINGS_THING_RESOURCE_MODULE
40 * @brief Enumeration for the SmartThings resource error.
44 SMARTTHINGS_RESOURCE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
45 SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
46 SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
47 SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
48 SMARTTHINGS_RESOURCE_ERROR_NO_DATA = TIZEN_ERROR_NO_DATA, /**< No data */
49 SMARTTHINGS_RESOURCE_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
50 SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED = TIZEN_ERROR_UNKNOWN - 1, /**< Operation failed */
51 SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE = TIZEN_ERROR_UNKNOWN -2 /**< Service unavailable */
52 } smartthings_resource_error_e;
55 * @brief Enumeration for the request type of resource and collection resource.
59 SMARTTHINGS_RESOURCE_REQUEST_GET = 0, /**< Get request type */
60 SMARTTHINGS_RESOURCE_REQUEST_SET = 1, /**< Set request type */
61 SMARTTHINGS_RESOURCE_REQUEST_COLLECTION_GET = 2, /**< Get request type for collection */
62 SMARTTHINGS_RESOURCE_REQUEST_COLLECTION_SET = 3 /**< Set request type for collection */
63 } smartthings_resource_req_type_e;
66 * @brief Enumeration for RPC connection status.
70 SMARTTHINGS_RESOURCE_CONNECTION_STATUS_CONNECTED = 0, /**< Connection is connected */
71 SMARTTHINGS_RESOURCE_CONNECTION_STATUS_DISCONNECTED, /**< Connection is disconnected */
72 SMARTTHINGS_RESOURCE_CONNECTION_STATUS_REJECTED, /**< Connection is rejected */
73 } smartthings_resource_connection_status_e;
76 * @brief The SmartThings resource handle.
79 typedef struct smartthings_resource_s *smartthings_resource_h;
82 * @brief Callback for status of connection to SmartThings Thing agent.
83 * @details The following error codes can be received: \n
84 #SMARTTHINGS_RESOURCE_ERROR_NONE: Success \n
85 #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED: Permission denied \n
86 #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE: Service unavailable \n
89 * @remarks The @a handle should not be released.
90 * @remarks The @a handle is the same object for which the callback was set/added.
91 * @remarks The @a handle will be released when smartthings_deinitialize() is called.
92 * @remarks When callback is called, user can see result as #smartthings_resource_error_e enumeration value.
93 * @remarks When callback is called, user can see connection status as #smartthings_connection_status_e enumeration value.
95 * @param[in] result The result of connection operation
96 * @param[in] handle The SmartThings handle
97 * @param[in] status The status of connection
98 * @param[in] user_data The user data passed from the callback registration function
100 * @see smartthings_resource_initialize()
102 typedef void (*smartthings_resource_connection_status_cb)(smartthings_resource_error_e result, smartthings_resource_h handle, smartthings_resource_connection_status_e status, void *user_data);
106 * @brief Callback for handling request(GET/SET) messages.
109 * @remarks The @a payload is NULL when @a req_type is #SMARTTHINGS_RESOURCE_REQUEST_GET.
110 * @remarks The @a payload can be used only in the callback. To use outside, make a copy.
111 * @remarks The @a st_h should not be released.
112 * @remarks The @a st_h is the same object for which the callback was set/added.
113 * @remarks The @a st_h will be released when smartthings_resource_deinitialize() is called.
114 * @remarks The @a payload should not be released.
115 * @remarks The @a uri can be used only in the callback. To use outside, make a copy.
117 * @param[in] st_h The SmartThings resource handle
118 * @param[in] req_id The request ID of request message
119 * @param[in] uri The resource URI
120 * @param[in] req_type The request type for request message
121 * @param[in] payload The payload for SET request message
122 * @param[in] user_data The user data passed from the callback registration function
124 * @see smartthings_resource_set_request_cb()
125 * @see smartthings_resource_unset_request_cb()
127 typedef void (*smartthings_resource_request_cb)(smartthings_resource_h st_h, int req_id, const char *uri,
128 smartthings_resource_req_type_e req_type,
129 smartthings_payload_h payload, void *user_data);
132 * @brief Callback for status of resource registration to cloud.
135 * @remarks This callback will be called when status of resource registration is changed.
136 * @remarks The @a st_h should not be released.
137 * @remarks The @a st_h is the same object for which the callback was set/added.
138 * @remarks The @a st_h will be released when smartthings_resource_deinitialize() is called.
139 * @remarks The @a is_registered will be true when resources are registered to cloud.
141 * @param[in] st_h The SmartThings resource handle
142 * @param[in] is_registered The status of resource registration to cloud
143 * @param[in] user_data The user data passed from the callback registration function
145 * @see smartthings_resource_set_cloud_registration_status_cb()
146 * @see smartthings_resource_unset_cloud_registration_status_cb()
148 typedef void (*smartthings_resource_cloud_registration_status_cb)(smartthings_resource_h st_h, bool is_registered, void *user_data);
152 * @brief Initializes a resource handle and connects to agent.
154 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
155 * %http://tizen.org/privilege/appmanager.launch \n
156 * %http://tizen.org/privilege/datasharing
158 * @remarks The @a st_h must be released using smartthings_resource_deinitialize().
159 * @remarks Ths function returns #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED\n
160 * if the application has no app-defined privilege for 'http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource'.
162 * @param[out] st_h The SmartThings resource handle to be newly created on success
163 * @param[in] connection_status_cb The connection status callback to register
164 * @param[in] user_data The user data to be passed to the callback function
166 * @return @c 0 on success,
167 * otherwise a negative error value
168 * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
169 * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
170 * @retval #SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY Out of memory
171 * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
172 * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
173 * @retval #SMARTTHINGS_RESOURCE_ERROR_NOT_SUPPORTED Not supported
174 * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
176 * @see smartthings_resource_deinitialize()
178 int smartthings_resource_initialize(smartthings_resource_h *st_h,
179 smartthings_resource_connection_status_cb connection_status_cb,
183 * @brief Deinitializes a resource handle and disconnects from the agent.
186 * @param[in] st_h The SmartThings resource handle
188 * @return @c 0 on success,
189 * otherwise a negative error value
190 * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
191 * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
193 * @see smartthings_resource_initialize()
195 int smartthings_resource_deinitialize(smartthings_resource_h st_h);
198 * @brief Sets resource request callback.
200 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
201 * %http://tizen.org/privilege/appmanager.launch \n
202 * %http://tizen.org/privilege/datasharing
204 * @param[in] st_h The SmartThings resource handle
205 * @param[in] req_cb The request callback to register
206 * @param[in] user_data The user data to be passed to the callback function
208 * @return @c 0 on success,
209 * otherwise a negative error value
210 * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
211 * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
212 * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
213 * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
214 * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
216 * @see smartthings_resource_unset_request_cb()
218 int smartthings_resource_set_request_cb(smartthings_resource_h st_h,
219 smartthings_resource_request_cb req_cb,
223 * @brief Unsets resource request callback.
225 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
226 * %http://tizen.org/privilege/appmanager.launch \n
227 * %http://tizen.org/privilege/datasharing
229 * @param[in] st_h The SmartThings resource handle
231 * @return @c 0 on success,
232 * otherwise a negative error value
233 * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
234 * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
235 * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
236 * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
237 * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
239 * @see smartthings_resource_set_request_cb()
241 int smartthings_resource_unset_request_cb(smartthings_resource_h st_h);
244 * @brief Sends response for resource request message.
246 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
247 * %http://tizen.org/privilege/appmanager.launch \n
248 * %http://tizen.org/privilege/datasharing \n
249 * %http://tizen.org/privilege/internet
251 * @param[in] st_h The SmartThings resource handle
252 * @param[in] req_id The request ID of request message
253 * @param[in] uri The resource URI
254 * @param[in] payload The payload of response message
255 * @param[in] result The result of response
257 * @return @c 0 on success,
258 * otherwise a negative error value
259 * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
260 * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
261 * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
262 * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
263 * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
265 int smartthings_resource_send_response(smartthings_resource_h st_h, int req_id, const char *uri, smartthings_payload_h payload, bool result);
268 * @brief Notifies resource change.
270 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
271 * %http://tizen.org/privilege/appmanager.launch \n
272 * %http://tizen.org/privilege/datasharing \n
273 * %http://tizen.org/privilege/internet
275 * @param[in] st_h The SmartThings resource handle
276 * @param[in] uri The resource URI
277 * @param[in] payload The payload of response message
279 * @return @c 0 on success,
280 * otherwise a negative error value
281 * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
282 * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
283 * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
284 * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
285 * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
287 int smartthings_resource_notify(smartthings_resource_h st_h, const char *uri, smartthings_payload_h payload);
290 * @brief Gets resource URIs.
292 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
293 * %http://tizen.org/privilege/appmanager.launch \n
294 * %http://tizen.org/privilege/datasharing
296 * @remarks The @a uris should be released using free().
298 * @param[in] st_h The SmartThings resource handle
299 * @param[out] count The resource count
300 * @param[out] uris The resource URI list
302 * @return @c 0 on success,
303 * otherwise a negative error value
304 * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
305 * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
306 * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
307 * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
308 * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
310 int smartthings_resource_get_uris(smartthings_resource_h st_h, int *count, char ***uris);
313 * @brief Sets cloud registration callback.
315 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
316 * %http://tizen.org/privilege/appmanager.launch \n
317 * %http://tizen.org/privilege/datasharing
319 * @param[in] st_h The SmartThings resource handle
320 * @param[in] reg_cb The callback to register
321 * @param[in] user_data The user data to be passed to the callback function
323 * @return @c 0 on success,
324 * otherwise a negative error value
325 * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
326 * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
327 * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
328 * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
329 * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
331 * @see smartthings_resource_unset_cloud_registration_status_cb()
333 int smartthings_resource_set_cloud_registration_status_cb(smartthings_resource_h st_h,
334 smartthings_resource_cloud_registration_status_cb reg_cb,
338 * @brief Unsets cloud registration callback.
340 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
341 * %http://tizen.org/privilege/appmanager.launch \n
342 * %http://tizen.org/privilege/datasharing
344 * @param[in] st_h The SmartThings resource handle
346 * @return @c 0 on success,
347 * otherwise a negative error value
348 * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
349 * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
350 * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
351 * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
352 * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
354 * @see smartthings_resource_set_cloud_registration_status_cb()
356 int smartthings_resource_unset_cloud_registration_status_cb(smartthings_resource_h st_h);
367 #endif /* __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_RESOURCE_H__ */