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