include/smartthings_resource.h

   1  /*
   2  * Copyright (c) 2018 Samsung Electronics Co., Ltd.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_RESOURCE_H__
  18 #define __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_RESOURCE_H__
  19
  20 #include <stdio.h>
  21 #include <stdlib.h>
  22 #include <stdbool.h>
  23 #include <tizen.h>
  24 #include <smartthings_payload.h>
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /**
  31  * @file smartthings_resource.h
  32  */
  33
  34 /**
  35  * @addtogroup CAPI_SMARTTHINGS_THING_RESOURCE_MODULE
  36  * @{
  37  */
  38
  39 /**
  40  * @brief Enumeration for the SmartThings resource error.
  41  * @since_ses 1
  42  */
  43 typedef enum {
  44         SMARTTHINGS_RESOURCE_ERROR_NONE = TIZEN_ERROR_NONE,                                /**< Successful */
  45         SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,      /**< Invalid parameter */
  46         SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,              /**< Out of memory */
  47         SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,      /**< Permission denied */
  48         SMARTTHINGS_RESOURCE_ERROR_NO_DATA = TIZEN_ERROR_NO_DATA,                          /**< No data */
  49         SMARTTHINGS_RESOURCE_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED,                      /**< Not supported */
  50         SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED = TIZEN_ERROR_UNKNOWN - 1,             /**< Operation failed */
  51         SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE = TIZEN_ERROR_UNKNOWN -2            /**< Service unavailable */
  52 } smartthings_resource_error_e;
  53
  54 /**
  55  * @brief Enumeration for the request type of resource and collection resource.
  56  * @since_ses 1
  57  */
  58 typedef enum {
  59         SMARTTHINGS_RESOURCE_REQUEST_GET = 0,              /**< Get request type */
  60         SMARTTHINGS_RESOURCE_REQUEST_SET = 1,              /**< Set request type */
  61         SMARTTHINGS_RESOURCE_REQUEST_COLLECTION_GET = 2,   /**< Get request type for collection */
  62         SMARTTHINGS_RESOURCE_REQUEST_COLLECTION_SET = 3    /**< Set request type for collection */
  63 } smartthings_resource_req_type_e;
  64
  65 /**
  66  * @brief Enumeration for RPC connection status.
  67  * @since_ses 1
  68  */
  69 typedef enum {
  70         SMARTTHINGS_RESOURCE_CONNECTION_STATUS_CONNECTED = 0,          /**< Connection is connected */
  71         SMARTTHINGS_RESOURCE_CONNECTION_STATUS_DISCONNECTED,           /**< Connection is disconnected */
  72         SMARTTHINGS_RESOURCE_CONNECTION_STATUS_REJECTED,               /**< Connection is rejected */
  73 } smartthings_resource_connection_status_e;
  74
  75 /**
  76  * @brief The SmartThings resource handle.
  77  * @since_ses 1
  78  */
  79 typedef struct smartthings_resource_s *smartthings_resource_h;
  80
  81 /**
  82  * @brief Callback for status of connection to SmartThings Thing agent.
  83   * @details The following error codes can be received: \n
  84         #SMARTTHINGS_RESOURCE_ERROR_NONE:                               Success \n
  85         #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED:      Permission denied \n
  86         #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE:   Service unavailable \n
  87  * @since_ses 1
  88  *
  89  * @remarks The @a handle should not be released.
  90  * @remarks The @a handle is the same object for which the callback was set/added.
  91  * @remarks The @a handle will be released when smartthings_deinitialize() is called.
  92  * @remarks When callback is called, user can see result as #smartthings_resource_error_e enumeration value.
  93  * @remarks When callback is called, user can see connection status as #smartthings_connection_status_e enumeration value.
  94  *
  95  * @param[in] result The result of connection operation
  96  * @param[in] handle The SmartThings handle
  97  * @param[in] status The status of connection
  98  * @param[in] user_data The user data passed from the callback registration function
  99  *
 100  * @see smartthings_resource_initialize()
 101  */
 102 typedef void (*smartthings_resource_connection_status_cb)(smartthings_resource_error_e result, smartthings_resource_h handle, smartthings_resource_connection_status_e status, void *user_data);
 103
 104
 105 /**
 106  * @brief Callback for handling request(GET/SET) messages.
 107  * @since_ses 1
 108  *
 109  * @remarks The @a payload is NULL when @a req_type is #SMARTTHINGS_RESOURCE_REQUEST_GET.
 110  * @remarks The @a payload can be used only in the callback. To use outside, make a copy.
 111  * @remarks The @a st_h should not be released.
 112  * @remarks The @a st_h is the same object for which the callback was set/added.
 113  * @remarks The @a st_h will be released when smartthings_resource_deinitialize() is called.
 114  * @remarks The @a payload should not be released.
 115  * @remarks The @a uri can be used only in the callback. To use outside, make a copy.
 116  *
 117  * @param[in] st_h The SmartThings resource handle
 118  * @param[in] req_id The request ID of request message
 119  * @param[in] uri The resource URI
 120  * @param[in] req_type The request type for request message
 121  * @param[in] payload The payload for SET request message
 122  * @param[in] user_data The user data passed from the callback registration function
 123  *
 124  * @see smartthings_resource_set_request_cb()
 125  * @see smartthings_resource_unset_request_cb()
 126  */
 127 typedef void (*smartthings_resource_request_cb)(smartthings_resource_h st_h, int req_id, const char *uri,
 128                                                                                                 smartthings_resource_req_type_e req_type,
 129                                                                                                 smartthings_payload_h payload, void *user_data);
 130
 131 /**
 132  * @brief Callback for status of resource registration to cloud.
 133  * @since_ses 1
 134  *
 135  * @remarks This callback will be called when status of resource registration is changed.
 136  * @remarks The @a st_h should not be released.
 137  * @remarks The @a st_h is the same object for which the callback was set/added.
 138  * @remarks The @a st_h will be released when smartthings_resource_deinitialize() is called.
 139  * @remarks The @a is_registered will be true when resources are registered to cloud.
 140  *
 141  * @param[in] st_h The SmartThings resource handle
 142  * @param[in] is_registered The status of resource registration to cloud
 143  * @param[in] user_data The user data passed from the callback registration function
 144  *
 145  * @see smartthings_resource_set_cloud_registration_status_cb()
 146  * @see smartthings_resource_unset_cloud_registration_status_cb()
 147  */
 148 typedef void (*smartthings_resource_cloud_registration_status_cb)(smartthings_resource_h st_h, bool is_registered, void *user_data);
 149
 150
 151 /**
 152  * @brief Initializes a resource handle and connects to agent.
 153  * @since_ses 1
 154  * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
 155  *            %http://tizen.org/privilege/appmanager.launch \n
 156  *            %http://tizen.org/privilege/datasharing
 157  *
 158  * @remarks The @a st_h must be released using smartthings_resource_deinitialize().
 159  * @remarks Ths function returns #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED\n
 160  *          if the application has no app-defined privilege for 'http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource'.
 161  *
 162  * @param[out] st_h The SmartThings resource handle to be newly created on success
 163  * @param[in] connection_status_cb The connection status callback to register
 164  * @param[in] user_data The user data to be passed to the callback function
 165  *
 166  * @return @c 0 on success,
 167  *         otherwise a negative error value
 168  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 169  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 170  * @retval #SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY Out of memory
 171  * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
 172  * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
 173  * @retval #SMARTTHINGS_RESOURCE_ERROR_NOT_SUPPORTED Not supported
 174  * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
 175  *
 176  * @see smartthings_resource_deinitialize()
 177  */
 178 int smartthings_resource_initialize(smartthings_resource_h *st_h,
 179                                                                    smartthings_resource_connection_status_cb connection_status_cb,
 180                                                                    void *user_data);
 181
 182 /**
 183  * @brief Deinitializes a resource handle and disconnects from the agent.
 184  * @since_ses 1
 185  *
 186  * @param[in] st_h The SmartThings resource handle
 187  *
 188  * @return @c 0 on success,
 189  *         otherwise a negative error value
 190  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 191  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 192  *
 193  * @see smartthings_resource_initialize()
 194  */
 195 int smartthings_resource_deinitialize(smartthings_resource_h st_h);
 196
 197 /**
 198  * @brief Sets resource request callback.
 199  * @since_ses 1
 200  * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
 201  *            %http://tizen.org/privilege/appmanager.launch \n
 202  *            %http://tizen.org/privilege/datasharing
 203  *
 204  * @param[in] st_h The SmartThings resource handle
 205  * @param[in] req_cb The request callback to register
 206  * @param[in] user_data The user data to be passed to the callback function
 207  *
 208  * @return @c 0 on success,
 209  *         otherwise a negative error value
 210  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 211  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 212  * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
 213  * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
 214  * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
 215  *
 216  * @see smartthings_resource_unset_request_cb()
 217  */
 218 int smartthings_resource_set_request_cb(smartthings_resource_h st_h,
 219                                                                 smartthings_resource_request_cb req_cb,
 220                                                                 void *user_data);
 221
 222 /**
 223  * @brief Unsets resource request callback.
 224  * @since_ses 1
 225  * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
 226  *            %http://tizen.org/privilege/appmanager.launch \n
 227  *            %http://tizen.org/privilege/datasharing
 228  *
 229  * @param[in] st_h The SmartThings resource handle
 230  *
 231  * @return @c 0 on success,
 232  *         otherwise a negative error value
 233  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 234  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 235  * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
 236  * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
 237  * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
 238  *
 239  * @see smartthings_resource_set_request_cb()
 240  */
 241 int smartthings_resource_unset_request_cb(smartthings_resource_h st_h);
 242
 243 /**
 244  * @brief Sends response for resource request message.
 245  * @since_ses 1
 246  * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
 247  *            %http://tizen.org/privilege/appmanager.launch \n
 248  *            %http://tizen.org/privilege/datasharing \n
 249  *            %http://tizen.org/privilege/internet
 250  *
 251  * @param[in] st_h The SmartThings resource handle
 252  * @param[in] req_id The request ID of request message
 253  * @param[in] uri The resource URI
 254  * @param[in] payload The payload of response message
 255  * @param[in] result The result of response
 256  *
 257  * @return @c 0 on success,
 258  *         otherwise a negative error value
 259  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 260  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 261  * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
 262  * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
 263  * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
 264  */
 265 int smartthings_resource_send_response(smartthings_resource_h st_h, int req_id, const char *uri, smartthings_payload_h payload, bool result);
 266
 267 /**
 268  * @brief Notifies resource change.
 269  * @since_ses 1
 270  * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
 271  *            %http://tizen.org/privilege/appmanager.launch \n
 272  *            %http://tizen.org/privilege/datasharing \n
 273  *            %http://tizen.org/privilege/internet
 274  *
 275  * @param[in] st_h The SmartThings resource handle
 276  * @param[in] uri The resource URI
 277  * @param[in] payload The payload of response message
 278  *
 279  * @return @c 0 on success,
 280  *         otherwise a negative error value
 281  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 282  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 283  * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
 284  * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
 285  * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
 286  */
 287 int smartthings_resource_notify(smartthings_resource_h st_h, const char *uri, smartthings_payload_h payload);
 288
 289 /**
 290  * @brief Gets resource URIs.
 291  * @since_ses 1
 292  * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
 293  *            %http://tizen.org/privilege/appmanager.launch \n
 294  *            %http://tizen.org/privilege/datasharing
 295  *
 296  * @remarks The @a uris should be released using free().
 297  *
 298  * @param[in] st_h The SmartThings resource handle
 299  * @param[out] count The resource count
 300  * @param[out] uris The resource URI list
 301  *
 302  * @return @c 0 on success,
 303  *         otherwise a negative error value
 304  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 305  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 306  * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
 307  * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
 308  * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
 309  */
 310 int smartthings_resource_get_uris(smartthings_resource_h st_h, int *count, char ***uris);
 311
 312 /**
 313  * @brief Sets cloud registration callback.
 314  * @since_ses 1
 315  * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
 316  *            %http://tizen.org/privilege/appmanager.launch \n
 317  *            %http://tizen.org/privilege/datasharing
 318  *
 319  * @param[in] st_h The SmartThings resource handle
 320  * @param[in] reg_cb The callback to register
 321  * @param[in] user_data The user data to be passed to the callback function
 322  *
 323  * @return @c 0 on success,
 324  *         otherwise a negative error value
 325  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 326  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 327  * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
 328  * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
 329  * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
 330  *
 331  * @see smartthings_resource_unset_cloud_registration_status_cb()
 332  */
 333 int smartthings_resource_set_cloud_registration_status_cb(smartthings_resource_h st_h,
 334                                                                 smartthings_resource_cloud_registration_status_cb reg_cb,
 335                                                                 void *user_data);
 336
 337 /**
 338  * @brief Unsets cloud registration callback.
 339  * @since_ses 1
 340  * @privilege %http://com.samsung.tizen.smartthings-thing/appdefined/smartthings-thing.resource \n
 341  *            %http://tizen.org/privilege/appmanager.launch \n
 342  *            %http://tizen.org/privilege/datasharing
 343  *
 344  * @param[in] st_h The SmartThings resource handle
 345  *
 346  * @return @c 0 on success,
 347  *         otherwise a negative error value
 348  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 349  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 350  * @retval #SMARTTHINGS_RESOURCE_ERROR_PERMISSION_DENIED Permission denied
 351  * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
 352  * @retval #SMARTTHINGS_RESOURCE_ERROR_SERVICE_UNAVAILABLE Service unavailable
 353  *
 354  * @see smartthings_resource_set_cloud_registration_status_cb()
 355  */
 356 int smartthings_resource_unset_cloud_registration_status_cb(smartthings_resource_h st_h);
 357
 358
 359 /**
 360  * @}
 361  */
 362
 363 #ifdef __cplusplus
 364 }
 365 #endif
 366
 367 #endif /* __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_RESOURCE_H__ */