2 * Copyright (c) 2000 - 2016 Samsung Electronics Co., Ltd. All rights reserved.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef __BUNDLE_INTERNAL_H__
18 #define __BUNDLE_INTERNAL_H__
21 * @file bundle_internal.h
22 * @brief This file declares has API of the bundle library
26 * @addtogroup CORE_LIB_BUNDLE_MODULE
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()
42 typedef void (*bundle_iterate_cb_t) (const char *key, const char *val, void *data);
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()
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
65 API int bundle_add(bundle *b, const char *key, const char *val);
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()
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"
87 bundle_free(b); // After freeing b, val becomes a dangling pointer.
91 API const char *bundle_get_val(bundle *b, const char *key);
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.
107 #include <bundle_internal.h>
108 void sample_cb(const char *k, const char *v, void *data) {
109 printf("%s -> %s\n", k, v);
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
122 API void bundle_iterate(bundle *b, bundle_iterate_cb_t callback, void *cb_data);
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()
137 API int bundle_keyval_type_is_measurable(bundle_keyval_t *kv);
140 * @brief Duplicate key-value pair.
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.
147 API bundle_keyval_t *bundle_keyval_dup(const bundle_keyval_t *kv);
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()
159 API int bundle_free_encoded_rawdata(bundle_raw **r);
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.
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
179 bundle_encode_raw(b, &r, &len); // encode b
184 API int bundle_encode_raw(bundle *b, bundle_raw **r, int *len);
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 b must be a valid bundle object.
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
202 bundle_raw *encoded_b;
204 bundle_encode(b, &encoded_b, &len); // encode b
207 b_dup = bundle_decode_raw(encoded_b, len); // decoded bundle object
214 API bundle *bundle_decode_raw(const bundle_raw *r, const int len);
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()
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
239 argc = bundle_export_to_argv(b, &argv); // export to argv
240 if(0 > argc) error("export failure");
243 for(i=0; i < argc; i++) {
244 printf("%s\n", argv[i]); // print argv
246 bundle_free_exported_argv(argc, argv); // argv must be freed after being used.
251 API int bundle_export_to_argv(bundle *b, char ***argv);
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()
265 bundle *b = bundle_create();
266 bundle_add_str(b, "foo", "bar");
270 argc = bundle_export_to_argv(b, &argv);
271 if(0 > argc) error("export failure");
275 bundle_free_exported_argv(argc, argv);
281 API int bundle_free_exported_argv(int argc, char ***argv);
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()
298 #include <bundle_internal.h>
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"
304 bundle_free(b); // After freeing b, val becomes a dangling pointer.
309 API bundle *bundle_import_from_argv(int argc, char **argv);
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()
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");
332 char **str_array = NULL;
333 int len_str_array = 0;
335 str_array=bundle_get_str_array(b, "foo", &len_str_array);
336 // str_array = { "aaa", "bbb", "ccc" }, and len_str_array = 3
341 API int bundle_set_str_array_element(bundle *b, const char *key, const unsigned int idx, const char *val);
344 * @brief Creates a json data from bundle.
346 * @remarks This API 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.
355 #include <bundle_internal.h>
356 bundle *b = bundle_create();
360 bundle_add_str(b, "foo", "bar");
361 ret = bundle_to_json(b, &json);
362 if (ret != BUNDLE_ERROR_NONE) {
366 // json = "{"foo":"bar"}"
371 API int bundle_to_json(bundle *b, char **json);
374 * @breif Creates a bundle object from json.
376 * @remarks This API 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
384 #include <bundle_internal.h>
386 char *json = "{"foo":"bar"}";
389 ret = bundle_from_json(json, &b);
390 if (ret != BUNDLE_ERROR_NONE)
395 API int bundle_from_json(const char *json, bundle **b);
398 * @breif Compares the bundle 1, 2.
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
407 API int bundle_compare(bundle *b1, bundle *b2);
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.
415 * @param[in] b The bundle object
416 * @param[in] key The key
417 * @param[in] len The length of the array to be created
418 * @return @c 0 on success,
419 * otherwise a negative error value
420 * @retval #BUNDLE_ERROR_NONE Successful
421 * @retval #BUNDLE_ERROR_INVALID_PARAMETEr Invalid parameter
422 * @retval #BUNDLE_ERROR_KEY_EXISTS Key already exists
423 * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
425 * @see bundle_set_byte_array_element()
427 API int bundle_init_byte_array(bundle *b, const char *key, const unsigned int len);
438 #endif /* __BUNDLE__INTERNAL_H__ */