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