include/bundle_internal.h

   1 /*
   2  * Copyright (c) 2000 - 2020 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
  17 #ifndef __BUNDLE_INTERNAL_H__
  18 #define __BUNDLE_INTERNAL_H__
  19
  20 /**
  21  * @file bundle_internal.h
  22  * @brief    This file declares has API of the bundle library
  23  */
  24
  25 /**
  26  * @addtogroup CORE_LIB_BUNDLE_MODULE
  27  * @{
  28  */
  29
  30 #include <bundle.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 # endif
  35
  36 /**
  37  * @brief Called for every key-value pair.
  38  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  39  * @remarks This type is obsolete. You must not use this type any more.
  40  * @see bundle_iterate()
  41  */
  42 typedef void (*bundle_iterate_cb_t) (const char *key, const char *val, void *data);
  43
  44 /**
  45  * @brief Adds a string type key-value pair into a given bundle.
  46  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  47  * @param[in] b The bundle object
  48  * @param[in] key The key
  49  * @param[in] val The value
  50  * @return The operation result
  51  * @retval #BUNDLE_ERROR_NONE Success
  52  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
  53  * @retval #BUNDLE_ERROR_KEY_EXISTS Key already exists
  54  * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
  55  * @pre @a b must be a valid bundle object.
  56  * @see bundle_add_str()
  57  @code
  58  #include <bundle_internal.h>
  59  bundle *b = bundle_create(); // Create new bundle object
  60  bundle_add(b, "foo_key", "bar_val"); // add a key-val pair
  61
  62  bundle_free(b);
  63  @endcode
  64  */
  65 int bundle_add(bundle *b, const char *key, const char *val);
  66
  67 /**
  68  * @brief Gets a value with a given key.
  69  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  70  * @remarks You MUST NOT free or modify the returned string!
  71  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
  72  * @param[in] b The bundle object
  73  * @param[in] key The key
  74  * @return The pointer for the value string
  75  * @retval @c NULL - Key not found
  76  * @exception #BUNDLE_ERROR_NONE Success
  77  * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
  78  * @exception #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
  79  * @pre @a b must be a valid bundle object.
  80  * @see bundle_get_str()
  81  @code
  82  #include <bundle_internal.h>
  83  bundle *b = bundle_create(); // Create new bundle object
  84  bundle_add_str(b, "foo", "bar"); //add a key-val pair
  85  char *val = bundle_get_val(b, "foo_key");      // val = "bar_val"
  86
  87  bundle_free(b);        // After freeing b, val becomes a dangling pointer.
  88  val = NULL;
  89  @endcode
  90  */
  91 const char *bundle_get_val(bundle *b, const char *key);
  92
  93 /**
  94  * @brief Iterates a callback function for each key-value pairs in a given bundle.
  95  * @details (NOTE: Only BUNDLE_TYPE_STR type values come!)
  96  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  97  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
  98  * @remarks This function is obsolete and does not give values whose types are not BUNDLE_TYPE_STR.
  99  * @param[in] b The bundle object
 100  * @param[in] callback The iteration callback function
 101  * @param[in] cb_data The data for callback function
 102  * @exception #BUNDLE_ERROR_NONE Success
 103  * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 104  * @pre @a b must be a valid bundle object.
 105  @code
 106  #include <stdio.h>
 107  #include <bundle_internal.h>
 108  void sample_cb(const char *k, const char *v, void *data) {
 109    printf("%s -> %s\n", k, v);
 110  }
 111
 112  int main(void) {
 113          bundle *b = bundle_create(); // Create new bundle object
 114          bundle_add_str(b, "k1", "v1"); // add a key-val pair
 115          bundle_add_str(b, "k2", "v2"); // add a key-val pair
 116          bundle_add_str(b, "k3", "v3"); // add a key-val pair
 117          bundle_iterate(b, sample_cb, NULL); // iterate sample_cb() for each key/val
 118          return 0;
 119  }
 120  @endcode
 121  */
 122 void bundle_iterate(bundle *b, bundle_iterate_cb_t callback, void *cb_data);
 123
 124 /**
 125  * @brief Determines whether the type of a key-value pair is measurable.
 126  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 127  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 128  * @param[in] kv A bundle_keyval_t object
 129  * @return The operation result
 130  * @retval @c 1 - @a kv is an measurable
 131  * @retval @c 0 - @a kv is not an measurable
 132  * @exception #BUNDLE_ERROR_NONE Success
 133  * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 134  * @pre @a kv must be a valid bundle_keyval_t object.
 135  * @see bundle_foreach()
 136  */
 137 int bundle_keyval_type_is_measurable(bundle_keyval_t *kv);
 138
 139 /**
 140  * @brief Duplicates key-value pair.
 141  * @since_tizen 5.5
 142  * @param[in] kv A bundle_keyval_t object
 143  * @return The bundle object
 144  * @retval @c NULL - Failure
 145  * @pre @a kv must be a valid bundle_keyval_t object.
 146  */
 147 bundle_keyval_t *bundle_keyval_dup(const bundle_keyval_t *kv);
 148
 149 /**
 150  * @brief Frees the encoded rawdata.
 151  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 152  * @param[in] r The rawdata
 153  * @return The operation result
 154  * @retval #BUNDLE_ERROR_NONE Success
 155  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 156  * @pre @a r is a valid rawdata generated by bundle_encode().
 157  * @see bundle_encode()
 158  */
 159 int bundle_free_encoded_rawdata(bundle_raw **r);
 160
 161 /**
 162  * @brief Encodes a bundle to the bundle_raw format.
 163  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 164  * @param[in] b The bundle object
 165  * @param[out] r The returned bundle_raw data(byte data)
 166  *               @a r MUST BE FREED by free(r)
 167  * @param[out] len The size of @a r (in bytes)
 168  * @return The size of the raw data
 169  * @retval #BUNDLE_ERROR_NONE Success
 170  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 171  * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
 172  * @pre @a b must be a valid bundle object.
 173  @code
 174  #include <bundle_internal.h>
 175  bundle *b = bundle_create(); // Create new bundle object
 176  bundle_add_str(b, "foo_key", "bar_val"); // add a key-val pair
 177  bundle_raw *r;
 178  int len;
 179  bundle_encode_raw(b, &r, &len);        // encode b
 180
 181  bundle_free(b);
 182  @endcode
 183  */
 184 int bundle_encode_raw(bundle *b, bundle_raw **r, int *len);
 185
 186 /**
 187  * @brief Deserializes bundle_raw and gets a bundle object.
 188  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 189  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 190  * @param[in] r The bundle_raw data to be converted to a bundle object
 191  * @param[in] len The size of @a r
 192  * @return The bundle object
 193  * @retval @c NULL - Failure
 194  * @exception #BUNDLE_ERROR_NONE Success
 195  * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 196  * @pre @a r must be a valid bundle object.
 197  @code
 198  #include <bundle_internal.h>
 199  bundle *b = bundle_create(); // Create new bundle object
 200  bundle_add_str(b, "foo_key", "bar_val"); // add a key-val pair
 201
 202  bundle_raw *encoded_b;
 203  int len;
 204  bundle_encode(b, &encoded_b, &len);    // encode b
 205
 206  bundle *b_dup;
 207  b_dup = bundle_decode_raw(encoded_b, len);     // decoded bundle object
 208
 209  bundle_free(b);
 210  free(encoded_b);
 211  bundle_free(b_dup);
 212  @endcode
 213  */
 214 bundle *bundle_decode_raw(const bundle_raw *r, const int len);
 215
 216 /**
 217  * @brief Exports bundle to @a argv.
 218  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 219  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 220  * @param[in] b The bundle object
 221  * @param[out] argv The pointer of the string array; \n
 222  *                  This array has NULL values for the first and last item; \n
 223  *                  First NULL is for argv[0], and last NULL is a terminator for execv() \n
 224  * @return The number of item in @a argv. This value is equal to the actual count of argv - 1. (Last NULL terminator is not counted.)
 225  * @retval @c -1 - Failure
 226  * @exception #BUNDLE_ERROR_NONE Success
 227  * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 228  * @exception #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
 229  * @pre @a b is a valid bundle object.
 230  * @post @a argv is a pointer of newly allocated memory. It must be freed.
 231  * @see bundle_import_from_argv()
 232  @code
 233  #include <bundle_internal.h>
 234  bundle *b = bundle_create(); // Create new bundle object
 235  bundle_add_str(b, "foo_key", "bar_val"); // add a key-val pair
 236
 237  int argc = 0;
 238  char **argv = NULL;
 239  argc = bundle_export_to_argv(b, &argv);        // export to argv
 240  if(0 > argc) error("export failure");
 241
 242  int i;
 243  for(i=0; i < argc; i++) {
 244    printf("%s\n", argv[i]);             // print argv
 245  }
 246  bundle_free_exported_argv(argc, argv); // argv must be freed after being used.
 247
 248  bundle_free(b);
 249  @endcode
 250  */
 251 int bundle_export_to_argv(bundle *b, char ***argv);
 252
 253 /**
 254  * @brief Frees the exported @a argv.
 255  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 256  * @remarks You must not use this API when you use global @a argv.
 257  * @param[in] argc The number of args, which is the return value of bundle_export_to_argv()
 258  * @param[in] argv The array from bundle_export_to_argv()
 259  * @return The operation result
 260  * @retval #BUNDLE_ERROR_NONE Success
 261  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 262  * @pre @a argv is a valid string array generated from bundle_export_to_argv().
 263  * @see bundle_export_to_argv()
 264  @code
 265  bundle *b = bundle_create();
 266  bundle_add_str(b, "foo", "bar");
 267
 268  int argc = 0;
 269  char **argv = NULL;
 270  argc = bundle_export_to_argv(b, &argv);
 271  if(0 > argc) error("export failure");
 272
 273  // Use argv...
 274
 275  bundle_free_exported_argv(argc, argv);
 276  argv = NULL;
 277
 278  bundle_free(b);
 279  @endcode
 280  */
 281 int bundle_free_exported_argv(int argc, char ***argv);
 282
 283 /**
 284  * @brief Imports a bundle from @a argv.
 285  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 286  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 287  * @param[in] argc The argument count
 288  * @param[in] argv The argument vector
 289  * @return The new bundle object
 290  * @retval @c NULL - Failure
 291  * @exception #BUNDLE_ERROR_NONE Success
 292  * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 293  * @exception #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
 294  * @pre @a argv is a valid string array, which is created by bundle_export_to_argv().
 295  * @post The returned bundle @a b must be freed.
 296  * @see bundle_export_to_argv()
 297  @code
 298  #include <bundle_internal.h>
 299
 300  int main(int argc, char **argv) {
 301    bundle *b = bundle_import_from_argv(argc, argv); // import from argc+argv
 302    char *val = bundle_get_val(b, "foo_key");    // value for "foo_key"
 303    // ......
 304    bundle_free(b);      // After freeing b, val becomes a dangling pointer.
 305    val = NULL;
 306  }
 307  @endcode
 308  */
 309 bundle *bundle_import_from_argv(int argc, char **argv);
 310
 311 /**
 312  * @brief Sets a value of string array elements.
 313  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 314  * @param[in] b The bundle object
 315  * @param[in] key The key
 316  * @param[in] idx The index of the array element to be changed
 317  * @param[in] val The string type value; if @c NULL, an empty array is created; you can change an item with
 318  * @return The operation result
 319  * @retval #BUNDLE_ERROR_NONE Success
 320  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 321  * @pre @a b must be a valid bundle object.
 322  * @see bundle_add_str_array()
 323  * @see bundle_get_str_array()
 324  @code
 325  #include <bundle_internal.h>
 326  bundle *b = bundle_create();
 327  bundle_add_str_array(b, "foo", NULL, 3); // add a key-val pair
 328  bundle_set_str_array_element(b, "foo", 0, "aaa");
 329  bundle_set_str_array_element(b, "foo", 1, "bbb");
 330  bundle_set_str_array_element(b, "foo", 2, "ccc");
 331
 332  char **str_array = NULL;
 333  int len_str_array = 0;
 334
 335  str_array=bundle_get_str_array(b, "foo", &len_str_array);
 336  // str_array = { "aaa", "bbb", "ccc" }, and len_str_array = 3
 337
 338  bundle_free(b);
 339  @endcode
 340  */
 341 int bundle_set_str_array_element(bundle *b, const char *key, const unsigned int idx, const char *val);
 342
 343 /**
 344  * @brief Creates a JSON data from bundle.
 345  * @since_tizen 3.0
 346  * @remarks This function only supports the string type and the string array type.
 347  * @param[in] b The bundle object
 348  * @param[out] json The new created json data
 349  * @return The operation result
 350  * @retval #BUNDLE_ERROR_NONE Success
 351  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 352  * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
 353  * @pre @a b must be a valid bundle object.
 354  @code
 355  #include <bundle_internal.h>
 356  bundle *b = bundle_create();
 357  char *json;
 358  int ret;
 359
 360  bundle_add_str(b, "foo", "bar");
 361  ret = bundle_to_json(b, &json);
 362  if (ret != BUNDLE_ERROR_NONE) {
 363  bundle_free(b);
 364  return;
 365  }
 366  // json = "{"foo":"bar"}"
 367  bundle_free(b);
 368  free(json);
 369  @endcode
 370  */
 371 int bundle_to_json(bundle *b, char **json);
 372
 373 /**
 374  * @breif Creates a bundle object from json.
 375  * @since_tizen 3.0
 376  * @remarks This function only supports the string type and the string array type.
 377  * @param[in] json The json data
 378  * @param[out] b The bundle object
 379  * @return The operation result
 380  * @retval #BUNDLE_ERROR_NONE Success
 381  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 382  * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
 383  @code
 384  #include <bundle_internal.h>
 385  bundle *b;
 386  char *json = "{"foo":"bar"}";
 387  int ret;
 388
 389  ret =  bundle_from_json(json, &b);
 390  if (ret != BUNDLE_ERROR_NONE)
 391  return;
 392  bundle_free(b);
 393  @endcode
 394  */
 395 int bundle_from_json(const char *json, bundle **b);
 396
 397 /**
 398  * @breif Compares the bundle 1, 2.
 399  * @since_tizen 3.0
 400  * @param[in] b1 The bundle object
 401  * @param[in] b2 The bundle object
 402  * @return The operation result
 403  * @retval @c 0 It is identical
 404  * @retval @c -1 Invalid parameter
 405  * @retval @c 1 It is not identical
 406  */
 407 int bundle_compare(bundle *b1, bundle *b2);
 408
 409 /**
 410  * @brief Initializes a byte array type key-value pair into a bundle.
 411  * @details To set the value of the byte array element, you should use bundle_set_byte_array_element().
 412  *          This function is only for creating a buffer of the byte array.
 413  * @since_tizen 5.5
 414  * @param[in] b The bundle object
 415  * @param[in] key The key
 416  * @param[in] len The length of the array to be created
 417  * @return @c 0 on success,
 418  *         otherwise a negative error value
 419  * @retval #BUNDLE_ERROR_NONE Successful
 420  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 421  * @retval #BUNDLE_ERROR_KEY_EXISTS Key already exists
 422  * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
 423  *
 424  * @see bundle_set_byte_array_element()
 425  */
 426 int bundle_init_byte_array(bundle *b, const char *key, const unsigned int len);
 427
 428 /**
 429  * @brief Frees the given key-value pair.
 430  * @since_tizen 6.0
 431  * @param[in] kv The key-value pair
 432  * @return @c 0 on success,
 433  *         otherwise a negative error value
 434  * @retval #BUNDLE_ERROR_NONE Successful
 435  * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 436  */
 437 int bundle_keyval_free(bundle_keyval_t *kv);
 438
 439 #ifdef __cplusplus
 440 }
 441 #endif
 442
 443 /**
 444  * @}
 445  * @}
 446  */
 447
 448 #endif  /* __BUNDLE__INTERNAL_H__ */