inc/smartthings_payload.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_PAYLOAD_H__
  21 #define __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_PAYLOAD_H__
  22
  23 #include <stdio.h>
  24 #include <stdlib.h>
  25 #include <stdbool.h>
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 /**
  32  * @file smartthings_payload.h
  33  */
  34
  35 /**
  36  * @addtogroup CAPI_SMARTTHINGS_THING_PAYLOAD_MODULE
  37  * @{
  38  */
  39
  40 /**
  41  * @brief The SmartThings payload handle.
  42  * @since_ses 1
  43  */
  44 typedef struct smartthings_payload_s *smartthings_payload_h;
  45
  46 /**
  47  * @brief Creates a SmartThings payload handle.
  48  * @since_ses 1
  49  *
  50  * @remarks The @a payload must be released using smartthings_payload_destroy().
  51  * @remarks If the @a payload is set to parent payload as an object or object array
  52  *          using smartthings_payload_set_object() or smartthings_payload_set_object_array(),
  53  *          the @a payload must not be released.
  54
  55  * @param[out] payload The SmartThings payload handle to be newly created on success
  56  * @return @c 0 on success,
  57  *         otherwise a negative error value
  58  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
  59  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
  60  * @retval #SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY Out of memory
  61  *
  62  * @see smartthings_payload_destroy()
  63  */
  64 int smartthings_payload_create(smartthings_payload_h *payload);
  65
  66 /**
  67  * @brief Destroys a SmartThings payload handle and releases all its resources.
  68  * @since_ses 1
  69  *
  70  * @remarks If the @a payload has child payload, its child payload will be released as well.
  71  *
  72  * @param[in] payload The SmartThings payload handle
  73  *
  74  * @return @c 0 on success,
  75  *         otherwise a negative error value
  76  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
  77  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
  78  *
  79  * @see smartthings_payload_create()
  80  */
  81 int smartthings_payload_destroy(smartthings_payload_h payload);
  82
  83 /**
  84  * @brief Sets an integer value for the attribute name.
  85  * @since_ses 1
  86  *
  87  * @remarks The @a attr_name is key value, one of several properties of the resource type.
  88  * @remarks The function replaces any existing value for the given @a attr_name.
  89  *
  90  * @param[in] payload The SmartThings payload handle
  91  * @param[in] attr_name The attribute name
  92  * @param[in] value The value to set
  93  *
  94  * @return @c 0 on success,
  95  *         otherwise a negative error value
  96  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
  97  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
  98  */
  99 int smartthings_payload_set_int(smartthings_payload_h payload, const char *attr_name, int value);
 100
 101 /**
 102  * @brief Sets a boolean value for the attribute name.
 103  * @since_ses 1
 104  *
 105  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 106  * @remarks The function replaces any existing value for the given @a attr_name.
 107  *
 108  * @param[in] payload The SmartThings payload handle
 109  * @param[in] attr_name The attribute name
 110  * @param[in] value The value to set
 111  *
 112  * @return @c 0 on success,
 113  *         otherwise a negative error value
 114  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 115  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 116  */
 117 int smartthings_payload_set_bool(smartthings_payload_h payload, const char *attr_name, bool value);
 118
 119 /**
 120  * @brief Sets a double value for the attribute name.
 121  * @since_ses 1
 122  *
 123  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 124  * @remarks The function replaces any existing value for the given @a attr_name.
 125  *
 126  * @param[in] payload The SmartThings payload handle
 127  * @param[in] attr_name The attribute name
 128  * @param[in] value The value to set
 129  *
 130  * @return @c 0 on success,
 131  *         otherwise a negative error value
 132  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 133  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 134  */
 135 int smartthings_payload_set_double(smartthings_payload_h payload, const char *attr_name, double value);
 136
 137 /**
 138  * @brief Sets a string value for the attribute name.
 139  * @since_ses 1
 140  *
 141  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 142  * @remarks The function replaces any existing value for the given @a attr_name.
 143  *
 144  * @param[in] payload The SmartThings payload handle
 145  * @param[in] attr_name The attribute name
 146  * @param[in] value The value to set
 147  *
 148  * @return @c 0 on success,
 149  *         otherwise a negative error value
 150  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 151  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 152  */
 153 int smartthings_payload_set_string(smartthings_payload_h payload, const char *attr_name, const char *value);
 154
 155 /**
 156  * @brief Sets a byte string value and length for the attribute name.
 157  * @since_ses 1
 158  *
 159  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 160  * @remarks The function replaces any existing value for the given @a attr_name.
 161  *
 162  * @param[in] payload The SmartThings payload handle
 163  * @param[in] attr_name The attribute name
 164  * @param[in] value The value to set
 165  * @param[in] length The size of value
 166  *
 167  * @return @c 0 on success,
 168  *         otherwise a negative error value
 169  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 170  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 171  * @retval #SMARTTHINGS_RESOURCE_ERROR_OPERATION_FAILED Operation failed
 172  */
 173 int smartthings_payload_set_byte_string(smartthings_payload_h payload, const char *attr_name, const char *value, unsigned int length);
 174
 175 /**
 176  * @brief Sets an object value for the attribute name.
 177  * @since_ses 1
 178  *
 179  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 180  * @remarks The @a value is SmartThings payload handle.
 181  * @remarks The function replaces any existing value for the given @a attr_name.
 182  *
 183  * @param[in] payload The SmartThings payload handle
 184  * @param[in] attr_name The attribute name
 185  * @param[in] value The value to set
 186  *
 187  * @return @c 0 on success,
 188  *         otherwise a negative error value
 189  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 190  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 191  */
 192 int smartthings_payload_set_object(smartthings_payload_h payload, const char *attr_name, smartthings_payload_h value);
 193
 194 /**
 195  * @brief Sets an integer array for the attribute name.
 196  * @since_ses 1
 197  *
 198  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 199  * @remarks The function replaces any existing array for the given @a attr_name.
 200  *
 201  * @param[in] payload The SmartThings payload handle
 202  * @param[in] attr_name The attribute name
 203  * @param[in] array The array associated with the given attribute name
 204  * @param[in] length The length of @a array
 205  *
 206  * @return @c 0 on success,
 207  *         otherwise a negative error value
 208  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 209  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 210  */
 211 int smartthings_payload_set_int_array(smartthings_payload_h payload, const char *attr_name, const int *array, unsigned int length);
 212
 213 /**
 214  * @brief Sets a boolean array for the attribute name.
 215  * @since_ses 1
 216  *
 217  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 218  * @remarks The function replaces any existing array for the given @a attr_name.
 219  *
 220  * @param[in] payload The SmartThings payload handle
 221  * @param[in] attr_name The attribute name
 222  * @param[in] array The array associated with the given attribute name
 223  * @param[in] length The length of @a array
 224  *
 225  * @return @c 0 on success,
 226  *         otherwise a negative error value
 227  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 228  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 229  */
 230 int smartthings_payload_set_bool_array(smartthings_payload_h payload, const char *attr_name, const bool *array, unsigned int length);
 231
 232 /**
 233  * @brief Sets a double array for the attribute name.
 234  * @since_ses 1
 235  *
 236  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 237  * @remarks The function replaces any existing array for the given @a attr_name.
 238  *
 239  * @param[in] payload The SmartThings payload handle
 240  * @param[in] attr_name The attribute name
 241  * @param[in] array The array associated with the given attribute name
 242  * @param[in] length The length of @a array
 243  *
 244  * @return @c 0 on success,
 245  *         otherwise a negative error value
 246  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 247  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 248  */
 249 int smartthings_payload_set_double_array(smartthings_payload_h payload, const char *attr_name, const double *array, unsigned int length);
 250
 251 /**
 252  * @brief Sets a string array for the attribute name.
 253  * @since_ses 1
 254  *
 255  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 256  * @remarks The function replaces any existing array for the given @a attr_name.
 257  *
 258  * @param[in] payload The SmartThings payload handle
 259  * @param[in] attr_name The attribute name
 260  * @param[in] array The array associated with the given attribute name
 261  * @param[in] length The length of @a array
 262  *
 263  * @return @c 0 on success,
 264  *         otherwise a negative error value
 265  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 266  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 267  */
 268 int smartthings_payload_set_string_array(smartthings_payload_h payload, const char *attr_name, const char **array, unsigned int length);
 269
 270 /**
 271  * @brief Sets an object array for the attribute name.
 272  * @since_ses 1
 273  *
 274  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 275  * @remarks The function replaces any existing array for the given @a attr_name.
 276  *
 277  * @param[in] payload The SmartThings payload handle
 278  * @param[in] attr_name The attribute name
 279  * @param[in] array The array associated with the given attribute name
 280  * @param[in] length The length of @a array
 281  *
 282  * @return @c 0 on success,
 283  *         otherwise a negative error value
 284  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 285  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 286  * @retval #SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY Out of memory
 287  */
 288 int smartthings_payload_set_object_array(smartthings_payload_h payload, const char *attr_name, smartthings_payload_h *array, unsigned int length);
 289
 290 /**
 291  * @brief Adds a payload for child resource of collection resource.
 292  * @since_ses 1
 293  *
 294  * @remarks The @a resource_uri is key value, one of several child resources of the collection resource.
 295  * @remarks The @a value is SmartThings payload handle.
 296  * @remarks The function replaces any existing payload for the given @a resource_uri.
 297  *
 298  * @param[in] payload The SmartThings payload handle
 299  * @param[in] resource_uri The resource URI of child resource
 300  * @param[in] value The payload associated with the given resource URI
 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  */
 307 int smartthings_payload_add_collection_object(smartthings_payload_h payload, const char *resource_uri, smartthings_payload_h value);
 308
 309 /**
 310  * @brief Gets an integer value for the attribute name.
 311  * @since_ses 1
 312  *
 313  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 314  *
 315  * @param[in] payload The SmartThings payload handle
 316  * @param[in] attr_name The attribute name
 317  * @param[out] value The value associated with the given attribute name
 318  *
 319  * @return @c 0 on success,
 320  *         otherwise a negative error value
 321  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 322  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 323  * @retval #SMARTTHINGS_RESOURCE_ERROR_NO_DATA No data
 324  */
 325 int smartthings_payload_get_int(smartthings_payload_h payload, const char *attr_name, int *value);
 326
 327 /**
 328  * @brief Gets a boolean value for the attribute name.
 329  * @since_ses 1
 330  *
 331  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 332  *
 333  * @param[in] payload The SmartThings payload handle
 334  * @param[in] attr_name The attribute name
 335  * @param[out] value The value associated with the given attribute name
 336  *
 337  * @return @c 0 on success,
 338  *         otherwise a negative error value
 339  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 340  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 341  * @retval #SMARTTHINGS_RESOURCE_ERROR_NO_DATA No data
 342  */
 343 int smartthings_payload_get_bool(smartthings_payload_h payload, const char *attr_name, bool *value);
 344
 345 /**
 346  * @brief Gets a double value for the attribute name.
 347  * @since_ses 1
 348  *
 349  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 350  *
 351  * @param[in] payload The SmartThings payload handle
 352  * @param[in] attr_name The attribute name
 353  * @param[out] value The value associated with the given attribute name
 354  *
 355  * @return @c 0 on success,
 356  *         otherwise a negative error value
 357  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 358  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 359  * @retval #SMARTTHINGS_RESOURCE_ERROR_NO_DATA No data
 360  */
 361 int smartthings_payload_get_double(smartthings_payload_h payload, const char *attr_name, double *value);
 362
 363 /**
 364  * @brief Gets a string value for the attribute name.
 365  * @since_ses 1
 366  *
 367  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 368  * @remarks The @a value should be released using free().
 369  *
 370  * @param[in] payload The SmartThings payload handle
 371  * @param[in] attr_name The attribute name
 372  * @param[out] value The value associated with the given attribute name
 373  *
 374  * @return @c 0 on success,
 375  *         otherwise a negative error value
 376  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 377  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 378  * @retval #SMARTTHINGS_RESOURCE_ERROR_NO_DATA No data
 379  */
 380 int smartthings_payload_get_string(smartthings_payload_h payload, const char *attr_name, char **value);
 381
 382 /**
 383  * @brief Gets a byte string value and length for the attribute name.
 384  * @since_ses 1
 385  *
 386  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 387  * @remarks The @a value should be released using free().
 388  *
 389  * @param[in] payload The SmartThings payload handle
 390  * @param[in] attr_name The attribute name
 391  * @param[out] value The value associated with the given attribute name
 392  * @param[out] length The size of value
 393  *
 394  * @return @c 0 on success,
 395  *         otherwise a negative error value
 396  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 397  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 398  * @retval #SMARTTHINGS_RESOURCE_ERROR_NO_DATA No data
 399  */
 400 int smartthings_payload_get_byte_string(smartthings_payload_h payload, const char *attr_name, char **value, unsigned int *length);
 401
 402 /**
 403  * @brief Gets an object value for the attribute name.
 404  * @since_ses 1
 405  *
 406  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 407  * @remarks The @a value is SmartThings payload handle.
 408  * @remarks The @a value must be released using smartthings_payload_release_object().
 409  *
 410  * @param[in] payload The SmartThings payload handle
 411  * @param[in] attr_name The attribute name
 412  * @param[out] value The value associated with the given attribute name
 413  *
 414  * @return @c 0 on success,
 415  *         otherwise a negative error value
 416  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 417  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 418  * @retval #SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY Out of memory
 419  * @retval #SMARTTHINGS_RESOURCE_ERROR_NO_DATA No data
 420  */
 421 int smartthings_payload_get_object(smartthings_payload_h payload, const char *attr_name, smartthings_payload_h *value);
 422
 423 /**
 424  * @brief Gets an integer array for the attribute name.
 425  * @since_ses 1
 426  *
 427  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 428  * @remarks The @a array must be released using smartthings_payload_release_int_array().
 429  *
 430  * @param[in] payload The SmartThings payload handle
 431  * @param[in] attr_name The attribute name
 432  * @param[out] array The array associated with the given attribute name
 433  * @param[out] length The length of @a array
 434  *
 435  * @return @c 0 on success,
 436  *         otherwise a negative error value
 437  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 438  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 439  * @retval #SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY Out of memory
 440  * @retval #SMARTTHINGS_RESOURCE_ERROR_NO_DATA No data
 441  *
 442  * @see smartthings_payload_release_int_array()
 443  */
 444 int smartthings_payload_get_int_array(smartthings_payload_h payload, const char *attr_name, int **array, unsigned int *length);
 445
 446 /**
 447  * @brief Gets a boolean array for the attribute name.
 448  * @since_ses 1
 449  *
 450  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 451  * @remarks The @a array must be released using smartthings_payload_release_bool_array().
 452  *
 453  * @param[in] payload The SmartThings payload handle
 454  * @param[in] attr_name The attribute name
 455  * @param[out] array The array associated with the given attribute name
 456  * @param[out] length The length of @a array
 457  *
 458  * @return @c 0 on success,
 459  *         otherwise a negative error value
 460  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 461  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 462  * @retval #SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY Out of memory
 463  * @retval #SMARTTHINGS_RESOURCE_ERROR_NO_DATA No data
 464  *
 465  * @see smartthings_payload_release_bool_array()
 466  */
 467 int smartthings_payload_get_bool_array(smartthings_payload_h payload, const char *attr_name, bool **array, unsigned int *length);
 468
 469 /**
 470  * @brief Gets a double array for the attribute name.
 471  * @since_ses 1
 472  *
 473  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 474  * @remarks The @a array must be released using smartthings_payload_release_double_array().
 475  *
 476  * @param[in] payload The SmartThings payload handle
 477  * @param[in] attr_name The attribute name
 478  * @param[out] array The array associated with the given attribute name
 479  * @param[out] length The length of @a array
 480  *
 481  * @return @c 0 on success,
 482  *         otherwise a negative error value
 483  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 484  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 485  * @retval #SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY Out of memory
 486  * @retval #SMARTTHINGS_RESOURCE_ERROR_NO_DATA No data
 487  *
 488  * @see smartthings_payload_release_double_array()
 489  */
 490 int smartthings_payload_get_double_array(smartthings_payload_h payload, const char *attr_name, double **array, unsigned int *length);
 491
 492 /**
 493  * @brief Gets a string array for the attribute name.
 494  * @since_ses 1
 495  *
 496  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 497  * @remarks The @a array must be released using smartthings_payload_release_string_array().
 498  *
 499  * @param[in] payload The SmartThings payload handle
 500  * @param[in] attr_name The attribute name
 501  * @param[out] array The array associated with the given attribute name
 502  * @param[out] length The length of @a array
 503  *
 504  * @return @c 0 on success,
 505  *         otherwise a negative error value
 506  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 507  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 508  * @retval #SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY Out of memory
 509  * @retval #SMARTTHINGS_RESOURCE_ERROR_NO_DATA No data
 510  *
 511  * @see smartthings_payload_release_string_array()
 512  */
 513 int smartthings_payload_get_string_array(smartthings_payload_h payload, const char *attr_name, char ***array, unsigned int *length);
 514
 515 /**
 516  * @brief Gets an object array for the attribute name.
 517  * @since_ses 1
 518  *
 519  * @remarks The @a attr_name is key value, one of several properties of the resource type.
 520  * @remarks The @a array is a list of SmartThings payload handle.
 521  * @remarks The @a array must be released using smartthings_payload_release_object_array().
 522  *
 523  * @param[in] payload The SmartThings payload handle
 524  * @param[in] attr_name The attribute name
 525  * @param[out] array The array associated with the given attribute name
 526  * @param[out] length The length of @a array
 527  *
 528  * @return @c 0 on success,
 529  *         otherwise a negative error value
 530  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 531  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 532  * @retval #SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY Out of memory
 533  * @retval #SMARTTHINGS_RESOURCE_ERROR_NO_DATA No data
 534  *
 535  * @see smartthings_payload_release_object_array()
 536  */
 537 int smartthings_payload_get_object_array(smartthings_payload_h payload, const char *attr_name, smartthings_payload_h **array, unsigned int *length);
 538
 539 /**
 540  * @brief Gets a payload for child resource of collection resource.
 541  * @since_ses 1
 542  *
 543  * @remarks The @a resource_uri is key value, one of several child resources of the collection resource.
 544  * @remarks The @a value is SmartThings payload handle.
 545  * @remarks The @a value must be released using smartthings_payload_release_object().
 546  *
 547  * @param[in] payload The SmartThings payload handle
 548  * @param[in] resource_uri The resource URI of child resource
 549  * @param[out] value The payload associated with the given resource URI
 550  *
 551  * @return @c 0 on success,
 552  *         otherwise a negative error value
 553  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 554  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 555  * @retval #SMARTTHINGS_RESOURCE_ERROR_OUT_OF_MEMORY Out of memory
 556  * @retval #SMARTTHINGS_RESOURCE_ERROR_NO_DATA No data
 557  */
 558 int smartthings_payload_get_collection_object(smartthings_payload_h payload, const char *resource_uri, smartthings_payload_h *value);
 559
 560 /**
 561  * @brief Releases an integer array of the SmartThings payload.
 562  * @since_ses 1
 563  *
 564  * @param[in] array The array to release
 565  *
 566  * @return @c 0 on success,
 567  *         otherwise a negative error value
 568  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 569  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 570  *
 571  * @see smartthings_payload_get_int_array()
 572  */
 573 int smartthings_payload_release_int_array(int *array);
 574
 575 /**
 576  * @brief Releases a boolean array of the SmartThings payload.
 577  * @since_ses 1
 578  *
 579  * @param[in] array The array to release
 580  *
 581  * @return @c 0 on success,
 582  *         otherwise a negative error value
 583  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 584  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 585  *
 586  * @see smartthings_payload_get_bool_array()
 587  */
 588 int smartthings_payload_release_bool_array(bool *array);
 589
 590 /**
 591  * @brief Releases a double array of the SmartThings payload.
 592  * @since_ses 1
 593  *
 594  * @param[in] array The array to release
 595  *
 596  * @return @c 0 on success,
 597  *         otherwise a negative error value
 598  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 599  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 600  *
 601  * @see smartthings_payload_get_double_array()
 602  */
 603 int smartthings_payload_release_double_array(double *array);
 604
 605 /**
 606  * @brief Releases a string array of the SmartThings payload.
 607  * @since_ses 1
 608  *
 609  * @param[in] array The array to release
 610  * @param[in] length The length of @a array
 611  *
 612  * @return @c 0 on success,
 613  *         otherwise a negative error value
 614  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 615  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 616  *
 617  * @see smartthings_payload_get_string_array()
 618  */
 619 int smartthings_payload_release_string_array(char **array, unsigned int length);
 620
 621 /**
 622  * @brief Releases an object array of the SmartThings payload.
 623  * @since_ses 1
 624  *
 625  * @param[in] array The array to release
 626  * @param[in] length The length of @a array
 627  *
 628  * @return @c 0 on success,
 629  *         otherwise a negative error value
 630  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 631  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 632  *
 633  * @see smartthings_payload_get_object_array()
 634  */
 635 int smartthings_payload_release_object_array(smartthings_payload_h *array, unsigned int length);
 636
 637 /**
 638  * @brief Releases a SmartThings payload.
 639  * @since_ses 1
 640  *
 641  * @remarks The function is different with smartthings_payload_destroy().
 642  * @remarks The function releases only payload value that is obtained by smartthings_payload_get_object().
 643  *
 644  * @param[in] payload The payload to release
 645  *
 646  * @return @c 0 on success,
 647  *         otherwise a negative error value
 648  * @retval #SMARTTHINGS_RESOURCE_ERROR_NONE Successful
 649  * @retval #SMARTTHINGS_RESOURCE_ERROR_INVALID_PARAMETER Invalid parameter
 650  *
 651  * @see smartthings_payload_get_object()
 652  */
 653 int smartthings_payload_release_object(smartthings_payload_h payload);
 654
 655 /**
 656  * @}
 657  */
 658
 659 #ifdef __cplusplus
 660 }
 661 #endif
 662
 663 #endif /* __SAMSUNG_EXPERIENCE_SERVICE_SMARTTHINGS_PAYLOAD_H__ */