inc/smartthings.h

   1 /*****************************************************************
   2  *
   3  * Copyright (c) 2018 Samsung Electronics Co., Ltd. All Rights Reserved
   4  *
   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
   8  *
   9  * http://www.apache.org/licenses/LICENSE-2.0
  10  *
  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.
  16  *
  17  ******************************************************************/
  18
  19
  20 #ifndef __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_H__
  21 #define __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_H__
  22
  23 #include <stdlib.h>
  24 #include <stdbool.h>
  25 #include <tizen.h>
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 /**
  32  * @addtogroup CAPI_SMARTTHINGS_THING_MASTER_MODULE
  33  * @{
  34  */
  35
  36 /**
  37  * @brief Definition for the max length of SSID for access point.
  38  * @since_ses 1
  39  */
  40 #define SMARTTHINGS_SSID_LEN_MAX 32
  41
  42 /**
  43  * @brief Definition for the max length of cloud information.
  44  * @since_ses 1
  45  */
  46 #define SMARTTHINGS_CLOUD_INFO_LEN_MAX 128
  47
  48 /**
  49  * @brief Enumeration for the SmartThings error.
  50  * @since_ses 1
  51  */
  52 typedef enum {
  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;
  62
  63 /**
  64  * @brief Enumeration for SmartThings status.
  65  * @since_ses 1
  66  */
  67 typedef enum {
  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;
  81
  82 /**
  83  * @brief Enumeration for RPC connection status.
  84  * @since_ses 1
  85  */
  86 typedef enum {
  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;
  91
  92 /**
  93  * @brief The Wi-Fi mode.
  94  * @since_ses 1
  95  */
  96 typedef enum {
  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;
 103
 104 /**
 105  * @brief The Wi-Fi frequency band.
 106  * @since_ses 1
 107  */
 108 typedef enum {
 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;
 112
 113 /**
 114  * @brief The Wi-Fi authentication type of access point.
 115  * @since_ses 1
 116  */
 117 typedef enum {
 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;
 123
 124 /**
 125  * @brief The Wi-Fi encryption type of access point.
 126  * @since_ses 1
 127  */
 128 typedef enum {
 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;
 136
 137 /**
 138  * @brief The SmartThings handle.
 139  * @since_ses 1
 140  */
 141 typedef struct smartthings_s *smartthings_h;
 142
 143 /**
 144  * @brief The access point information handle.
 145  * @since_ses 1
 146  */
 147 typedef struct smartthings_ap_info_s *smartthings_ap_info_h;
 148
 149 /**
 150  * @brief The device provisioning information handle.
 151  * @since_ses 1
 152  */
 153 typedef struct smartthings_device_prov_info_s *smartthings_device_prov_info_h;
 154
 155 /**
 156  * @brief The cloud information handle for cloud sign-up.
 157  * @since_ses 1
 158  */
 159 typedef struct smartthings_cloud_info_s *smartthings_cloud_info_h;
 160
 161 /**
 162  * @brief The access point list handle.
 163  * @since_ses 1
 164  */
 165 typedef struct smartthings_ap_list_s *smartthings_ap_list_h;
 166
 167 /**
 168  * @brief Callback for status of connection to SmartThings Thing agent.
 169  * @since_ses 1
 170  *
 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.
 175  *
 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
 180  *
 181  * @see smartthings_initialize()
 182  */
 183 typedef void (*smartthings_connection_status_cb)(smartthings_h handle, smartthings_connection_status_e status, void *user_data);
 184
 185 /**
 186  * @brief Callback for SmartThings Thing status.
 187  * @since_ses 1
 188  *
 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.
 193  *
 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
 197  *
 198  * @see smartthings_set_status_changed_cb()
 199  * @see smartthings_unset_status_changed_cb()
 200  */
 201 typedef void (*smartthings_status_changed_cb)(smartthings_h handle, smartthings_status_e status, void *user_data);
 202
 203 /**
 204  * @brief Callback for getting user's input regarding mutual verification.
 205  * @since_ses 1
 206  *
 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.
 211  *
 212  * @param[in] handle The SmartThings handle
 213  * @param[in] user_data The user data passed from the callback registration function
 214  *
 215  * @see smartthings_set_user_confirm_cb()
 216  * @see smartthings_unset_user_confirm_cb()
 217  */
 218 typedef void (*smartthings_user_confirm_cb)(smartthings_h handle, void *user_data);
 219
 220 /**
 221  * @brief Callback for getting user's opinion regarding device reset.
 222  * @since_ses 1
 223  *
 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.
 228  *
 229  * @param[in] handle The SmartThings handle
 230  * @param[in] user_data The user data passed from the callback registration function
 231  *
 232  * @see smartthings_set_reset_confirm_cb()
 233  * @see smartthings_unset_reset_confirm_cb()
 234  */
 235 typedef void (*smartthings_reset_confirm_cb)(smartthings_h handle, void *user_data);
 236
 237 /**
 238  * @brief Callback for result of reset operation.
 239  * @since_ses 1
 240  *
 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.
 245  *
 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
 249  *
 250  * @see smartthings_set_reset_result_cb()
 251  * @see smartthings_unset_reset_result_cb()
 252  */
 253 typedef void (*smartthings_reset_result_cb)(smartthings_h handle, bool result, void *user_data);
 254
 255 /**
 256  * @brief Callback for carrying the randomly generated PIN information.
 257  * @since_ses 1
 258  *
 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.
 264  *
 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
 269  *
 270  * @see smartthings_set_pin_cb()
 271  * @see smartthings_unset_pin_cb()
 272  */
 273 typedef void (*smartthings_pin_generated_cb)(smartthings_h handle, const char* pin, size_t size, void *user_data);
 274
 275 /**
 276  * @brief Callback for informing the application to close the PIN display.
 277  * @since_ses 1
 278  *
 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.
 283  *
 284  * @param[in] handle The SmartThings handle
 285  * @param[in] user_data The user data passed from the callback registration function
 286  *
 287  * @see smartthings_set_pin_cb()
 288  * @see smartthings_unset_pin_cb()
 289  */
 290 typedef void (*smartthings_pin_display_close_cb)(smartthings_h handle, void *user_data);
 291
 292 /**
 293  * @brief Callback for informing Wi-Fi AP information to connect.
 294  * @since_ses 1
 295  *
 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.
 302  *
 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
 306  *
 307  * @see smartthings_set_wifi_ap_provisioning_cb()
 308  * @see smartthings_unset_wifi_ap_provisioning_cb()
 309  */
 310 typedef void (*smartthings_wifi_ap_provisioning_cb)(smartthings_h handle, smartthings_ap_info_h ap_info_h, void *user_data);
 311
 312 /**
 313  * @brief Callback for informing device provisioning information.
 314  * @since_ses 1
 315  *
 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.
 322  *
 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
 326  *
 327  * @see smartthings_set_device_provisioning_cb()
 328  * @see smartthings_unset_device_provisioning_cb()
 329  */
 330 typedef void (*smartthings_device_provisioning_cb)(smartthings_h handle, smartthings_device_prov_info_h dev_prov_h, void *user_data);
 331
 332 /**
 333  * @brief Callback for informing the scan AP list request.
 334  * @since_ses 1
 335  *
 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.
 340  *
 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
 344  *
 345  * @see smartthings_set_scan_ap_cb()
 346  * @see smartthings_unset_scan_ap_cb()
 347  */
 348 typedef void (*smartthings_scan_ap_cb)(smartthings_h handle, int req_id, void *user_data);
 349
 350 /**
 351  * @brief Callback for informing the stop soft AP request.
 352  * @since_ses 1
 353  *
 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.
 358  *
 359  * @param[in] handle The SmartThings handle
 360  * @param[in] user_data The user data passed from the callback registration function
 361  *
 362  * @see smartthings_set_stop_soft_ap_cb()
 363  * @see smartthings_unset_stop_soft_ap_cb()
 364  */
 365 typedef void (*smartthings_stop_soft_ap_cb)(smartthings_h handle, void *user_data);
 366
 367 /**
 368  * @brief Creates a handle and connects to agent.
 369  * @since_ses 1
 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
 373  *
 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'.
 377  *
 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
 381  *
 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
 391  *
 392  * @see smartthings_deinitialize()
 393  */
 394 int smartthings_initialize(smartthings_h *handle,
 395                                                 smartthings_connection_status_cb connection_status_cb,
 396                                                 void *user_data);
 397
 398 /**
 399  * @brief Deinitializes a handle and disconnects from the agent.
 400  * @since_ses 1
 401  *
 402  * @param[in] handle The SmartThings handle
 403  *
 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
 409  *
 410  * @see smartthings_initialize()
 411  */
 412 int smartthings_deinitialize(smartthings_h handle);
 413
 414 /**
 415  * @brief Starts SmartThings Thing operation.
 416  * @since_ses 1
 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
 420  *
 421  * @param[in] handle The SmartThings handle
 422  *
 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
 430  *
 431  * @see smartthings_stop()
 432  */
 433 int smartthings_start(smartthings_h handle);
 434
 435 /**
 436  * @brief Stops SmartThings Thing operation.
 437  * @since_ses 1
 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
 441  *
 442  * @param[in] handle The SmartThings handle
 443  *
 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
 451  *
 452  * @see smartthings_start()
 453  */
 454 int smartthings_stop(smartthings_h handle);
 455
 456 /**
 457  * @brief Sets thing status changed callback.
 458  * @since_ses 1
 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
 462  *
 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.
 467  *
 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
 471  *
 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
 479  *
 480  * @see smartthings_unset_status_changed_cb()
 481  */
 482 int smartthings_set_status_changed_cb(smartthings_h handle,
 483                                                                 smartthings_status_changed_cb status_cb,
 484                                                                 void *user_data);
 485
 486 /**
 487  * @brief Unsets thing status changed callback.
 488  * @since_ses 1
 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
 492  *
 493  * @param[in] handle The SmartThings handle
 494  *
 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
 502  *
 503  * @see smartthings_set_status_changed_cb()
 504  */
 505 int smartthings_unset_status_changed_cb(smartthings_h handle);
 506
 507 /**
 508  * @brief Sets test certificate files.
 509  * @since_ses 1
 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
 513  *
 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()
 517  *
 518  * @param[in] handle The SmartThings handle
 519  * @param[in] certificate The certificate file
 520  * @param[in] private_key The private key file
 521  *
 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
 529  */
 530 int smartthings_set_certificate_file(smartthings_h handle, const char *certificate, const char *private_key);
 531
 532 /**
 533  * @brief Sets device property for Easy-setup.
 534  * @since_ses 1
 535  *
 536  * @remarks This function can be used before smartthings_start()
 537  *
 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)
 542  *
 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
 547  */
 548 int smartthings_set_device_property(smartthings_h handle, const char* dev_name, int wifi_mode, int wifi_freq);
 549
 550 /**
 551  * @brief Gets a device ID.
 552  * @since_ses 1
 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
 556  *
 557  * @remarks The @a device_id should be released using free().
 558  *
 559  * @param[in] handle The SmartThings handle
 560  * @param[out] device_id The device ID
 561  *
 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
 569  */
 570 int smartthings_get_device_id(smartthings_h handle, char **device_id);
 571
 572 /**
 573  * @brief Gets a Easy-setup status.
 574  * @since_ses 1
 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
 578  *
 579  * @param[in] handle The SmartThings handle
 580  * @param[out] is_completed The status of Easy-setup whether it is completed or not
 581  *
 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
 589  */
 590 int smartthings_get_easysetup_status(smartthings_h handle, bool *is_completed);
 591
 592 /**
 593  * @brief Starts Easy-setup mode.
 594  *
 595  * @details This function requests for turning on soft AP to SmartThings Thing agent.
 596  * @since_ses 1
 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
 601  *
 602  * @param[in] handle The SmartThings handle
 603  *
 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
 611  *
 612  * @see smartthings_stop_easysetup()
 613  */
 614 int smartthings_start_easysetup(smartthings_h handle);
 615
 616 /**
 617  * @brief Stops Easy-setup mode.
 618  *
 619  * @details This function requests for turning off soft AP to SmartThings Thing agent.
 620  * @since_ses 1
 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
 625  *
 626  * @param[in] handle The SmartThings handle
 627  *
 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
 635  *
 636  * @see smartthings_start_easysetup()
 637  */
 638 int smartthings_stop_easysetup(smartthings_h handle);
 639
 640 /**
 641  * @brief Sets callback for getting user confirmation for mutual verification based just work ownership transfer.
 642  * @since_ses 1
 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
 646  *
 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.
 651  *
 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
 655  *
 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
 663  *
 664  * @see smartthings_unset_user_confirm_cb()
 665  */
 666 int smartthings_set_user_confirm_cb(smartthings_h handle,
 667                                                                 smartthings_user_confirm_cb confirm_cb,
 668                                                                 void *user_data);
 669
 670 /**
 671  * @brief Unsets user confirmation callback.
 672  * @since_ses 1
 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
 676  *
 677  * @param[in] handle The SmartThings handle
 678  *
 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
 686  *
 687  * @see smartthings_set_user_confirm_cb()
 688  */
 689 int smartthings_unset_user_confirm_cb(smartthings_h handle);
 690
 691 /**
 692  * @brief Sets reset confirmation callback.
 693  * @since_ses 1
 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
 697  *
 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.
 702  *
 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
 706  *
 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
 714  *
 715  * @see smartthings_unset_reset_confirm_cb()
 716  */
 717 int smartthings_set_reset_confirm_cb(smartthings_h handle,
 718                                                                 smartthings_reset_confirm_cb confirm_cb,
 719                                                                 void *user_data);
 720
 721 /**
 722  * @brief Unsets reset confirmation callback.
 723  * @since_ses 1
 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
 727  *
 728  * @param[in] handle The SmartThings handle
 729  *
 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
 737  *
 738  * @see smartthings_set_reset_confirm_cb()
 739  */
 740 int smartthings_unset_reset_confirm_cb(smartthings_h handle);
 741
 742 /**
 743  * @brief Sets reset result callback.
 744  * @since_ses 1
 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
 748  *
 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.
 753  *
 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
 757  *
 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
 765  *
 766  * @see smartthings_unset_reset_result_cb()
 767  */
 768 int smartthings_set_reset_result_cb(smartthings_h handle,
 769                                                                 smartthings_reset_result_cb reset_result_cb,
 770                                                                 void *user_data);
 771
 772 /**
 773  * @brief Unsets reset result callback.
 774  * @since_ses 1
 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
 778  *
 779  * @param[in] handle The SmartThings handle
 780  *
 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
 788  *
 789  * @see smartthings_set_reset_result_cb()
 790  */
 791 int smartthings_unset_reset_result_cb(smartthings_h handle);
 792
 793
 794 /**
 795  * @brief Sets callback for getting randomly generated PIN for the PIN-based ownership transfer request.
 796  * @since_ses 1
 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
 800  *
 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.
 807  *
 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
 812  *
 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
 820  *
 821  * @see smartthings_unset_pin_cb()
 822  */
 823 int smartthings_set_pin_cb(smartthings_h handle,
 824                                                                 smartthings_pin_generated_cb generated_cb,
 825                                                                 smartthings_pin_display_close_cb close_cb,
 826                                                                 void *user_data);
 827
 828 /**
 829  * @brief Unsets PIN callback.
 830  * @since_ses 1
 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
 834  *
 835  * @param[in] handle The SmartThings handle
 836  *
 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
 844  *
 845  * @see smartthings_set_pin_cb()
 846  */
 847 int smartthings_unset_pin_cb(smartthings_h handle);
 848
 849 /**
 850  * @brief Sets callback for getting Wi-Fi AP information during Easy-setup.
 851  * @since_ses 1
 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
 855  *
 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.
 860  *
 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
 864  *
 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
 872  *
 873  * @see smartthings_unset_wifi_ap_provisioning_cb()
 874  */
 875 int smartthings_set_wifi_ap_provisioning_cb(smartthings_h handle,
 876                                                                 smartthings_wifi_ap_provisioning_cb wifi_ap_cb,
 877                                                                 void *user_data);
 878
 879 /**
 880  * @brief Unsets callback for getting Wi-Fi AP information during Easy-setup.
 881  * @since_ses 1
 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
 885  *
 886  * @param[in] handle The SmartThings handle
 887  *
 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
 895  *
 896  * @see smartthings_set_wifi_ap_provisioning_cb()
 897  */
 898 int smartthings_unset_wifi_ap_provisioning_cb(smartthings_h handle);
 899
 900 /**
 901  * @brief Sets callback for getting device provisioning information.
 902  * @since_ses 1
 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
 906  *
 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.
 911  *
 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
 915  *
 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
 923  *
 924  * @see smartthings_unset_device_provisioning_cb()
 925  */
 926 int smartthings_set_device_provisioning_cb(smartthings_h handle,
 927                                                                 smartthings_device_provisioning_cb dev_prov_cb,
 928                                                                 void *user_data);
 929
 930 /**
 931  * @brief Unsets callback for getting device provisioning information.
 932  * @since_ses 1
 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
 936  *
 937  * @param[in] handle The SmartThings handle
 938  *
 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
 946  *
 947  * @see smartthings_set_device_provisioning_cb()
 948  */
 949 int smartthings_unset_device_provisioning_cb(smartthings_h handle);
 950
 951 /**
 952  * @brief Sets callback for informing the scan AP list request.
 953  * @since_ses 1
 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
 957  *
 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.
 962  *
 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
 966  *
 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
 974  *
 975  * @see smartthings_unset_scan_ap_cb()
 976  * @see smartthings_send_ap_list()
 977  */
 978 int smartthings_set_scan_ap_cb(smartthings_h handle,
 979                                                                 smartthings_scan_ap_cb scan_ap_cb,
 980                                                                 void *user_data);
 981
 982 /**
 983  * @brief Unsets callback for informing the scan AP list request.
 984  * @since_ses 1
 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
 988  *
 989  * @param[in] handle The SmartThings handle
 990  *
 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
 998  *
 999  * @see smartthings_set_scan_ap_cb()
1000  */
1001 int smartthings_unset_scan_ap_cb(smartthings_h handle);
1002
1003 /**
1004  * @brief Sets callback for informing the stop soft AP request.
1005  * @since_ses 1
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
1009  *
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.
1014  *
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
1018  *
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
1026  *
1027  * @see smartthings_unset_stop_soft_ap_cb()
1028  */
1029 int smartthings_set_stop_soft_ap_cb(smartthings_h handle,
1030                                                                 smartthings_stop_soft_ap_cb stop_soft_ap_cb,
1031                                                                 void *user_data);
1032
1033 /**
1034  * @brief Unsets callback for informing the stop soft AP request.
1035  * @since_ses 1
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
1039  *
1040  * @param[in] handle The SmartThings handle
1041  *
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
1049  *
1050  * @see smartthings_set_stop_soft_ap_cb()
1051  */
1052 int smartthings_unset_stop_soft_ap_cb(smartthings_h handle);
1053
1054 /**
1055  * @brief Sends a user confirmation for MUTUAL VERIFICATION BASED JUST WORK Ownership transfer.
1056  * @since_ses 1
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
1061  *
1062  * @param[in] handle The SmartThings handle
1063  * @param[in] confirm The user confirmation for OTM(ownership transfer method)
1064  *
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
1072  *
1073  * @see smartthings_set_user_confirm_cb()
1074  * @see smartthings_unset_user_confirm_cb()
1075  */
1076 int smartthings_send_user_confirm(smartthings_h handle, bool confirm);
1077
1078
1079 /**
1080  * @brief Sends a reset confirmation.
1081  * @since_ses 1
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
1086  *
1087  * @param[in] handle The SmartThings handle
1088  * @param[in] confirm The reset confirmation
1089  *
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
1097  *
1098  * @see smartthings_set_reset_confirm_cb()
1099  * @see smartthings_unset_reset_confirm_cb()
1100  */
1101 int smartthings_send_reset_confirm(smartthings_h handle, bool confirm);
1102
1103 /**
1104  * @brief Sends a reset command for resetting the device's Cloud signup and Easy-setup.
1105  * @since_ses 1
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
1110  *
1111  * @param[in] handle The SmartThings handle
1112  *
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
1120  *
1121  * @see smartthings_set_reset_result_cb()
1122  * @see smartthings_unset_reset_result_cb()
1123  */
1124 int smartthings_reset(smartthings_h handle);
1125
1126 /**
1127  * @brief Gets SSID of access point.
1128  * @since_ses 1
1129  *
1130  * @remarks The @a ssid should be released using free().
1131  *
1132  * @param[in] ap_info_h The SmartThings AP information handle
1133  * @param[out] ssid The SSID name
1134  *
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
1140  *
1141  * @see smartthings_set_wifi_ap_provisioning_cb()
1142  * @see smartthings_unset_wifi_ap_provisioning_cb()
1143  */
1144 int smartthings_apinfo_get_ssid(smartthings_ap_info_h ap_info_h, char **ssid);
1145
1146 /**
1147  * @brief Gets password of access point.
1148  * @since_ses 1
1149  *
1150  * @remarks The @a pwd should be released using free().
1151  *
1152  * @param[in] ap_info_h The SmartThings AP information handle
1153  * @param[out] pwd The password
1154  *
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
1160  *
1161  * @see smartthings_set_wifi_ap_provisioning_cb()
1162  * @see smartthings_unset_wifi_ap_provisioning_cb()
1163  */
1164 int smartthings_apinfo_get_password(smartthings_ap_info_h ap_info_h, char **pwd);
1165
1166 /**
1167  * @brief Gets authentification type of access point.
1168  * @since_ses 1
1169  *
1170  * @param[in] ap_info_h The SmartThings AP information handle
1171  * @param[out] authtype The authentification type
1172  *
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
1178  *
1179  * @see smartthings_set_wifi_ap_provisioning_cb()
1180  * @see smartthings_unset_wifi_ap_provisioning_cb()
1181  */
1182 int smartthings_apinfo_get_authtype(smartthings_ap_info_h ap_info_h, smartthings_wifi_authtype_e *authtype);
1183
1184 /**
1185  * @brief Gets encryption type of access point.
1186  * @since_ses 1
1187  *
1188  * @param[in] ap_info_h The SmartThings AP information handle
1189  * @param[out] enctype The encryption type
1190  *
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
1196  *
1197  * @see smartthings_set_wifi_ap_provisioning_cb()
1198  * @see smartthings_unset_wifi_ap_provisioning_cb()
1199  */
1200 int smartthings_apinfo_get_enctype(smartthings_ap_info_h ap_info_h, smartthings_wifi_enctype_e *enctype);
1201
1202 /**
1203  * @brief Gets channel information of access point.
1204  * @since_ses 1
1205  *
1206  * @param[in] ap_info_h The SmartThings AP information handle
1207  * @param[out] channel The frequency channel
1208  *
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
1214  *
1215  * @see smartthings_set_wifi_ap_provisioning_cb()
1216  * @see smartthings_unset_wifi_ap_provisioning_cb()
1217  */
1218 int smartthings_apinfo_get_channel(smartthings_ap_info_h ap_info_h, int *channel);
1219
1220 /**
1221  * @brief Gets language of device provisioing information.
1222  * @since_ses 1
1223  *
1224  * @remarks The @a language should be released using free().
1225  *
1226  * @param[in] dev_prov_h The SmartThings device provisioning information handle
1227  * @param[out] language The IETF language tag using ISO 639X
1228  *
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
1234  *
1235  * @see smartthings_set_device_provisioning_cb()
1236  * @see smartthings_unset_device_provisioning_cb()
1237  */
1238 int smartthings_devinfo_get_language(smartthings_device_prov_info_h dev_prov_h, char **language);
1239
1240 /**
1241  * @brief Gets country of device provisioing information.
1242  * @since_ses 1
1243  *
1244  * @remarks The @a country should be released using free().
1245  *
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)
1248  *
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
1254  *
1255  * @see smartthings_set_device_provisioning_cb()
1256  * @see smartthings_unset_device_provisioning_cb()
1257  */
1258 int smartthings_devinfo_get_country(smartthings_device_prov_info_h dev_prov_h, char **country);
1259
1260 /**
1261  * @brief Gets datetime of device provisioing information.
1262  * @since_ses 1
1263  *
1264  * @remarks The @a datetime should be released using free().
1265  *
1266  * @param[in] dev_prov_h The SmartThings device provisioning information handle
1267  * @param[out] datetime The date and time
1268  *
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
1274  *
1275  * @see smartthings_set_device_provisioning_cb()
1276  * @see smartthings_unset_device_provisioning_cb()
1277  */
1278 int smartthings_devinfo_get_datetime(smartthings_device_prov_info_h dev_prov_h, char **datetime);
1279
1280 /**
1281  * @brief Creates a SmartThings AP list handle.
1282  * @since_ses 1
1283  *
1284  * @remarks The @a ap_list_h must be released using smartthings_aplist_destroy().
1285  *
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
1288  *
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
1294  *
1295  * @see smartthings_aplist_destroy()
1296  */
1297 int smartthings_aplist_create(smartthings_ap_list_h *ap_list_h, unsigned int count);
1298
1299 /**
1300  * @brief Destroys a SmartThings AP list handle.
1301  * @since_ses 1
1302  *
1303  * @param[in] ap_list_h The SmartThings AP list handle
1304  *
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
1309  *
1310  * @see smartthings_aplist_create()
1311  */
1312 int smartthings_aplist_destroy(smartthings_ap_list_h ap_list_h);
1313
1314 /**
1315  * @brief Sets SSID at the specific index of AP list handle.
1316  * @since_ses 1
1317  *
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
1321  *
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
1326  *
1327  * @see smartthings_aplist_create()
1328  * @see smartthings_aplist_destroy()
1329  */
1330 int smartthings_aplist_set_ssid(smartthings_ap_list_h ap_list_h, int idx, const char *ssid);
1331
1332 /**
1333  * @brief Sets BSSID at the specific index of AP list handle.
1334  * @since_ses 1
1335  *
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
1339  *
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
1344  *
1345  * @see smartthings_aplist_create()
1346  * @see smartthings_aplist_destroy()
1347  */
1348 int smartthings_aplist_set_bssid(smartthings_ap_list_h ap_list_h, int idx, const char *bssid);
1349
1350 /**
1351  * @brief Sets authentification type at the specific index of AP list handle.
1352  * @since_ses 1
1353  *
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
1357  *
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
1362  *
1363  * @see smartthings_aplist_create()
1364  * @see smartthings_aplist_destroy()
1365  */
1366 int smartthings_aplist_set_authtype(smartthings_ap_list_h ap_list_h, int idx, smartthings_wifi_authtype_e authtype);
1367
1368 /**
1369  * @brief Sets encryption type at the specific index of AP list handle.
1370  * @since_ses 1
1371  *
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
1375  *
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
1380  *
1381  * @see smartthings_aplist_create()
1382  * @see smartthings_aplist_destroy()
1383  */
1384 int smartthings_aplist_set_enctype(smartthings_ap_list_h ap_list_h, int idx, smartthings_wifi_enctype_e enctype);
1385
1386 /**
1387  * @brief Sets frequency channel at the specific index of AP list handle.
1388  * @since_ses 1
1389  *
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
1393  *
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
1398  *
1399  * @see smartthings_aplist_create()
1400  * @see smartthings_aplist_destroy()
1401  */
1402 int smartthings_aplist_set_channel(smartthings_ap_list_h ap_list_h, int idx, int channel);
1403
1404 /**
1405  * @brief Sets signal level at the specific index of AP list handle.
1406  * @since_ses 1
1407  *
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
1411  *
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
1416  *
1417  * @see smartthings_aplist_create()
1418  * @see smartthings_aplist_destroy()
1419  */
1420 int smartthings_aplist_set_signal_level(smartthings_ap_list_h ap_list_h, int idx, int signal_level);
1421
1422 /**
1423  * @brief Sets max speed rate at the specific index of AP list handle.
1424  * @since_ses 1
1425  *
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
1429  *
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
1434  *
1435  * @see smartthings_aplist_create()
1436  * @see smartthings_aplist_destroy()
1437  */
1438 int smartthings_aplist_set_max_rate(smartthings_ap_list_h ap_list_h, int idx, int max_rate);
1439
1440 /**
1441  * @brief Sends the scanned AP list.
1442  * @since_ses 1
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
1447  *
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
1451  *
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
1460  *
1461  * @see smartthings_aplist_create()
1462  * @see smartthings_aplist_destroy()
1463  * @see smartthings_set_scan_ap_cb()
1464  */
1465 int smartthings_send_ap_list(smartthings_h handle, smartthings_ap_list_h ap_list_h, int req_id);
1466
1467 /**
1468  * @brief Creates a SmartThings cloud information handle.
1469  * @since_ses 1
1470  *
1471  * @remarks The @a cloud_info_h must be released using smartthings_cloudinfo_destroy().
1472  *
1473  * @param[out] cloud_info_h The SmartThings cloud information handle to be newly created on success
1474  *
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
1480  *
1481  * @see smartthings_cloudinfo_destroy()
1482  */
1483 int smartthings_cloudinfo_create(smartthings_cloud_info_h *cloud_info_h);
1484
1485 /**
1486  * @brief Destroys a SmartThings cloud information handle.
1487  * @since_ses 1
1488  *
1489  * @param[in] cloud_info_h The SmartThings cloud information handle
1490  *
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
1495  *
1496  * @see smartthings_cloudinfo_create()
1497  */
1498 int smartthings_cloudinfo_destroy(smartthings_cloud_info_h cloud_info_h);
1499
1500 /**
1501  * @brief Sets region of cloud information.
1502  * @since_ses 1
1503  *
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.
1506  *
1507  * @param[in] cloud_info_h The SmartThings cloud information handle
1508  * @param[in] region The region name
1509  *
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
1514  */
1515 int smartthings_cloudinfo_set_region(smartthings_cloud_info_h cloud_info_h, const char *region);
1516
1517 /**
1518  * @brief Sets authentification provider of cloud information.
1519  * @since_ses 1
1520  *
1521  * @param[in] cloud_info_h The SmartThings cloud information handle
1522  * @param[in] auth_provider The authentification provider
1523  *
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
1528  */
1529 int smartthings_cloudinfo_set_auth_provider(smartthings_cloud_info_h cloud_info_h, const char *auth_provider);
1530
1531 /**
1532  * @brief Sets access token of cloud information.
1533  * @since_ses 1
1534  *
1535  * @param[in] cloud_info_h The SmartThings cloud information handle
1536  * @param[in] access_token The access token
1537  *
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
1542  */
1543 int smartthings_cloudinfo_set_access_token(smartthings_cloud_info_h cloud_info_h, const char *access_token);
1544
1545 /**
1546  * @brief Sets refresh token of cloud information.
1547  * @since_ses 1
1548  *
1549  * @param[in] cloud_info_h The SmartThings cloud information handle
1550  * @param[in] refresh_token The refresh token
1551  *
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
1556  */
1557 int smartthings_cloudinfo_set_refresh_token(smartthings_cloud_info_h cloud_info_h, const char *refresh_token);
1558
1559 /**
1560  * @brief Sets user ID of cloud information.
1561  * @since_ses 1
1562  *
1563  * @param[in] cloud_info_h The SmartThings cloud information handle
1564  * @param[in] user_id The user ID
1565  *
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
1570  */
1571 int smartthings_cloudinfo_set_user_id(smartthings_cloud_info_h cloud_info_h, const char *user_id);
1572
1573 /**
1574  * @brief Sets client ID of cloud information.
1575  * @since_ses 1
1576  *
1577  * @param[in] cloud_info_h The SmartThings cloud information handle
1578  * @param[in] client_id The client ID
1579  *
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
1584  */
1585 int smartthings_cloudinfo_set_client_id(smartthings_cloud_info_h cloud_info_h, const char *client_id);
1586
1587 /**
1588  * @brief Requests to sign up to cloud.
1589  * @since_ses 1
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
1594  *
1595  * @param[in] handle The SmartThings handle
1596  * @param[in] cloud_info_h The handle for cloud signup
1597  *
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
1605  */
1606 int smartthings_sign_up_cloud(smartthings_h handle, smartthings_cloud_info_h cloud_info_h);
1607
1608 /**
1609  * @brief Sets preconfigured PIN.
1610  * @since_ses 1
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
1614  *
1615  * @param[in] handle The SmartThings handle
1616  * @param[in] pin The PIN code to preconfigure
1617  *
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
1625  */
1626 int smartthings_set_preconfigured_pin(smartthings_h handle, const char* pin);
1627
1628 /**
1629  * @brief Sets MOT(multiple ownership transfer) status.
1630  * @since_ses 1
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
1634  *
1635  * @param[in] handle The SmartThings handle
1636  * @param[in] enable The MOT(multiple ownership transfer) status
1637  *
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
1645  */
1646 int smartthings_set_mot_status(smartthings_h handle, bool enable);
1647
1648 /**
1649  * @}
1650  */
1651
1652 #ifdef __cplusplus
1653 }
1654 #endif
1655
1656 #endif /* __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_H__ */