lib/include/iotcon-state.h

   1 /*
   2  * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
   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 #ifndef __IOT_CONNECTIVITY_MANAGER_STRUCT_STATE_H__
  17 #define __IOT_CONNECTIVITY_MANAGER_STRUCT_STATE_H__
  18
  19 #include <iotcon-types.h>
  20
  21 /**
  22  * @file iotcon-state.h
  23  */
  24
  25 /**
  26  * @ingroup CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_MODULE
  27  * @defgroup CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_STATE_MODULE State
  28  *
  29  * @brief Iotcon State provides API to manage state.
  30  *
  31  * @section CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_STATE_MODULE_HEADER Required Header
  32  *  \#include <iotcon.h>
  33  *
  34  * @section CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_STATE_MODULE_OVERVIEW Overview
  35  * The iotcon state API provides string key based hash table.
  36  *
  37  * Example :
  38  * @code
  39 #include <iotcon.h>
  40 ...
  41 static void _request_handler(iotcon_resource_h resource, iotcon_request_h request,
  42                 void *user_data)
  43 {
  44         int ret;
  45         int types;
  46
  47         ret = iotcon_request_get_types(request, &types);
  48         if (IOTCON_ERROR_NONE != ret)
  49                 return;
  50
  51         if (IOTCON_REQUEST_GET & types) {
  52                 iotcon_response_h response = NULL;
  53                 iotcon_representation_h representation = NULL;
  54                 iotcon_state_h state = NULL;
  55
  56                 ret = iotcon_response_create(request, &response);
  57                 if (IOTCON_ERROR_NONE != ret)
  58                         return;
  59
  60                 ret = iotcon_representation_create(&representation);
  61                 if (IOTCON_ERROR_NONE != ret) {
  62                         iotcon_response_destroy(resopnse);
  63                         return;
  64                 }
  65
  66                 ...
  67
  68                 ret = iotcon_state_create(&state);
  69                 if (IOTCON_ERROR_NONE != ret) {
  70                         iotcon_representation_destroy(representation);
  71                         iotcon_response_destroy(resopnse);
  72                         return;
  73                 }
  74
  75                 ret = iotcon_state_add_bool(state, "power", true);
  76                 if (IOTCON_ERROR_NONE != ret) {
  77                         iotcon_state_destroy(state);
  78                         iotcon_representation_destroy(representation);
  79                         iotcon_response_destroy(resopnse);
  80                         return;
  81                 }
  82
  83                 ret = itocon_state_set_int(state, "brightness", 75);
  84                 if (IOTCON_ERROR_NONE != ret) {
  85                         iotcon_state_destroy(state);
  86                         iotcon_representation_destroy(representation);
  87                         iotcon_response_destroy(resopnse);
  88                         return;
  89                 }
  90
  91                 ret = iotcon_representation_set_state(representation, state);
  92                 if (IOTCON_ERROR_NONE != ret) {
  93                         iotcon_state_destroy(state);
  94                         iotcon_representation_destroy(representation);
  95                         iotcon_response_destroy(resopnse);
  96                         return;
  97                 }
  98
  99                 ...
 100
 101                 ret = iotcon_response_set_representation(response, IOTCON_INTERFACE_DEFAULT,
 102                                 representation);
 103                 if (IOTCON_ERROR_NONE != ret) {
 104                         iotcon_state_destroy(state);
 105                         iotcon_representation_destroy(representation);
 106                         iotcon_response_destroy(resopnse);
 107                         return;
 108                 }
 109
 110                 ret = iotcon_response_send(response);
 111                 if (IOTCON_ERROR_NONE != ret) {
 112                         iotcon_state_destroy(state);
 113                         iotcon_representation_destroy(representation);
 114                         iotcon_response_destroy(resopnse);
 115                         return;
 116                 }
 117
 118                 iotcon_state_destroy(state);
 119                 iotcon_representation_destroy(representation);
 120                 iotcon_response_destroy(resopnse);
 121         }
 122         ...
 123 }
 124  * @endcode
 125  *
 126  * @{
 127  */
 128
 129 /**
 130  * @brief Creates a new state handle.
 131  *
 132  * @since_tizen 3.0
 133  *
 134  * @remarks You must destroy @a state by calling iotcon_state_destroy()
 135  * if @a state is no longer needed.
 136  *
 137  * @param[out] state A newly allocated state handle
 138  *
 139  * @return 0 on success, otherwise a negative error value.
 140  * @retval #IOTCON_ERROR_NONE  Successful
 141  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 142  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 143  *
 144  * @see iotcon_state_destroy()
 145  */
 146 int iotcon_state_create(iotcon_state_h *state);
 147
 148 /**
 149  * @brief Destroys a state.
 150  * @details Releases a @a state and its internal data.
 151  *
 152  * @since_tizen 3.0
 153  *
 154  * @param[in] state The state handle to free
 155  *
 156  * @return void
 157  *
 158  * @see iotcon_state_create()
 159  */
 160 void iotcon_state_destroy(iotcon_state_h state);
 161
 162 /**
 163  * @brief Clones a state handle.
 164  *
 165  * @since_tizen 3.0
 166  *
 167  * @remarks You must destroy @a state_clone by calling iotcon_state_destroy()
 168  * if @a state_clone is no longer needed.
 169  *
 170  * @param[in] state The state handle
 171  * @param[out] state_clone The cloned state handle
 172  *
 173  * @return 0 on success, otherwise a negative error value.
 174  * @retval #IOTCON_ERROR_NONE  Successful
 175  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 176  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 177  *
 178  * @see iotcon_state_create()
 179  * @see iotcon_state_destroy()
 180  */
 181 int iotcon_state_clone(iotcon_state_h state, iotcon_state_h *state_clone);
 182
 183 /**
 184  * @brief Adds a new key and integer value into the representation.
 185  * @details If @a key is already exists, current value will be replaced with new @a val.
 186  *
 187  * @since_tizen 3.0
 188  *
 189  * @param[in] state The state handle
 190  * @param[in] key The key
 191  * @param[in] val The value
 192  *
 193  * @return 0 on success, otherwise a negative error value.
 194  * @retval #IOTCON_ERROR_NONE  Successful
 195  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 196  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 197  */
 198 int iotcon_state_add_int(iotcon_state_h state, const char *key, int val);
 199
 200 /**
 201  * @brief Adds a new key and boolean value into the representation.
 202  * @details If @a key is already exists, current value will be replaced with new @a val.
 203  *
 204  * @since_tizen 3.0
 205  *
 206  * @param[in] state The state handle
 207  * @param[in] key The key
 208  * @param[in] val The value
 209  *
 210  * @return 0 on success, otherwise a negative error value.
 211  * @retval #IOTCON_ERROR_NONE  Successful
 212  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 213  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 214  */
 215 int iotcon_state_add_bool(iotcon_state_h state, const char *key, bool val);
 216
 217 /**
 218  * @brief Adds a new key and double value into the representation.
 219  * @details If @a key is already exists, current value will be replaced with new @a val.
 220  *
 221  * @since_tizen 3.0
 222  *
 223  * @param[in] state The state handle
 224  * @param[in] key The key
 225  * @param[in] val The value
 226  *
 227  * @return 0 on success, otherwise a negative error value.
 228  * @retval #IOTCON_ERROR_NONE  Successful
 229  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 230  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 231  */
 232 int iotcon_state_add_double(iotcon_state_h state, const char *key, double val);
 233
 234 /**
 235  * @brief Adds a new key and string value into the representation.
 236  * @details If @a key is already exists, current value will be replaced with new @a val.
 237  *
 238  * @since_tizen 3.0
 239  *
 240  * @param[in] state The state handle
 241  * @param[in] key The key
 242  * @param[in] val The value
 243  *
 244  * @return 0 on success, otherwise a negative error value.
 245  * @retval #IOTCON_ERROR_NONE  Successful
 246  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 247  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 248  */
 249 int iotcon_state_add_str(iotcon_state_h state, const char *key, char *val);
 250
 251 /**
 252  * @brief Adds a new key and list value into the representation.
 253  * @details If @a key is already exists, current list will be replaced with new @a list.
 254  *
 255  * @since_tizen 3.0
 256  *
 257  * @param[in] state The state handle
 258  * @param[in] key The key
 259  * @param[in] list The value
 260  *
 261  * @return 0 on success, otherwise a negative error value.
 262  * @retval #IOTCON_ERROR_NONE  Successful
 263  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 264  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 265  */
 266 int iotcon_state_add_list(iotcon_state_h state, const char *key, iotcon_list_h list);
 267
 268 /**
 269  * @brief Adds a new key and state value into the representation.
 270  * @details If @a key is already exists, current state will be replaced with new @a src.
 271  *
 272  * @since_tizen 3.0
 273  *
 274  * @param[in] dest The state handle
 275  * @param[in] key The key
 276  * @param[in] src The state handle to set newly
 277  *
 278  * @return 0 on success, otherwise a negative error value.
 279  * @retval #IOTCON_ERROR_NONE  Successful
 280  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 281  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 282  */
 283 int iotcon_state_add_state(iotcon_state_h dest, const char *key, iotcon_state_h src);
 284
 285 /**
 286  * @brief Adds a new key with NULL value into the representation.
 287  * @details If @a key is already exists, current value will be replaced with NULL
 288  *
 289  * @since_tizen 3.0
 290  *
 291  * @param[in] state The state handle
 292  * @param[in] key The key to be set NULL
 293  *
 294  * @return 0 on success, otherwise a negative error value.
 295  * @retval #IOTCON_ERROR_NONE  Successful
 296  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 297  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 298  */
 299 int iotcon_state_add_null(iotcon_state_h state, const char *key);
 300
 301 /**
 302  * @brief Gets the integer value from the given key.
 303  *
 304  * @since_tizen 3.0
 305  *
 306  * @param[in] state The state handle
 307  * @param[in] key The key
 308  * @param[out] val The integer value
 309  *
 310  * @return 0 on success, otherwise a negative error value.
 311  * @retval #IOTCON_ERROR_NONE  Successful
 312  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 313  * @retval #IOTCON_ERROR_NO_DATA  No data available
 314  * @retval #IOTCON_ERROR_INVALID_TYPE  Invalid type
 315  */
 316 int iotcon_state_get_int(iotcon_state_h state, const char *key, int *val);
 317
 318 /**
 319  * @brief Gets the boolean value from the given key.
 320  *
 321  * @since_tizen 3.0
 322  *
 323  * @param[in] state The state handle
 324  * @param[in] key The key
 325  * @param[out] val The boolean value
 326  *
 327  * @return 0 on success, otherwise a negative error value.
 328  * @retval #IOTCON_ERROR_NONE  Successful
 329  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 330  * @retval #IOTCON_ERROR_NO_DATA  No data available
 331  * @retval #IOTCON_ERROR_INVALID_TYPE  Invalid type
 332  */
 333 int iotcon_state_get_bool(iotcon_state_h state, const char *key, bool *val);
 334
 335 /**
 336  * @brief Gets the double value from the given key.
 337  *
 338  * @since_tizen 3.0
 339  *
 340  * @param[in] state The state handle
 341  * @param[in] key The key
 342  * @param[out] val The double value
 343  *
 344  * @return 0 on success, otherwise a negative error value.
 345  * @retval #IOTCON_ERROR_NONE  Successful
 346  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 347  * @retval #IOTCON_ERROR_NO_DATA  No data available
 348  * @retval #IOTCON_ERROR_INVALID_TYPE  Invalid type
 349  */
 350 int iotcon_state_get_double(iotcon_state_h state, const char *key, double *val);
 351
 352 /**
 353  * @brief Gets the string value from the given key.
 354  *
 355  * @since_tizen 3.0
 356  *
 357  * @remarks @a val must not be released using free().
 358  *
 359  * @param[in] state The state handle
 360  * @param[in] key The key
 361  * @param[out] val The string value
 362  *
 363  * @return 0 on success, otherwise a negative error value.
 364  * @retval #IOTCON_ERROR_NONE  Successful
 365  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 366  * @retval #IOTCON_ERROR_NO_DATA  No data available
 367  * @retval #IOTCON_ERROR_INVALID_TYPE  Invalid type
 368  */
 369 int iotcon_state_get_str(iotcon_state_h state, const char *key, char **val);
 370
 371 /**
 372  * @brief Gets the list value from the given key.
 373  *
 374  * @since_tizen 3.0
 375  *
 376  * @remarks @a list must not be released using iotcon_list_destroy().
 377  *
 378  * @param[in] state The state handle
 379  * @param[in] key The key
 380  * @param[out] list The list value
 381  *
 382  * @return 0 on success, otherwise a negative error value.
 383  * @retval #IOTCON_ERROR_NONE  Successful
 384  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 385  * @retval #IOTCON_ERROR_NO_DATA  No data available
 386  * @retval #IOTCON_ERROR_INVALID_TYPE  Invalid type
 387  */
 388 int iotcon_state_get_list(iotcon_state_h state, const char *key, iotcon_list_h *list);
 389
 390 /**
 391  * @brief Gets the state value from the given key.
 392  *
 393  * @since_tizen 3.0
 394  *
 395  * @remarks @a state must not be released using iotcon_state_destroy().
 396  *
 397  * @param[in] src The state handle
 398  * @param[in] key The key
 399  * @param[out] dest The state value at the key
 400  *
 401  * @return 0 on success, otherwise a negative error value.
 402  * @retval #IOTCON_ERROR_NONE  Successful
 403  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 404  * @retval #IOTCON_ERROR_NO_DATA  No data available
 405  * @retval #IOTCON_ERROR_INVALID_TYPE  Invalid type
 406  */
 407 int iotcon_state_get_state(iotcon_state_h src, const char *key, iotcon_state_h *dest);
 408
 409 /**
 410  * @brief Checks whether the value of given key is NULL or not.
 411  *
 412  * @since_tizen 3.0
 413  *
 414  * @param[in] state The state handle
 415  * @param[in] key The key
 416  * @param[out] is_null true if the type of the given key is null, otherwise false
 417  *
 418  * @return 0 on success, otherwise a negative error value.
 419  * @retval #IOTCON_ERROR_NONE  Successful
 420  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 421  */
 422 int iotcon_state_is_null(iotcon_state_h state, const char *key, bool *is_null);
 423
 424 /**
 425  * @brief Removes the key and its associated value from the state.
 426  *
 427  * @since_tizen 3.0
 428  *
 429  * @param[in] state The state handle
 430  * @param[in] key The key
 431  *
 432  * @return 0 on success, otherwise a negative error value.
 433  * @retval #IOTCON_ERROR_NONE  Successful
 434  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 435  * @retval #IOTCON_ERROR_NO_DATA  No data available
 436  */
 437 int iotcon_state_remove(iotcon_state_h state, const char *key);
 438
 439 /**
 440  * @brief Gets the type of a value at the given key.
 441  * @details It gets the data type of value related the @a key in @a state.
 442  * The data type could be one of #iotcon_type_e.
 443  *
 444  * @since_tizen 3.0
 445  *
 446  * @param[in] state The state handle
 447  * @param[in] key The key
 448  * @param[out] type The data type of value related the key in state handle.
 449  *
 450  * @return 0 on success, otherwise a negative error value.
 451  * @retval #IOTCON_ERROR_NONE  Successful
 452  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 453  * @retval #IOTCON_ERROR_NO_DATA  No data available
 454  */
 455 int iotcon_state_get_type(iotcon_state_h state, const char *key,
 456                 iotcon_type_e *type);
 457
 458 /**
 459  * @brief Specifies the type of function passed to iotcon_state_foreach()
 460  *
 461  * @since_tizen 3.0
 462  *
 463  * @param[in] state The state handle
 464  * @param[in] key The key
 465  * @param[in] user_data The user data to pass to the function
 466  *
 467  * @return true to continue with the next iteration of the loop,
 468  * otherwise false to break out of the loop. #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP
 469  * are more friendly values for the return.
 470  *
 471  * @pre iotcon_state_foreach() will invoke this callback function.
 472  *
 473  * @see iotcon_state_foreach()
 474  */
 475 typedef bool (*iotcon_state_cb)(iotcon_state_h state, const char *key, void *user_data);
 476
 477 /**
 478  * @brief Calls a function for each element of state.
 479  * @details iotcon_state_cb() will be called for each child.
 480  *
 481  * @since_tizen 3.0
 482  *
 483  * @param[in] state The state handle
 484  * @param[in] cb The callback function to invoke
 485  * @param[in] user_data The user data to pass to the function
 486  *
 487  * @return 0 on success, otherwise a negative error value.
 488  * @retval #IOTCON_ERROR_NONE  Successful
 489  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 490  *
 491  * @post iotcon_state_cb() will be called for each child.
 492  *
 493  * @see iotcon_state_cb()
 494  */
 495 int iotcon_state_foreach(iotcon_state_h state, iotcon_state_cb cb, void *user_data);
 496
 497 /**
 498  * @brief  Gets the number of keys in the state.
 499  *
 500  * @since_tizen 3.0
 501  *
 502  * @param[in] state The state handle
 503  * @param[out] count The number of keys
 504  *
 505  * @return 0 on success, otherwise a negative error value.
 506  * @retval #IOTCON_ERROR_NONE  Successful
 507  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 508  */
 509 int iotcon_state_get_keys_count(iotcon_state_h state, unsigned int *count);
 510
 511 /**
 512  * @}
 513  */
 514
 515 #endif /* __IOT_CONNECTIVITY_MANAGER_STRUCT_STATE_H__ */