1 /*****************************************************************
3 * Copyright (c) 2018 Samsung Electronics Co., Ltd. All Rights Reserved
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
17 ******************************************************************/
20 #ifndef __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_H__
21 #define __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_H__
32 * @addtogroup CAPI_SMARTTHINGS_THING_MASTER_MODULE
37 * @brief Definition for the max length of SSID for access point.
40 #define SMARTTHINGS_SSID_LEN_MAX 32
43 * @brief Definition for the max length of cloud information.
46 #define SMARTTHINGS_CLOUD_INFO_LEN_MAX 128
49 * @brief Enumeration for the SmartThings error.
53 SMARTTHINGS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
54 SMARTTHINGS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
55 SMARTTHINGS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
56 SMARTTHINGS_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
57 SMARTTHINGS_ERROR_NO_DATA = TIZEN_ERROR_NO_DATA, /**< No data */
58 SMARTTHINGS_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
59 SMARTTHINGS_ERROR_OPERATION_FAILED = TIZEN_ERROR_UNKNOWN - 1, /**< Operation failed */
60 SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE = TIZEN_ERROR_UNKNOWN -2 /**< Service unavailable */
61 } smartthings_error_e;
64 * @brief Enumeration for SmartThings status.
68 SMARTTHINGS_STATUS_NOT_READY = -1, /**< Service agent is not ready */
69 SMARTTHINGS_STATUS_INIT = 0, /**< Initial state of SmartThings Thing */
70 SMARTTHINGS_STATUS_ES_STARTED, /**< Easy-setup is started */
71 SMARTTHINGS_STATUS_ES_DONE, /**< Easy-setup is done */
72 SMARTTHINGS_STATUS_ES_FAILED_ON_OWNERSHIP_TRANSFER, /**< Easy-setup failed due to Ownership-Transfer failure */
73 SMARTTHINGS_STATUS_CONNECTING_TO_AP, /**< Connecting to target Wi-Fi access point */
74 SMARTTHINGS_STATUS_CONNECTED_TO_AP, /**< Connected to target Wi-Fi access point */
75 SMARTTHINGS_STATUS_CONNECTING_TO_AP_FAILED, /**< Failed to connect to target Wi-Fi access point */
76 SMARTTHINGS_STATUS_REGISTERING_TO_CLOUD, /**< Trying to sign up, sign in and publish resources to cloud */
77 SMARTTHINGS_STATUS_REGISTERED_TO_CLOUD, /**< Publish resources to cloud is complete. Now the thing is ready to be controlled via cloud */
78 SMARTTHINGS_STATUS_REGISTERING_FAILED_ON_SIGN_IN, /**< Failed to sign in to cloud */
79 SMARTTHINGS_STATUS_REGISTERING_FAILED_ON_PUB_RES /**< Failed to publish resources to cloud */
80 } smartthings_status_e;
83 * @brief Enumeration for RPC connection status.
87 SMARTTHINGS_CONNECTION_STATUS_CONNECTED = 0, /**< Connection is connected */
88 SMARTTHINGS_CONNECTION_STATUS_DISCONNECTED, /**< Connection is disconnected */
89 SMARTTHINGS_CONNECTION_STATUS_REJECTED, /**< Connection is rejected */
90 } smartthings_connection_status_e;
93 * @brief The Wi-Fi mode.
97 SMARTTHINGS_WIFI_MODE_11A = (1 << 0), /**< Wi-Fi 11A */
98 SMARTTHINGS_WIFI_MODE_11B = (1 << 1), /**< Wi-Fi 11B */
99 SMARTTHINGS_WIFI_MODE_11G = (1 << 2), /**< Wi-Fi 11G */
100 SMARTTHINGS_WIFI_MODE_11N = (1 << 3), /**< Wi-Fi 11N */
101 SMARTTHINGS_WIFI_MODE_11AC = (1 << 4) /**< Wi-Fi 11AC */
102 } smartthings_wifi_mode_e;
105 * @brief The Wi-Fi frequency band.
109 SMARTTHINGS_WIFI_FREQ_24G = (1 << 0), /**< Wi-Fi 2.4GHz */
110 SMARTTHINGS_WIFI_FREQ_5G = (1 << 1), /**< Wi-Fi 5GHz */
111 } smartthings_wifi_freq_e;
114 * @brief The Wi-Fi authentication type of access point.
118 SMARTTHINGS_WIFI_AUTHTYPE_NONE = 0, /**< No authentication */
119 SMARTTHINGS_WIFI_AUTHTYPE_WEP, /**< WEP */
120 SMARTTHINGS_WIFI_AUTHTYPE_WPA_PSK, /**< WPA-PSK */
121 SMARTTHINGS_WIFI_AUTHTYPE_WPA2_PSK /**< WPA2-PSK */
122 } smartthings_wifi_authtype_e;
125 * @brief The Wi-Fi encryption type of access point.
129 SMARTTHINGS_WIFI_ENCTYPE_NONE = 0, /**< No encryption */
130 SMARTTHINGS_WIFI_ENCTYPE_WEP_64, /**< WEP 64 */
131 SMARTTHINGS_WIFI_ENCTYPE_WEP_128, /**< WEP 128 */
132 SMARTTHINGS_WIFI_ENCTYPE_TKIP, /**< TKIP */
133 SMARTTHINGS_WIFI_ENCTYPE_AES, /**< AES */
134 SMARTTHINGS_WIFI_ENCTYPE_TKIP_AES /**< TKIP/AES */
135 } smartthings_wifi_enctype_e;
138 * @brief The SmartThings handle.
141 typedef struct smartthings_s *smartthings_h;
144 * @brief The access point information handle.
147 typedef struct smartthings_ap_info_s *smartthings_ap_info_h;
150 * @brief The device provisioning information handle.
153 typedef struct smartthings_device_prov_info_s *smartthings_device_prov_info_h;
156 * @brief The cloud information handle for cloud sign-up.
159 typedef struct smartthings_cloud_info_s *smartthings_cloud_info_h;
162 * @brief The access point list handle.
165 typedef struct smartthings_ap_list_s *smartthings_ap_list_h;
168 * @brief Callback for status of connection to SmartThings Thing agent.
171 * @remarks The @a handle should not be released.
172 * @remarks The @a handle is the same object for which the callback was set/added.
173 * @remarks The @a handle will be released when smartthings_deinitialize() is called.
174 * @remarks When callback is called, user can see connection status as #smartthings_connection_status_e enumeration value.
176 * @param[in] result The result of connection operation
177 * @param[in] handle The SmartThings handle
178 * @param[in] status The status of connection
179 * @param[in] user_data The user data passed from the callback registration function
181 * @see smartthings_initialize()
183 typedef void (*smartthings_connection_status_cb)(smartthings_h handle, smartthings_connection_status_e status, void *user_data);
186 * @brief Callback for SmartThings Thing status.
189 * @remarks The @a handle should not be released.
190 * @remarks The @a handle is the same object for which the callback was set/added.
191 * @remarks The @a handle will be released when smartthings_deinitialize() is called.
192 * @remarks When callback is called, user can see SmartThings status as #smartthings_status_e enumeration value.
194 * @param[in] handle The SmartThings handle
195 * @param[in] status The status of SmartThings
196 * @param[in] user_data The user data passed from the callback registration function
198 * @see smartthings_set_status_changed_cb()
199 * @see smartthings_unset_status_changed_cb()
201 typedef void (*smartthings_status_changed_cb)(smartthings_h handle, smartthings_status_e status, void *user_data);
204 * @brief Callback for getting user's input regarding mutual verification.
207 * @remarks The @a handle should not be released.
208 * @remarks The @a handle is the same object for which the callback was set/added.
209 * @remarks The @a handle will be released when smartthings_deinitialize() is called.
210 * @remarks When callback is called, user can send a confirmation for mutual verification as true or false.
212 * @param[in] handle The SmartThings handle
213 * @param[in] user_data The user data passed from the callback registration function
215 * @see smartthings_set_user_confirm_cb()
216 * @see smartthings_unset_user_confirm_cb()
218 typedef void (*smartthings_user_confirm_cb)(smartthings_h handle, void *user_data);
221 * @brief Callback for getting user's opinion regarding device reset.
224 * @remarks The @a handle should not be released.
225 * @remarks The @a handle is the same object for which the callback was set/added.
226 * @remarks The @a handle will be released when smartthings_deinitialize() is called.
227 * @remarks When callback is called, user can sends a confirmation for reset as true or false.
229 * @param[in] handle The SmartThings handle
230 * @param[in] user_data The user data passed from the callback registration function
232 * @see smartthings_set_reset_confirm_cb()
233 * @see smartthings_unset_reset_confirm_cb()
235 typedef void (*smartthings_reset_confirm_cb)(smartthings_h handle, void *user_data);
238 * @brief Callback for result of reset operation.
241 * @remarks The @a handle should not be released.
242 * @remarks The @a handle is the same object for which the callback was set/added.
243 * @remarks The @a handle will be released when smartthings_deinitialize() is called.
244 * @remarks When callback is called, user can check reset operation succeeds or fails.
246 * @param[in] handle The SmartThings handle
247 * @param[in] result The result of reset
248 * @param[in] user_data The user data passed from the callback registration function
250 * @see smartthings_set_reset_result_cb()
251 * @see smartthings_unset_reset_result_cb()
253 typedef void (*smartthings_reset_result_cb)(smartthings_h handle, bool result, void *user_data);
256 * @brief Callback for carrying the randomly generated PIN information.
259 * @remarks The @a handle should not be released.
260 * @remarks The @a handle is the same object for which the callback was set/added.
261 * @remarks The @a handle will be released when smartthings_deinitialize() is called.
262 * @remarks The @a pin can be used only in the callback. To use outside, make a copy.
263 * @remarks When callback is called, user can see PIN value and length.
265 * @param[in] handle The SmartThings handle
266 * @param[in] pin The PIN data in string format
267 * @param[in] size The PIN length of @a pin
268 * @param[in] user_data The user data passed from the callback registration function
270 * @see smartthings_set_pin_cb()
271 * @see smartthings_unset_pin_cb()
273 typedef void (*smartthings_pin_generated_cb)(smartthings_h handle, const char* pin, size_t size, void *user_data);
276 * @brief Callback for informing the application to close the PIN display.
279 * @remarks The @a handle should not be released.
280 * @remarks The @a handle is the same object for which the callback was set/added.
281 * @remarks The @a handle will be released when smartthings_deinitialize() is called.
282 * @remarks When callback is called, user can know PIN based ownership transfer is finished.
284 * @param[in] handle The SmartThings handle
285 * @param[in] user_data The user data passed from the callback registration function
287 * @see smartthings_set_pin_cb()
288 * @see smartthings_unset_pin_cb()
290 typedef void (*smartthings_pin_display_close_cb)(smartthings_h handle, void *user_data);
293 * @brief Callback for informing Wi-Fi AP information to connect.
296 * @remarks The @a handle should not be released.
297 * @remarks The @a handle is the same object for which the callback was set/added.
298 * @remarks The @a handle will be released when smartthings_deinitialize() is called.
299 * @remarks The @a ap_info_h should not be released.
300 * @remarks The @a ap_info_h will be released when smartthings_unset_wifi_ap_provisioning_cb() is called.
301 * @remarks When callback is called, user can get Wi-Fi provisioning information.
303 * @param[in] handle The SmartThings handle
304 * @param[in] ap_info_h The AP information handle
305 * @param[in] user_data The user data passed from the callback registration function
307 * @see smartthings_set_wifi_ap_provisioning_cb()
308 * @see smartthings_unset_wifi_ap_provisioning_cb()
310 typedef void (*smartthings_wifi_ap_provisioning_cb)(smartthings_h handle, smartthings_ap_info_h ap_info_h, void *user_data);
313 * @brief Callback for informing device provisioning information.
316 * @remarks The @a handle should not be released.
317 * @remarks The @a handle is the same object for which the callback was set/added.
318 * @remarks The @a handle will be released when smartthings_deinitialize() is called.
319 * @remarks The @a dev_prov_h should not be released.
320 * @remarks The @a dev_prov_h will be released when smartthings_unset_device_provisioning_cb() is called.
321 * @remarks When callback is called, user can get device provisioning information.
323 * @param[in] handle The SmartThings handle
324 * @param[in] dev_prov_h The device provisioning information handle
325 * @param[in] user_data The user data passed from the callback registration function
327 * @see smartthings_set_device_provisioning_cb()
328 * @see smartthings_unset_device_provisioning_cb()
330 typedef void (*smartthings_device_provisioning_cb)(smartthings_h handle, smartthings_device_prov_info_h dev_prov_h, void *user_data);
333 * @brief Callback for informing the scan AP list request.
336 * @remarks The @a handle should not be released.
337 * @remarks The @a handle is the same object for which the callback was set/added.
338 * @remarks The @a handle will be released when smartthings_deinitialize() is called.
339 * @remarks When callback is called, user scans access points, sets AP list and sends it to agent.
341 * @param[in] handle The SmartThings handle
342 * @param[in] req_id The request ID
343 * @param[in] user_data The user data passed from the callback registration function
345 * @see smartthings_set_scan_ap_cb()
346 * @see smartthings_unset_scan_ap_cb()
348 typedef void (*smartthings_scan_ap_cb)(smartthings_h handle, int req_id, void *user_data);
351 * @brief Callback for informing the stop soft AP request.
354 * @remarks The @a handle should not be released.
355 * @remarks The @a handle is the same object for which the callback was set/added.
356 * @remarks The @a handle will be released when smartthings_deinitialize() is called.
357 * @remarks When callback is called, user stops soft AP.
359 * @param[in] handle The SmartThings handle
360 * @param[in] user_data The user data passed from the callback registration function
362 * @see smartthings_set_stop_soft_ap_cb()
363 * @see smartthings_unset_stop_soft_ap_cb()
365 typedef void (*smartthings_stop_soft_ap_cb)(smartthings_h handle, void *user_data);
368 * @brief Creates a handle and connects to agent.
370 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
371 * %http://tizen.org/privilege/appmanager.launch \n
372 * %http://tizen.org/privilege/datasharing
374 * @remarks The @a handle must be released using smartthings_deinitialize().
375 * @remarks Ths function returns #SMARTTHINGS_ERROR_PERMISSION_DENIED\n
376 * if the application has no app-defined privilege for 'http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master'.
378 * @param[out] handle The SmartThings handle to be newly created on success
379 * @param[in] connection_status_cb The RPC connection status callback to register
380 * @param[in] user_data The user data to be passed to the callback function
382 * @return @c 0 on success,
383 * otherwise a negative error value
384 * @retval #SMARTTHINGS_ERROR_NONE Successful
385 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
386 * @retval #SMARTTHINGS_ERROR_OUT_OF_MEMORY Out of memory
387 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
388 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
389 * @retval #SMARTTHINGS_ERROR_NOT_SUPPORTED Not supported
390 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
392 * @see smartthings_deinitialize()
394 int smartthings_initialize(smartthings_h *handle,
395 smartthings_connection_status_cb connection_status_cb,
399 * @brief Deinitializes a handle and disconnects from the agent.
402 * @param[in] handle The SmartThings handle
404 * @return @c 0 on success,
405 * otherwise a negative error value
406 * @retval #SMARTTHINGS_ERROR_NONE Successful
407 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
408 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
410 * @see smartthings_initialize()
412 int smartthings_deinitialize(smartthings_h handle);
415 * @brief Starts SmartThings Thing operation.
417 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
418 * %http://tizen.org/privilege/appmanager.launch \n
419 * %http://tizen.org/privilege/datasharing
421 * @param[in] handle The SmartThings handle
423 * @return @c 0 on success,
424 * otherwise a negative error value
425 * @retval #SMARTTHINGS_ERROR_NONE Successful
426 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
427 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
428 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
429 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
431 * @see smartthings_stop()
433 int smartthings_start(smartthings_h handle);
436 * @brief Stops SmartThings Thing operation.
438 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
439 * %http://tizen.org/privilege/appmanager.launch \n
440 * %http://tizen.org/privilege/datasharing
442 * @param[in] handle The SmartThings handle
444 * @return @c 0 on success,
445 * otherwise a negative error value
446 * @retval #SMARTTHINGS_ERROR_NONE Successful
447 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
448 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
449 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
450 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
452 * @see smartthings_start()
454 int smartthings_stop(smartthings_h handle);
457 * @brief Sets thing status changed callback.
459 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
460 * %http://tizen.org/privilege/appmanager.launch \n
461 * %http://tizen.org/privilege/datasharing
463 * @remarks Only one callback function can be set with this function.
464 * @remarks If multiple callbacks are set, the last one is registered only.
465 * @remarks Callback is called when SmartThings status is changed.
466 * @remarks When callback is called, user can get SmartThings status as #smartthings_status_e enumeration value.
468 * @param[in] handle The SmartThings handle
469 * @param[in] status_cb The status changed callback to register
470 * @param[in] user_data The user data to be passed to the callback function
472 * @return @c 0 on success,
473 * otherwise a negative error value
474 * @retval #SMARTTHINGS_ERROR_NONE Successful
475 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
476 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
477 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
478 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
480 * @see smartthings_unset_status_changed_cb()
482 int smartthings_set_status_changed_cb(smartthings_h handle,
483 smartthings_status_changed_cb status_cb,
487 * @brief Unsets thing status changed callback.
489 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
490 * %http://tizen.org/privilege/appmanager.launch \n
491 * %http://tizen.org/privilege/datasharing
493 * @param[in] handle The SmartThings handle
495 * @return @c 0 on success,
496 * otherwise a negative error value
497 * @retval #SMARTTHINGS_ERROR_NONE Successful
498 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
499 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
500 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
501 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
503 * @see smartthings_set_status_changed_cb()
505 int smartthings_unset_status_changed_cb(smartthings_h handle);
508 * @brief Sets test certificate files.
510 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
511 * %http://tizen.org/privilege/appmanager.launch \n
512 * %http://tizen.org/privilege/datasharing
514 * @remarks These files should be placed in 'res' directory of application.
515 * @remarks This function is needed only for using test certificate.
516 * @remarks This function can be used before smartthings_start()
518 * @param[in] handle The SmartThings handle
519 * @param[in] certificate The certificate file
520 * @param[in] private_key The private key file
522 * @return @c 0 on success,
523 * otherwise a negative error value
524 * @retval #SMARTTHINGS_ERROR_NONE Successful
525 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
526 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
527 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
528 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
530 int smartthings_set_certificate_file(smartthings_h handle, const char *certificate, const char *private_key);
533 * @brief Sets device property for Easy-setup.
536 * @remarks This function can be used before smartthings_start()
538 * @param[in] handle The SmartThings handle
539 * @param[in] dev_name The device name
540 * @param[in] wifi_mode The supported Wi-Fi mode (bit masked value for #smartthings_wifi_mode_e)
541 * @param[in] wifi_freq The supported Wi-Fi frequency (bit masked value for #smartthings_wifi_freq_e)
543 * @return @c 0 on success,
544 * otherwise a negative error value
545 * @retval #SMARTTHINGS_ERROR_NONE Successful
546 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
548 int smartthings_set_device_property(smartthings_h handle, const char* dev_name, int wifi_mode, int wifi_freq);
551 * @brief Gets a device ID.
553 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
554 * %http://tizen.org/privilege/appmanager.launch \n
555 * %http://tizen.org/privilege/datasharing
557 * @remarks The @a device_id should be released using free().
559 * @param[in] handle The SmartThings handle
560 * @param[out] device_id The device ID
562 * @return @c 0 on success,
563 * otherwise a negative error value
564 * @retval #SMARTTHINGS_ERROR_NONE Successful
565 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
566 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
567 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
568 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
570 int smartthings_get_device_id(smartthings_h handle, char **device_id);
573 * @brief Gets a Easy-setup status.
575 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
576 * %http://tizen.org/privilege/appmanager.launch \n
577 * %http://tizen.org/privilege/datasharing
579 * @param[in] handle The SmartThings handle
580 * @param[out] is_completed The status of Easy-setup whether it is completed or not
582 * @return @c 0 on success,
583 * otherwise a negative error value
584 * @retval #SMARTTHINGS_ERROR_NONE Successful
585 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
586 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
587 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
588 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
590 int smartthings_get_easysetup_status(smartthings_h handle, bool *is_completed);
593 * @brief Starts Easy-setup mode.
595 * @details This function requests for turning on soft AP to SmartThings Thing agent.
597 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
598 * %http://tizen.org/privilege/appmanager.launch \n
599 * %http://tizen.org/privilege/datasharing \n
600 * %http://tizen.org/privilege/softap
602 * @param[in] handle The SmartThings handle
604 * @return @c 0 on success,
605 * otherwise a negative error value
606 * @retval #SMARTTHINGS_ERROR_NONE Successful
607 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
608 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
609 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
610 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
612 * @see smartthings_stop_easysetup()
614 int smartthings_start_easysetup(smartthings_h handle);
617 * @brief Stops Easy-setup mode.
619 * @details This function requests for turning off soft AP to SmartThings Thing agent.
621 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
622 * %http://tizen.org/privilege/appmanager.launch \n
623 * %http://tizen.org/privilege/datasharing \n
624 * %http://tizen.org/privilege/softap
626 * @param[in] handle The SmartThings handle
628 * @return @c 0 on success,
629 * otherwise a negative error value
630 * @retval #SMARTTHINGS_ERROR_NONE Successful
631 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
632 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
633 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
634 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
636 * @see smartthings_start_easysetup()
638 int smartthings_stop_easysetup(smartthings_h handle);
641 * @brief Sets callback for getting user confirmation for mutual verification based just work ownership transfer.
643 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
644 * %http://tizen.org/privilege/appmanager.launch \n
645 * %http://tizen.org/privilege/datasharing
647 * @remarks Only one callback function can be set with this function.
648 * @remarks If multiple callbacks are set, the last one is registered only.
649 * @remarks Callback is called when it needs user's confirm for mutual verification based just work ownership transfer.
650 * @remarks When callback is called, user can send a confirmation for mutual verification based just work ownership transfer as true or false.
652 * @param[in] handle The SmartThings handle
653 * @param[in] confirm_cb The user confirm callback to register
654 * @param[in] user_data The user data to be passed to the callback function
656 * @return @c 0 on success,
657 * otherwise a negative error value
658 * @retval #SMARTTHINGS_ERROR_NONE Successful
659 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
660 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
661 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
662 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
664 * @see smartthings_unset_user_confirm_cb()
666 int smartthings_set_user_confirm_cb(smartthings_h handle,
667 smartthings_user_confirm_cb confirm_cb,
671 * @brief Unsets user confirmation callback.
673 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
674 * %http://tizen.org/privilege/appmanager.launch \n
675 * %http://tizen.org/privilege/datasharing
677 * @param[in] handle The SmartThings handle
679 * @return @c 0 on success,
680 * otherwise a negative error value
681 * @retval #SMARTTHINGS_ERROR_NONE Successful
682 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
683 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
684 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
685 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
687 * @see smartthings_set_user_confirm_cb()
689 int smartthings_unset_user_confirm_cb(smartthings_h handle);
692 * @brief Sets reset confirmation callback.
694 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
695 * %http://tizen.org/privilege/appmanager.launch \n
696 * %http://tizen.org/privilege/datasharing
698 * @remarks Only one callback function can be set with this function.
699 * @remarks If multiple callbacks are set, the last one is registered only.
700 * @remarks Callback is called when it needs user's confirm for reset.
701 * @remarks When callback is called, user can send a confirmation for reset as true or false.
703 * @param[in] handle The SmartThings handle
704 * @param[in] confirm_cb The reset confirm callback to register
705 * @param[in] user_data The user data to be passed to the callback function
707 * @return @c 0 on success,
708 * otherwise a negative error value
709 * @retval #SMARTTHINGS_ERROR_NONE Successful
710 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
711 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
712 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
713 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
715 * @see smartthings_unset_reset_confirm_cb()
717 int smartthings_set_reset_confirm_cb(smartthings_h handle,
718 smartthings_reset_confirm_cb confirm_cb,
722 * @brief Unsets reset confirmation callback.
724 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
725 * %http://tizen.org/privilege/appmanager.launch \n
726 * %http://tizen.org/privilege/datasharing
728 * @param[in] handle The SmartThings handle
730 * @return @c 0 on success,
731 * otherwise a negative error value
732 * @retval #SMARTTHINGS_ERROR_NONE Successful
733 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
734 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
735 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
736 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
738 * @see smartthings_set_reset_confirm_cb()
740 int smartthings_unset_reset_confirm_cb(smartthings_h handle);
743 * @brief Sets reset result callback.
745 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
746 * %http://tizen.org/privilege/appmanager.launch \n
747 * %http://tizen.org/privilege/datasharing
749 * @remarks Only one callback function can be set with this function.
750 * @remarks If multiple callbacks are set, the last one is registered only.
751 * @remarks Callback is called when reset operation returns its result.
752 * @remarks When callback is called, user can check reset operation succeeds or fails.
754 * @param[in] handle The SmartThings handle
755 * @param[in] reset_result_cb The reset result callback to register
756 * @param[in] user_data The user data to be passed to the callback function
758 * @return @c 0 on success,
759 * otherwise a negative error value
760 * @retval #SMARTTHINGS_ERROR_NONE Successful
761 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
762 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
763 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
764 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
766 * @see smartthings_unset_reset_result_cb()
768 int smartthings_set_reset_result_cb(smartthings_h handle,
769 smartthings_reset_result_cb reset_result_cb,
773 * @brief Unsets reset result callback.
775 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
776 * %http://tizen.org/privilege/appmanager.launch \n
777 * %http://tizen.org/privilege/datasharing
779 * @param[in] handle The SmartThings handle
781 * @return @c 0 on success,
782 * otherwise a negative error value
783 * @retval #SMARTTHINGS_ERROR_NONE Successful
784 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
785 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
786 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
787 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
789 * @see smartthings_set_reset_result_cb()
791 int smartthings_unset_reset_result_cb(smartthings_h handle);
795 * @brief Sets callback for getting randomly generated PIN for the PIN-based ownership transfer request.
797 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
798 * %http://tizen.org/privilege/appmanager.launch \n
799 * %http://tizen.org/privilege/datasharing
801 * @remarks Only one callback function can be set with this function.
802 * @remarks If multiple callbacks are set, the last one is registered only.
803 * @remarks @a generated_cb callback is called when PIN is generated.
804 * @remarks @a close_cb callback is called when PIN based ownership transfer is finished.
805 * @remarks When @a generated_cb callback is called, user can see PIN value and length.
806 * @remarks When @a close_cb callback is called, user can know PIN based ownership transfer is finished.
808 * @param[in] handle The SmartThings handle
809 * @param[in] generated_cb The PIN generation callback to register
810 * @param[in] close_cb The PIN display close callback to register
811 * @param[in] user_data The user data to be passed to the callback function
813 * @return @c 0 on success,
814 * otherwise a negative error value
815 * @retval #SMARTTHINGS_ERROR_NONE Successful
816 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
817 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
818 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
819 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
821 * @see smartthings_unset_pin_cb()
823 int smartthings_set_pin_cb(smartthings_h handle,
824 smartthings_pin_generated_cb generated_cb,
825 smartthings_pin_display_close_cb close_cb,
829 * @brief Unsets PIN callback.
831 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
832 * %http://tizen.org/privilege/appmanager.launch \n
833 * %http://tizen.org/privilege/datasharing
835 * @param[in] handle The SmartThings handle
837 * @return @c 0 on success,
838 * otherwise a negative error value
839 * @retval #SMARTTHINGS_ERROR_NONE Successful
840 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
841 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
842 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
843 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
845 * @see smartthings_set_pin_cb()
847 int smartthings_unset_pin_cb(smartthings_h handle);
850 * @brief Sets callback for getting Wi-Fi AP information during Easy-setup.
852 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
853 * %http://tizen.org/privilege/appmanager.launch \n
854 * %http://tizen.org/privilege/datasharing
856 * @remarks Only one callback function can be set with this function.
857 * @remarks If multiple callbacks are set, the last one is registered only.
858 * @remarks Callback is called when Wi-Fi provisioning event occurs.
859 * @remarks When callback is called, user can get Wi-Fi provisioning information.
861 * @param[in] handle The SmartThings handle
862 * @param[in] wifi_ap_cb The Wi-Fi AP callback to register
863 * @param[in] user_data The user data to be passed to the callback function
865 * @return @c 0 on success,
866 * otherwise a negative error value
867 * @retval #SMARTTHINGS_ERROR_NONE Successful
868 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
869 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
870 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
871 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
873 * @see smartthings_unset_wifi_ap_provisioning_cb()
875 int smartthings_set_wifi_ap_provisioning_cb(smartthings_h handle,
876 smartthings_wifi_ap_provisioning_cb wifi_ap_cb,
880 * @brief Unsets callback for getting Wi-Fi AP information during Easy-setup.
882 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
883 * %http://tizen.org/privilege/appmanager.launch \n
884 * %http://tizen.org/privilege/datasharing
886 * @param[in] handle The SmartThings handle
888 * @return @c 0 on success,
889 * otherwise a negative error value
890 * @retval #SMARTTHINGS_ERROR_NONE Successful
891 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
892 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
893 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
894 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
896 * @see smartthings_set_wifi_ap_provisioning_cb()
898 int smartthings_unset_wifi_ap_provisioning_cb(smartthings_h handle);
901 * @brief Sets callback for getting device provisioning information.
903 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
904 * %http://tizen.org/privilege/appmanager.launch \n
905 * %http://tizen.org/privilege/datasharing
907 * @remarks Only one callback function can be set with this function.
908 * @remarks If multiple callbacks are set, the last one is registered only.
909 * @remarks Callback is called when device provisioning event occurs.
910 * @remarks When callback is called, user can get device provisioning information.
912 * @param[in] handle The SmartThings handle
913 * @param[in] dev_prov_cb The device provisioning callback to register
914 * @param[in] user_data The user data to be passed to the callback function
916 * @return @c 0 on success,
917 * otherwise a negative error value
918 * @retval #SMARTTHINGS_ERROR_NONE Successful
919 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
920 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
921 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
922 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
924 * @see smartthings_unset_device_provisioning_cb()
926 int smartthings_set_device_provisioning_cb(smartthings_h handle,
927 smartthings_device_provisioning_cb dev_prov_cb,
931 * @brief Unsets callback for getting device provisioning information.
933 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
934 * %http://tizen.org/privilege/appmanager.launch \n
935 * %http://tizen.org/privilege/datasharing
937 * @param[in] handle The SmartThings handle
939 * @return @c 0 on success,
940 * otherwise a negative error value
941 * @retval #SMARTTHINGS_ERROR_NONE Successful
942 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
943 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
944 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
945 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
947 * @see smartthings_set_device_provisioning_cb()
949 int smartthings_unset_device_provisioning_cb(smartthings_h handle);
952 * @brief Sets callback for informing the scan AP list request.
954 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
955 * %http://tizen.org/privilege/appmanager.launch \n
956 * %http://tizen.org/privilege/datasharing
958 * @remarks Only one callback function can be set with this function.
959 * @remarks If multiple callbacks are set, the last one is registered only.
960 * @remarks Callback is called when GET request for access point list.
961 * @remarks When callback is called, user scans access points, sets AP list and sends it to agent.
963 * @param[in] handle The SmartThings handle
964 * @param[in] scan_ap_cb The callback to register
965 * @param[in] user_data The user data to be passed to the callback function
967 * @return @c 0 on success,
968 * otherwise a negative error value
969 * @retval #SMARTTHINGS_ERROR_NONE Successful
970 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
971 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
972 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
973 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
975 * @see smartthings_unset_scan_ap_cb()
976 * @see smartthings_send_ap_list()
978 int smartthings_set_scan_ap_cb(smartthings_h handle,
979 smartthings_scan_ap_cb scan_ap_cb,
983 * @brief Unsets callback for informing the scan AP list request.
985 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
986 * %http://tizen.org/privilege/appmanager.launch \n
987 * %http://tizen.org/privilege/datasharing
989 * @param[in] handle The SmartThings handle
991 * @return @c 0 on success,
992 * otherwise a negative error value
993 * @retval #SMARTTHINGS_ERROR_NONE Successful
994 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
995 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
996 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
997 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
999 * @see smartthings_set_scan_ap_cb()
1001 int smartthings_unset_scan_ap_cb(smartthings_h handle);
1004 * @brief Sets callback for informing the stop soft AP request.
1006 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
1007 * %http://tizen.org/privilege/appmanager.launch \n
1008 * %http://tizen.org/privilege/datasharing
1010 * @remarks Only one callback function can be set with this function.
1011 * @remarks If multiple callbacks are set, the last one is registered only.
1012 * @remarks Callback is called when POST request for stopping soft AP.
1013 * @remarks When callback is called, user stops soft AP.
1015 * @param[in] handle The SmartThings handle
1016 * @param[in] stop_soft_ap_cb The callback to register
1017 * @param[in] user_data The user data to be passed to the callback function
1019 * @return @c 0 on success,
1020 * otherwise a negative error value
1021 * @retval #SMARTTHINGS_ERROR_NONE Successful
1022 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1023 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
1024 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1025 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
1027 * @see smartthings_unset_stop_soft_ap_cb()
1029 int smartthings_set_stop_soft_ap_cb(smartthings_h handle,
1030 smartthings_stop_soft_ap_cb stop_soft_ap_cb,
1034 * @brief Unsets callback for informing the stop soft AP request.
1036 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
1037 * %http://tizen.org/privilege/appmanager.launch \n
1038 * %http://tizen.org/privilege/datasharing
1040 * @param[in] handle The SmartThings handle
1042 * @return @c 0 on success,
1043 * otherwise a negative error value
1044 * @retval #SMARTTHINGS_ERROR_NONE Successful
1045 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1046 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
1047 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1048 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
1050 * @see smartthings_set_stop_soft_ap_cb()
1052 int smartthings_unset_stop_soft_ap_cb(smartthings_h handle);
1055 * @brief Sends a user confirmation for MUTUAL VERIFICATION BASED JUST WORK Ownership transfer.
1057 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
1058 * %http://tizen.org/privilege/appmanager.launch \n
1059 * %http://tizen.org/privilege/datasharing \n
1060 * %http://tizen.org/privilege/internet
1062 * @param[in] handle The SmartThings handle
1063 * @param[in] confirm The user confirmation for OTM(ownership transfer method)
1065 * @return @c 0 on success,
1066 * otherwise a negative error value
1067 * @retval #SMARTTHINGS_ERROR_NONE Successful
1068 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1069 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
1070 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1071 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
1073 * @see smartthings_set_user_confirm_cb()
1074 * @see smartthings_unset_user_confirm_cb()
1076 int smartthings_send_user_confirm(smartthings_h handle, bool confirm);
1080 * @brief Sends a reset confirmation.
1082 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
1083 * %http://tizen.org/privilege/appmanager.launch \n
1084 * %http://tizen.org/privilege/datasharing \n
1085 * %http://tizen.org/privilege/internet
1087 * @param[in] handle The SmartThings handle
1088 * @param[in] confirm The reset confirmation
1090 * @return @c 0 on success,
1091 * otherwise a negative error value
1092 * @retval #SMARTTHINGS_ERROR_NONE Successful
1093 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1094 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
1095 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1096 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
1098 * @see smartthings_set_reset_confirm_cb()
1099 * @see smartthings_unset_reset_confirm_cb()
1101 int smartthings_send_reset_confirm(smartthings_h handle, bool confirm);
1104 * @brief Sends a reset command for resetting the device's Cloud signup and Easy-setup.
1106 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
1107 * %http://tizen.org/privilege/appmanager.launch \n
1108 * %http://tizen.org/privilege/datasharing \n
1109 * %http://tizen.org/privilege/internet
1111 * @param[in] handle The SmartThings handle
1113 * @return @c 0 on success,
1114 * otherwise a negative error value
1115 * @retval #SMARTTHINGS_ERROR_NONE Successful
1116 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1117 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
1118 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1119 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
1121 * @see smartthings_set_reset_result_cb()
1122 * @see smartthings_unset_reset_result_cb()
1124 int smartthings_reset(smartthings_h handle);
1127 * @brief Gets SSID of access point.
1130 * @remarks The @a ssid should be released using free().
1132 * @param[in] ap_info_h The SmartThings AP information handle
1133 * @param[out] ssid The SSID name
1135 * @return @c 0 on success,
1136 * otherwise a negative error value
1137 * @retval #SMARTTHINGS_ERROR_NONE Successful
1138 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1139 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1141 * @see smartthings_set_wifi_ap_provisioning_cb()
1142 * @see smartthings_unset_wifi_ap_provisioning_cb()
1144 int smartthings_apinfo_get_ssid(smartthings_ap_info_h ap_info_h, char **ssid);
1147 * @brief Gets password of access point.
1150 * @remarks The @a pwd should be released using free().
1152 * @param[in] ap_info_h The SmartThings AP information handle
1153 * @param[out] pwd The password
1155 * @return @c 0 on success,
1156 * otherwise a negative error value
1157 * @retval #SMARTTHINGS_ERROR_NONE Successful
1158 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1159 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1161 * @see smartthings_set_wifi_ap_provisioning_cb()
1162 * @see smartthings_unset_wifi_ap_provisioning_cb()
1164 int smartthings_apinfo_get_password(smartthings_ap_info_h ap_info_h, char **pwd);
1167 * @brief Gets authentification type of access point.
1170 * @param[in] ap_info_h The SmartThings AP information handle
1171 * @param[out] authtype The authentification type
1173 * @return @c 0 on success,
1174 * otherwise a negative error value
1175 * @retval #SMARTTHINGS_ERROR_NONE Successful
1176 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1177 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1179 * @see smartthings_set_wifi_ap_provisioning_cb()
1180 * @see smartthings_unset_wifi_ap_provisioning_cb()
1182 int smartthings_apinfo_get_authtype(smartthings_ap_info_h ap_info_h, smartthings_wifi_authtype_e *authtype);
1185 * @brief Gets encryption type of access point.
1188 * @param[in] ap_info_h The SmartThings AP information handle
1189 * @param[out] enctype The encryption type
1191 * @return @c 0 on success,
1192 * otherwise a negative error value
1193 * @retval #SMARTTHINGS_ERROR_NONE Successful
1194 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1195 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1197 * @see smartthings_set_wifi_ap_provisioning_cb()
1198 * @see smartthings_unset_wifi_ap_provisioning_cb()
1200 int smartthings_apinfo_get_enctype(smartthings_ap_info_h ap_info_h, smartthings_wifi_enctype_e *enctype);
1203 * @brief Gets channel information of access point.
1206 * @param[in] ap_info_h The SmartThings AP information handle
1207 * @param[out] channel The frequency channel
1209 * @return @c 0 on success,
1210 * otherwise a negative error value
1211 * @retval #SMARTTHINGS_ERROR_NONE Successful
1212 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1213 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1215 * @see smartthings_set_wifi_ap_provisioning_cb()
1216 * @see smartthings_unset_wifi_ap_provisioning_cb()
1218 int smartthings_apinfo_get_channel(smartthings_ap_info_h ap_info_h, int *channel);
1221 * @brief Gets language of device provisioing information.
1224 * @remarks The @a language should be released using free().
1226 * @param[in] dev_prov_h The SmartThings device provisioning information handle
1227 * @param[out] language The IETF language tag using ISO 639X
1229 * @return @c 0 on success,
1230 * otherwise a negative error value
1231 * @retval #SMARTTHINGS_ERROR_NONE Successful
1232 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1233 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1235 * @see smartthings_set_device_provisioning_cb()
1236 * @see smartthings_unset_device_provisioning_cb()
1238 int smartthings_devinfo_get_language(smartthings_device_prov_info_h dev_prov_h, char **language);
1241 * @brief Gets country of device provisioing information.
1244 * @remarks The @a country should be released using free().
1246 * @param[in] dev_prov_h The SmartThings device provisioning information handle
1247 * @param[out] country The ISO Country Code (ISO 3166-1 Alpha-2)
1249 * @return @c 0 on success,
1250 * otherwise a negative error value
1251 * @retval #SMARTTHINGS_ERROR_NONE Successful
1252 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1253 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1255 * @see smartthings_set_device_provisioning_cb()
1256 * @see smartthings_unset_device_provisioning_cb()
1258 int smartthings_devinfo_get_country(smartthings_device_prov_info_h dev_prov_h, char **country);
1261 * @brief Gets datetime of device provisioing information.
1264 * @remarks The @a datetime should be released using free().
1266 * @param[in] dev_prov_h The SmartThings device provisioning information handle
1267 * @param[out] datetime The date and time
1269 * @return @c 0 on success,
1270 * otherwise a negative error value
1271 * @retval #SMARTTHINGS_ERROR_NONE Successful
1272 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1273 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1275 * @see smartthings_set_device_provisioning_cb()
1276 * @see smartthings_unset_device_provisioning_cb()
1278 int smartthings_devinfo_get_datetime(smartthings_device_prov_info_h dev_prov_h, char **datetime);
1281 * @brief Creates a SmartThings AP list handle.
1284 * @remarks The @a ap_list_h must be released using smartthings_aplist_destroy().
1286 * @param[out] ap_list_h The SmartThings AP list handle to be newly created on success
1287 * @param[in] count The count of AP
1289 * @return @c 0 on success,
1290 * otherwise a negative error value
1291 * @retval #SMARTTHINGS_ERROR_NONE Successful
1292 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1293 * @retval #SMARTTHINGS_ERROR_OUT_OF_MEMORY Out of memory
1295 * @see smartthings_aplist_destroy()
1297 int smartthings_aplist_create(smartthings_ap_list_h *ap_list_h, unsigned int count);
1300 * @brief Destroys a SmartThings AP list handle.
1303 * @param[in] ap_list_h The SmartThings AP list handle
1305 * @return @c 0 on success,
1306 * otherwise a negative error value
1307 * @retval #SMARTTHINGS_ERROR_NONE Successful
1308 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1310 * @see smartthings_aplist_create()
1312 int smartthings_aplist_destroy(smartthings_ap_list_h ap_list_h);
1315 * @brief Sets SSID at the specific index of AP list handle.
1318 * @param[in] ap_list_h The SmartThings AP list handle
1319 * @param[in] idx The index
1320 * @param[in] ssid The SSID of AP
1322 * @return @c 0 on success,
1323 * otherwise a negative error value
1324 * @retval #SMARTTHINGS_ERROR_NONE Successful
1325 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1327 * @see smartthings_aplist_create()
1328 * @see smartthings_aplist_destroy()
1330 int smartthings_aplist_set_ssid(smartthings_ap_list_h ap_list_h, int idx, const char *ssid);
1333 * @brief Sets BSSID at the specific index of AP list handle.
1336 * @param[in] ap_list_h The SmartThings AP list handle
1337 * @param[in] idx The index
1338 * @param[in] bssid The BSSID of AP
1340 * @return @c 0 on success,
1341 * otherwise a negative error value
1342 * @retval #SMARTTHINGS_ERROR_NONE Successful
1343 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1345 * @see smartthings_aplist_create()
1346 * @see smartthings_aplist_destroy()
1348 int smartthings_aplist_set_bssid(smartthings_ap_list_h ap_list_h, int idx, const char *bssid);
1351 * @brief Sets authentification type at the specific index of AP list handle.
1354 * @param[in] ap_list_h The SmartThings AP list handle
1355 * @param[in] idx The index
1356 * @param[in] authtype The authentification type of AP
1358 * @return @c 0 on success,
1359 * otherwise a negative error value
1360 * @retval #SMARTTHINGS_ERROR_NONE Successful
1361 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1363 * @see smartthings_aplist_create()
1364 * @see smartthings_aplist_destroy()
1366 int smartthings_aplist_set_authtype(smartthings_ap_list_h ap_list_h, int idx, smartthings_wifi_authtype_e authtype);
1369 * @brief Sets encryption type at the specific index of AP list handle.
1372 * @param[in] ap_list_h The SmartThings AP list handle
1373 * @param[in] idx The index
1374 * @param[in] enctype The encryption type of AP
1376 * @return @c 0 on success,
1377 * otherwise a negative error value
1378 * @retval #SMARTTHINGS_ERROR_NONE Successful
1379 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1381 * @see smartthings_aplist_create()
1382 * @see smartthings_aplist_destroy()
1384 int smartthings_aplist_set_enctype(smartthings_ap_list_h ap_list_h, int idx, smartthings_wifi_enctype_e enctype);
1387 * @brief Sets frequency channel at the specific index of AP list handle.
1390 * @param[in] ap_list_h The SmartThings AP list handle
1391 * @param[in] idx The index
1392 * @param[in] channel The frequency channel of AP
1394 * @return @c 0 on success,
1395 * otherwise a negative error value
1396 * @retval #SMARTTHINGS_ERROR_NONE Successful
1397 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1399 * @see smartthings_aplist_create()
1400 * @see smartthings_aplist_destroy()
1402 int smartthings_aplist_set_channel(smartthings_ap_list_h ap_list_h, int idx, int channel);
1405 * @brief Sets signal level at the specific index of AP list handle.
1408 * @param[in] ap_list_h The SmartThings AP list handle
1409 * @param[in] idx The index
1410 * @param[in] signal_level The signal level of AP
1412 * @return @c 0 on success,
1413 * otherwise a negative error value
1414 * @retval #SMARTTHINGS_ERROR_NONE Successful
1415 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1417 * @see smartthings_aplist_create()
1418 * @see smartthings_aplist_destroy()
1420 int smartthings_aplist_set_signal_level(smartthings_ap_list_h ap_list_h, int idx, int signal_level);
1423 * @brief Sets max speed rate at the specific index of AP list handle.
1426 * @param[in] ap_list_h The SmartThings AP list handle
1427 * @param[in] idx The index
1428 * @param[in] max_rate The max speed rate of AP
1430 * @return @c 0 on success,
1431 * otherwise a negative error value
1432 * @retval #SMARTTHINGS_ERROR_NONE Successful
1433 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1435 * @see smartthings_aplist_create()
1436 * @see smartthings_aplist_destroy()
1438 int smartthings_aplist_set_max_rate(smartthings_ap_list_h ap_list_h, int idx, int max_rate);
1441 * @brief Sends the scanned AP list.
1443 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
1444 * %http://tizen.org/privilege/appmanager.launch \n
1445 * %http://tizen.org/privilege/datasharing \n
1446 * %http://tizen.org/privilege/internet
1448 * @param[in] handle The SmartThings handle
1449 * @param[in] ap_list_h The SmartThings AP list handle
1450 * @param[in] req_id The request ID
1452 * @return @c 0 on success,
1453 * otherwise a negative error value
1454 * @retval #SMARTTHINGS_ERROR_NONE Successful
1455 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1456 * @retval #SMARTTHINGS_ERROR_OUT_OF_MEMORY Out of memory
1457 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
1458 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1459 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
1461 * @see smartthings_aplist_create()
1462 * @see smartthings_aplist_destroy()
1463 * @see smartthings_set_scan_ap_cb()
1465 int smartthings_send_ap_list(smartthings_h handle, smartthings_ap_list_h ap_list_h, int req_id);
1468 * @brief Creates a SmartThings cloud information handle.
1471 * @remarks The @a cloud_info_h must be released using smartthings_cloudinfo_destroy().
1473 * @param[out] cloud_info_h The SmartThings cloud information handle to be newly created on success
1475 * @return @c 0 on success,
1476 * otherwise a negative error value
1477 * @retval #SMARTTHINGS_ERROR_NONE Successful
1478 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1479 * @retval #SMARTTHINGS_ERROR_OUT_OF_MEMORY Out of memory
1481 * @see smartthings_cloudinfo_destroy()
1483 int smartthings_cloudinfo_create(smartthings_cloud_info_h *cloud_info_h);
1486 * @brief Destroys a SmartThings cloud information handle.
1489 * @param[in] cloud_info_h The SmartThings cloud information handle
1491 * @return @c 0 on success,
1492 * otherwise a negative error value
1493 * @retval #SMARTTHINGS_ERROR_NONE Successful
1494 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1496 * @see smartthings_cloudinfo_create()
1498 int smartthings_cloudinfo_destroy(smartthings_cloud_info_h cloud_info_h);
1501 * @brief Sets region of cloud information.
1504 * @remarks The @a region can be set to one of "global" or "china".
1505 * @remarks If it doesn't use this function, the @a region will be set to "global" internally.
1507 * @param[in] cloud_info_h The SmartThings cloud information handle
1508 * @param[in] region The region name
1510 * @return @c 0 on success,
1511 * otherwise a negative error value
1512 * @retval #SMARTTHINGS_ERROR_NONE Successful
1513 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1515 int smartthings_cloudinfo_set_region(smartthings_cloud_info_h cloud_info_h, const char *region);
1518 * @brief Sets authentification provider of cloud information.
1521 * @param[in] cloud_info_h The SmartThings cloud information handle
1522 * @param[in] auth_provider The authentification provider
1524 * @return @c 0 on success,
1525 * otherwise a negative error value
1526 * @retval #SMARTTHINGS_ERROR_NONE Successful
1527 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1529 int smartthings_cloudinfo_set_auth_provider(smartthings_cloud_info_h cloud_info_h, const char *auth_provider);
1532 * @brief Sets access token of cloud information.
1535 * @param[in] cloud_info_h The SmartThings cloud information handle
1536 * @param[in] access_token The access token
1538 * @return @c 0 on success,
1539 * otherwise a negative error value
1540 * @retval #SMARTTHINGS_ERROR_NONE Successful
1541 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1543 int smartthings_cloudinfo_set_access_token(smartthings_cloud_info_h cloud_info_h, const char *access_token);
1546 * @brief Sets refresh token of cloud information.
1549 * @param[in] cloud_info_h The SmartThings cloud information handle
1550 * @param[in] refresh_token The refresh token
1552 * @return @c 0 on success,
1553 * otherwise a negative error value
1554 * @retval #SMARTTHINGS_ERROR_NONE Successful
1555 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1557 int smartthings_cloudinfo_set_refresh_token(smartthings_cloud_info_h cloud_info_h, const char *refresh_token);
1560 * @brief Sets user ID of cloud information.
1563 * @param[in] cloud_info_h The SmartThings cloud information handle
1564 * @param[in] user_id The user ID
1566 * @return @c 0 on success,
1567 * otherwise a negative error value
1568 * @retval #SMARTTHINGS_ERROR_NONE Successful
1569 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1571 int smartthings_cloudinfo_set_user_id(smartthings_cloud_info_h cloud_info_h, const char *user_id);
1574 * @brief Sets client ID of cloud information.
1577 * @param[in] cloud_info_h The SmartThings cloud information handle
1578 * @param[in] client_id The client ID
1580 * @return @c 0 on success,
1581 * otherwise a negative error value
1582 * @retval #SMARTTHINGS_ERROR_NONE Successful
1583 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1585 int smartthings_cloudinfo_set_client_id(smartthings_cloud_info_h cloud_info_h, const char *client_id);
1588 * @brief Requests to sign up to cloud.
1590 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
1591 * %http://tizen.org/privilege/appmanager.launch \n
1592 * %http://tizen.org/privilege/datasharing \n
1593 * %http://tizen.org/privilege/internet
1595 * @param[in] handle The SmartThings handle
1596 * @param[in] cloud_info_h The handle for cloud signup
1598 * @return @c 0 on success,
1599 * otherwise a negative error value
1600 * @retval #SMARTTHINGS_ERROR_NONE Successful
1601 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1602 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
1603 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1604 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
1606 int smartthings_sign_up_cloud(smartthings_h handle, smartthings_cloud_info_h cloud_info_h);
1609 * @brief Sets preconfigured PIN.
1611 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
1612 * %http://tizen.org/privilege/appmanager.launch \n
1613 * %http://tizen.org/privilege/datasharing
1615 * @param[in] handle The SmartThings handle
1616 * @param[in] pin The PIN code to preconfigure
1618 * @return @c 0 on success,
1619 * otherwise a negative error value
1620 * @retval #SMARTTHINGS_ERROR_NONE Successful
1621 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1622 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
1623 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1624 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
1626 int smartthings_set_preconfigured_pin(smartthings_h handle, const char* pin);
1629 * @brief Sets MOT(multiple ownership transfer) status.
1631 * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.master \n
1632 * %http://tizen.org/privilege/appmanager.launch \n
1633 * %http://tizen.org/privilege/datasharing
1635 * @param[in] handle The SmartThings handle
1636 * @param[in] enable The MOT(multiple ownership transfer) status
1638 * @return @c 0 on success,
1639 * otherwise a negative error value
1640 * @retval #SMARTTHINGS_ERROR_NONE Successful
1641 * @retval #SMARTTHINGS_ERROR_INVALID_PARAMETER Invalid parameter
1642 * @retval #SMARTTHINGS_ERROR_PERMISSION_DENIED Permission denied
1643 * @retval #SMARTTHINGS_ERROR_OPERATION_FAILED Operation failed
1644 * @retval #SMARTTHINGS_ERROR_SERVICE_UNAVAILABLE Service unavailable
1646 int smartthings_set_mot_status(smartthings_h handle, bool enable);
1656 #endif /* __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_H__ */