Asterisk - The Open Source Telephony Project GIT-master-3dae2cf
json.h
Go to the documentation of this file.
1/*
2 * Asterisk -- An open source telephony toolkit.
3 *
4 * Copyright (C) 2012 - 2013, Digium, Inc.
5 *
6 * David M. Lee, II <dlee@digium.com>
7 *
8 * See http://www.asterisk.org for more information about
9 * the Asterisk project. Please do not directly contact
10 * any of the maintainers of this project for assistance;
11 * the project provides a web site, mailing lists and IRC
12 * channels for your use.
13 *
14 * This program is free software, distributed under the terms of
15 * the GNU General Public License Version 2. See the LICENSE file
16 * at the top of the source tree.
17 */
18
19#ifndef _ASTERISK_JSON_H
20#define _ASTERISK_JSON_H
21
22#include "asterisk/netsock2.h"
23
24/*! \file
25 *
26 * \brief Asterisk JSON abstraction layer.
27 * \since 12.0.0
28 *
29 * This is a very thin wrapper around the Jansson API. For more details on it,
30 * see its docs at http://www.digip.org/jansson/doc/2.11/apiref.html.
31 *
32 * Rather than provide the multiple ways of doing things that the Jansson API
33 * does, the Asterisk wrapper is always reference-stealing, and always NULL
34 * safe.
35 *
36 * And by always, I mean that the reference is stolen even if the function
37 * fails. This avoids lots of conditional logic, and also avoids having to track
38 * zillions of local variables when building complex JSON objects. You can
39 * instead chain \c ast_json_* calls together safely and only worry about
40 * cleaning up the root object.
41 *
42 * In the cases where you have a need to introduce intermediate objects, just
43 * wrap them with json_ref() when passing them to other \c ast_json_*()
44 * functions.
45 *
46 * \par Example code
47 *
48 * \code
49 * // Example of how to use the Asterisk JSON API
50 * static struct ast_json *foo(void) {
51 * RAII_VAR(struct ast_json *, array, NULL, ast_json_unref);
52 * RAII_VAR(struct ast_json *, obj, NULL, ast_json_unref);
53 * int i, res;
54 *
55 * array = ast_json_array_create();
56 * if (!array) { return NULL; }
57 *
58 * for (i = 0; i < 10; ++i) {
59 * // NULL safety and object stealing means calls can
60 * // be chained together directly.
61 * res = ast_json_array_append(array,
62 * ast_json_integer_create(i));
63 * if (res != 0) { return NULL; }
64 * }
65 *
66 * obj = ast_json_object_create();
67 * if (!obj) { return NULL; }
68 *
69 * // If you already have an object reference, ast_json_ref()
70 * // can be used inline to bump the ref before passing it along
71 * // to a ref-stealing call
72 * res = ast_json_object_set(obj, "foo", ast_json_ref(array));
73 * if (!res) { return NULL; }
74 *
75 * return obj;
76 * }
77 * \endcode
78 *
79 * \author David M. Lee, II <dlee@digium.com>
80 */
81
82/*!@{*/
83
84/*!
85 * \brief Primarily used to cast when packing to an "I" type.
86 */
88
89/*!
90 * \brief Initialize the JSON library.
91 */
92int ast_json_init(void);
93
94/*!
95 * \brief Set custom allocators instead of the standard ast_malloc() and ast_free().
96 * \since 12.0.0
97 *
98 * This is used by the unit tests to do JSON specific memory leak detection. Since it
99 * affects all users of the JSON library, shouldn't normally be used.
100 *
101 * \param malloc_fn Custom allocation function.
102 * \param free_fn Matching free function.
103 */
104void ast_json_set_alloc_funcs(void *(*malloc_fn)(size_t), void (*free_fn)(void*));
105
106/*!
107 * \brief Change alloc funcs back to the resource module defaults.
108 * \since 12.0.0
109 *
110 * If you use ast_json_set_alloc_funcs() to temporarily change the allocator functions
111 * (i.e., from in a unit test), this function sets them back to ast_malloc() and
112 * ast_free().
113 */
115
116/*!
117 * \brief Asterisk's custom JSON allocator. Exposed for use by unit tests.
118 * \since 12.0.0
119 * \internal
120 */
121void *ast_json_malloc(size_t size);
122
123/*!
124 * \brief Asterisk's custom JSON allocator. Exposed for use by unit tests.
125 * \since 12.0.0
126 * \internal
127 */
128void ast_json_free(void *p);
129
130/*!
131 * \struct ast_json
132 * \brief Abstract JSON element (object, array, string, int, ...).
133 * \since 12.0.0
134 */
135struct ast_json;
136
137/*!
138 * \brief Increase refcount on \a value.
139 * \since 12.0.0
140 *
141 * \param value JSON value to reference.
142 * \return The given \a value.
143 */
144struct ast_json *ast_json_ref(struct ast_json *value);
145
146/*!
147 * \brief Decrease refcount on \a value. If refcount reaches zero, \a value is freed.
148 * \since 12.0.0
149 *
150 * \note It is safe to pass \c NULL to this function.
151 */
152void ast_json_unref(struct ast_json *value);
153
154/*!@}*/
155
156/*!@{*/
157
158/*!
159 * \brief Valid types of a JSON element.
160 * \since 12.0.0
161 */
163{
172};
173
174/*!
175 * \brief Get the type of \a value.
176 * \since 12.0.0
177 * \param value Value to query.
178 * \return Type of \a value.
179 */
180enum ast_json_type ast_json_typeof(const struct ast_json *value);
181
182/*!
183 * \brief Get the string name for the given type.
184 * \since 12.0.0
185 * \param type Type to convert to string.
186 * \return Simple string for the type name (object, array, string, etc.)
187 * \retval "?" for invalid types.
188 */
189const char *ast_json_typename(enum ast_json_type type);
190
191/*!@}*/
192
193/*!@{*/
194
195/*!
196 * \brief Check the string of the given length for UTF-8 format.
197 * \since 13.12.0
198 *
199 * \param str String to check.
200 * \param len Length of string to check.
201 *
202 * \retval 0 if not UTF-8 encoded or str is NULL.
203 * \retval 1 if UTF-8 encoded.
204 */
205int ast_json_utf8_check_len(const char *str, size_t len);
206
207/*!
208 * \brief Check the nul terminated string for UTF-8 format.
209 * \since 13.12.0
210 *
211 * \param str String to check.
212 *
213 * \retval 0 if not UTF-8 encoded or str is NULL.
214 * \retval 1 if UTF-8 encoded.
215 */
216int ast_json_utf8_check(const char *str);
217
218/*!
219 * \brief Check str for UTF-8 and replace with an empty string if fails the check.
220 *
221 * \note The convenience macro is normally used with ast_json_pack()
222 * or a function wrapper that calls ast_json_vpack().
223 */
224#define AST_JSON_UTF8_VALIDATE(str) (ast_json_utf8_check(str) ? (str) : "")
225
226/*!@}*/
227
228/*!@{*/
229
230/*!
231 * \brief Get the JSON true value.
232 * \since 12.0.0
233 *
234 * The returned value is a singleton, and does not need to be
235 * ast_json_unref()'ed.
236 *
237 * \return JSON true.
238 */
239struct ast_json *ast_json_true(void);
240
241/*!
242 * \brief Get the JSON false value.
243 * \since 12.0.0
244 *
245 * The returned value is a singleton, and does not need to be
246 * ast_json_unref()'ed.
247 *
248 * \return JSON false.
249 */
250struct ast_json *ast_json_false(void);
251
252/*!
253 * \brief Get the JSON boolean corresponding to \a value.
254 * \since 12.0.0
255 * \return JSON true if value is true (non-zero).
256 * \return JSON false if value is false (zero).
257 */
258struct ast_json *ast_json_boolean(int value);
259
260/*!
261 * \brief Get the JSON null value.
262 * \since 12.0.0
263 *
264 * The returned value is a singleton, and does not need to be
265 * ast_json_unref()'ed.
266 *
267 * \return JSON null.
268 */
269struct ast_json *ast_json_null(void);
270
271/*!
272 * \brief Check if \a value is JSON array.
273 * \since 12.0.0
274 * \retval True (non-zero) if \a value == \ref ast_json_array().
275 * \retval False (zero) otherwise..
276 */
277int ast_json_is_array(const struct ast_json *value);
278
279/*!
280 * \brief Check if \a value is JSON object.
281 * \since 12.0.0
282 * \retval True (non-zero) if \a value == \ref ast_json_object().
283 * \retval False (zero) otherwise..
284 */
285int ast_json_is_object(const struct ast_json *value);
286
287/*!
288 * \brief Check if \a value is JSON true.
289 * \since 12.0.0
290 * \retval True (non-zero) if \a value == \ref ast_json_true().
291 * \retval False (zero) otherwise..
292 */
293int ast_json_is_true(const struct ast_json *value);
294
295/*!
296 * \brief Check if \a value is JSON false.
297 * \since 12.0.0
298 * \retval True (non-zero) if \a value == \ref ast_json_false().
299 * \retval False (zero) otherwise.
300 */
301int ast_json_is_false(const struct ast_json *value);
302
303/*!
304 * \brief Check if \a value is JSON null.
305 * \since 12.0.0
306 * \retval True (non-zero) if \a value == \ref ast_json_false().
307 * \retval False (zero) otherwise.
308 */
309int ast_json_is_null(const struct ast_json *value);
310
311/*!@}*/
312
313/*!@{*/
314
315/*!
316 * \brief Construct a JSON string from \a value.
317 * \since 12.0.0
318 *
319 * The given \a value must be a valid ASCII or UTF-8 encoded string.
320 *
321 * \param value Value of new JSON string.
322 * \return Newly constructed string element.
323 * \retval NULL on error.
324 */
325struct ast_json *ast_json_string_create(const char *value);
326
327/*!
328 * \brief Get the value of a JSON string.
329 * \since 12.0.0
330 * \param string JSON string.
331 * \return Value of the string.
332 * \retval NULL on error.
333 */
334const char *ast_json_string_get(const struct ast_json *string);
335
336/*!
337 * \brief Change the value of a JSON string.
338 * \since 12.0.0
339 *
340 * The given \a value must be a valid ASCII or UTF-8 encoded string.
341 *
342 * \param string JSON string to modify.
343 * \param value New value to store in \a string.
344 * \retval 0 on success.
345 * \retval -1 on error.
346 */
347int ast_json_string_set(struct ast_json *string, const char *value);
348
349/*!
350 * \brief Create a JSON string, printf style.
351 * \since 12.0.0
352 *
353 * The formatted value must be a valid ASCII or UTF-8 encoded string.
354 *
355 * \param format \c printf style format string.
356 * \return Newly allocated string.
357 * \retval NULL on error.
358 */
359struct ast_json *ast_json_stringf(const char *format, ...) __attribute__((format(printf, 1, 2)));
360
361/*!
362 * \brief Create a JSON string, vprintf style.
363 * \since 12.0.0
364 *
365 * The formatted value must be a valid ASCII or UTF-8 encoded string.
366 *
367 * \param format \c printf style format string.
368 * \param args
369 *
370 * \return Newly allocated string.
371 * \retval NULL on error.
372 */
373struct ast_json *ast_json_vstringf(const char *format, va_list args) __attribute__((format(printf, 1, 0)));
374
375/*!@}*/
376
377/*!@{*/
378
379/*!
380 * \brief Create a JSON integer.
381 * \since 12.0.0
382 * \param value Value of the new JSON integer.
383 * \return Newly allocated integer.
384 * \retval NULL on error.
385 */
386struct ast_json *ast_json_integer_create(intmax_t value);
387
388/*!
389 * \brief Get the value from a JSON integer.
390 * \since 12.0.0
391 * \param integer JSON integer.
392 * \return Value of a JSON integer.
393 * \retval 0 if \a integer is not a JSON integer.
394 */
395intmax_t ast_json_integer_get(const struct ast_json *integer);
396
397/*!
398 * \brief Set the value of a JSON integer.
399 * \since 12.0.0
400 * \param integer JSON integer to modify.
401 * \param value New value for \a integer.
402 * \retval 0 on success.
403 * \retval -1 on error.
404 */
405int ast_json_integer_set(struct ast_json *integer, intmax_t value);
406
407/*!
408 * \brief Create a JSON real number.
409 * \since 12.0.0
410 * \param value Value of the new JSON real number.
411 * \return Newly allocated real number.
412 * \retval NULL on error.
413 */
414struct ast_json *ast_json_real_create(double value);
415
416/*!
417 * \brief Get the value from a JSON real number.
418 * \since 12.0.0
419 * \param real JSON real number.
420 * \return Value of a JSON real number.
421 * \retval 0 if \a real is not a JSON real number.
422 */
423double ast_json_real_get(const struct ast_json *real);
424
425/*!
426 * \brief Set the value of a JSON real number.
427 * \since 12.0.0
428 * \param real JSON real number to modify.
429 * \param value New value for \a real.
430 * \retval 0 on success.
431 * \retval -1 on error.
432 */
433int ast_json_real_set(struct ast_json *real, double value);
434
435/*!@}*/
436
437/*!@{*/
438
439/*!
440 * \brief Create a empty JSON array.
441 * \since 12.0.0
442 * \return Newly allocated array.
443 * \retval NULL on error.
444 */
445struct ast_json *ast_json_array_create(void);
446
447/*!
448 * \brief Get the size of a JSON array.
449 * \since 12.0.0
450 * \param array JSON array.
451 * \return Size of \a array.
452 * \retval 0 if array is not a JSON array.
453 */
454size_t ast_json_array_size(const struct ast_json *array);
455
456/*!
457 * \brief Get an element from an array.
458 * \since 12.0.0
459 *
460 * The returned element is a borrowed reference; use ast_json_ref() to safely keep a
461 * pointer to it.
462 *
463 * \param array JSON array.
464 * \param index Zero-based index into \a array.
465 * \return The specified element.
466 * \retval NULL if \a array not an array.
467 * if \a index is out of bounds.
468 */
469struct ast_json *ast_json_array_get(const struct ast_json *array, size_t index);
470
471/*!
472 * \brief Change an element in an array.
473 * \since 12.0.0
474 *
475 * \note The \a array steals the \a value reference even if it returns error;
476 * use ast_json_ref() to safely keep a pointer to it.
477 *
478 * \param array JSON array to modify.
479 * \param index Zero-based index into array.
480 * \param value New JSON value to store in \a array at \a index.
481 * \retval 0 on success.
482 * \retval -1 on error.
483 */
484int ast_json_array_set(struct ast_json *array, size_t index, struct ast_json *value);
485
486/*!
487 * \brief Append to an array.
488 * \since 12.0.0
489 *
490 * \note The \a array steals the \a value reference even if it returns error;
491 * use ast_json_ref() to safely keep a pointer to it.
492 *
493 * \param array JSON array to modify.
494 * \param value New JSON value to store at the end of \a array.
495 * \retval 0 on success.
496 * \retval -1 on error.
497 */
499
500/*!
501 * \brief Insert into an array.
502 * \since 12.0.0
503 *
504 * \note The \a array steals the \a value reference even if it returns error;
505 * use ast_json_ref() to safely keep a pointer to it.
506 *
507 * \param array JSON array to modify.
508 * \param index Zero-based index into array.
509 * \param value New JSON value to store in \a array at \a index.
510 * \retval 0 on success.
511 * \retval -1 on error.
512 */
513int ast_json_array_insert(struct ast_json *array, size_t index, struct ast_json *value);
514
515/*!
516 * \brief Remove an element from an array.
517 * \since 12.0.0
518 * \param array JSON array to modify.
519 * \param index Zero-based index into array.
520 * \retval 0 on success.
521 * \retval -1 on error.
522 */
523int ast_json_array_remove(struct ast_json *array, size_t index);
524
525/*!
526 * \brief Remove all elements from an array.
527 * \since 12.0.0
528 * \param array JSON array to clear.
529 * \retval 0 on success.
530 * \retval -1 on error.
531 */
533
534/*!
535 * \brief Append all elements from \a tail to \a array.
536 * \since 12.0.0
537 *
538 * The \a tail argument is not changed, so ast_json_unref() it when you are done with it.
539 *
540 * \param array JSON array to modify.
541 * \param tail JSON array with contents to append to \a array.
542 * \retval 0 on success.
543 * \retval -1 on error.
544 */
545int ast_json_array_extend(struct ast_json *array, struct ast_json *tail);
546
547/*!@}*/
548
549/*!@{*/
550
551/*!
552 * \brief Create a new JSON object.
553 * \since 12.0.0
554 * \return Newly allocated object.
555 * \retval NULL on error.
556 */
557struct ast_json *ast_json_object_create(void);
558
559/*!
560 * \brief Create a new JSON object using the given variables
561 * \param variables A list of Asterisk variables
562 * \param excludes Comma separated string of variable names to exclude (optional)
563 * \return Newly allocated object.
564 * \retval NULL on error.
565 */
566struct ast_json *ast_json_object_create_vars(const struct ast_variable *variables, const char *excludes);
567
568/*!
569 * \brief Get size of JSON object.
570 * \since 12.0.0
571 * \param object JSON object.
572 * \return Size of \a object.
573 * \retval Zero of \a object is not a JSON object.
574 */
575size_t ast_json_object_size(struct ast_json *object);
576
577/*!
578 * \brief Get a field from a JSON object.
579 * \since 12.0.0
580 *
581 * The returned element is a borrowed reference; use ast_json_ref() to safely keep a
582 * pointer to it.
583 *
584 * \param object JSON object.
585 * \param key Key of field to look up.
586 * \return Value with given \a key.
587 * \retval NULL on error.
588 */
589struct ast_json *ast_json_object_get(struct ast_json *object, const char *key);
590
591/*!
592 * \brief Get a string field from a JSON object.
593 * \since 16.3.0
594 *
595 * \param object JSON object.
596 * \param key Key of string field to look up.
597 * \return String value of given \a key.
598 * \retval NULL on error, or key value is not a string.
599 */
600#define ast_json_object_string_get(object, key) ast_json_string_get(ast_json_object_get(object, key))
601
602/*!
603 * \brief Get an integer field from a JSON object.
604 * \param object JSON object.
605 * \param key Key of integer field to look up.
606 * \return Value of a JSON integer.
607 * \retval 0 if \a integer is not a JSON integer.
608 */
609#define ast_json_object_integer_get(object, key) ast_json_integer_get(ast_json_object_get(object, key))
610
611/*!
612 * \brief Get a double field from a JSON object.
613 * \param object JSON object.
614 * \param key Key of double field to look up.
615 * \return Value of a JSON double.
616 * \retval 0 if \a real is not a JSON real number.
617 */
618#define ast_json_object_real_get(object, key) ast_json_real_get(ast_json_object_get(object, key))
619
620/*!
621 * \brief Set a field in a JSON object.
622 * \since 12.0.0
623 *
624 * \note The object steals the \a value reference even if it returns error;
625 * use ast_json_ref() to safely keep a pointer to it.
626 *
627 * \param object JSON object to modify.
628 * \param key Key of field to set.
629 * \param value JSON value to set for field.
630 * \retval 0 on success.
631 * \retval -1 on error.
632 */
633int ast_json_object_set(struct ast_json *object, const char *key, struct ast_json *value);
634
635/*!
636 * \brief Delete a field from a JSON object.
637 * \since 12.0.0
638 *
639 * \param object JSON object to modify.
640 * \param key Key of field to delete.
641 * \retval 0 on success, or -1 if key does not exist.
642 */
643int ast_json_object_del(struct ast_json *object, const char *key);
644
645/*!
646 * \brief Delete all elements from a JSON object.
647 * \since 12.0.0
648 * \param object JSON object to clear.
649 * \retval 0 on success.
650 * \retval -1 on error.
651 */
652int ast_json_object_clear(struct ast_json *object);
653
654/*!
655 * \brief Update \a object with all of the fields of \a other.
656 * \since 12.0.0
657 *
658 * All of the fields of \a other are copied into \a object, overwriting existing keys.
659 * The \a other object is not changed, so ast_json_unref() it when you are done with it.
660 *
661 * \param object JSON object to modify.
662 * \param other JSON object to copy into \a object.
663 * \retval 0 on success.
664 * \retval -1 on error.
665 */
666int ast_json_object_update(struct ast_json *object, struct ast_json *other);
667
668/*!
669 * \brief Update existing fields in \a object with the fields of \a other.
670 * \since 12.0.0
671 *
672 * Like ast_json_object_update(), but only existing fields are updated. No new fields
673 * will get added. The \a other object is not changed, so ast_json_unref() it when you
674 * are done with it.
675 *
676 * \param object JSON object to modify.
677 * \param other JSON object to copy into \a object.
678 * \retval 0 on success.
679 * \retval -1 on error.
680 */
681int ast_json_object_update_existing(struct ast_json *object, struct ast_json *other);
682
683/*!
684 * \brief Add new fields to \a object with the fields of \a other.
685 * \since 12.0.0
686 *
687 * Like ast_json_object_update(), but only missing fields are added. No existing fields
688 * will be modified. The \a other object is not changed, so ast_json_unref() it when you
689 * are done with it.
690 *
691 * \param object JSON object to modify.
692 * \param other JSON object to copy into \a object.
693 * \retval 0 on success.
694 * \retval -1 on error.
695 */
696int ast_json_object_update_missing(struct ast_json *object, struct ast_json *other);
697
698/*!
699 * \struct ast_json_iter
700 * \brief Iterator for JSON object key/values.
701 * \since 12.0.0
702 *
703 * Note that iteration order is not specified, and may change as fields are added to
704 * and removed from the object.
705 */
706struct ast_json_iter;
707
708/*!
709 * \brief Get an iterator pointing to the first field in a JSON object.
710 * \since 12.0.0
711 *
712 * The order of the fields in an object are not specified. However, iterating forward
713 * from this iterator will cover all fields in \a object. Adding or removing fields from
714 * \a object may invalidate its iterators.
715 *
716 * \param object JSON object.
717 * \return Iterator to the first field in \a object.
718 * \retval NULL \a object is empty.
719 * on error.
720 */
721struct ast_json_iter *ast_json_object_iter(struct ast_json *object);
722
723/*!
724 * \brief Get an iterator pointing to a specified \a key in \a object.
725 * \since 12.0.0
726 *
727 * Iterating forward from this iterator may not to cover all elements in \a object.
728 *
729 * \param object JSON object to iterate.
730 * \param key Key of field to lookup.
731 * \return Iterator pointing to the field with the given \a key.
732 * \retval NULL if \a key does not exist.
733 * on error.
734 */
735struct ast_json_iter *ast_json_object_iter_at(struct ast_json *object, const char *key);
736
737/*!
738 * \brief Get the next iterator.
739 * \since 12.0.0
740 * \param object JSON object \a iter was obtained from.
741 * \param iter JSON object iterator.
742 * \return Iterator to next field in \a object.
743 * \retval NULL if \a iter was the last field.
744 */
745struct ast_json_iter *ast_json_object_iter_next(struct ast_json *object, struct ast_json_iter *iter);
746
747/*!
748 * \brief Get the key from an iterator.
749 * \since 12.0.0
750 * \param iter JSON object iterator.
751 * \return Key of the field \a iter points to.
752 */
753const char *ast_json_object_iter_key(struct ast_json_iter *iter);
754
755/*!
756 * \brief Get the value from an iterator.
757 * \since 12.0.0
758 *
759 * The returned element is a borrowed reference; use ast_json_ref() to safely
760 * keep a pointer to it.
761 *
762 * \param iter JSON object iterator.
763 * \return Value of the field \a iter points to.
764 */
766
767/*!
768 * \brief Set the value of the field pointed to by an iterator.
769 * \since 12.0.0
770 *
771 * \note The object steals the \p value reference even if it returns error;
772 * use ast_json_ref() to safely keep a pointer to it.
773 *
774 * \param object JSON object \p iter was obtained from.
775 * \param iter JSON object iterator.
776 * \param value JSON value to store in \p iter's field.
777 * \retval 0 on success.
778 * \retval -1 on error.
779 */
780int ast_json_object_iter_set(struct ast_json *object, struct ast_json_iter *iter, struct ast_json *value);
781
782/*!@}*/
783
784/*!@{*/
785
786/*!
787 * \brief Encoding format type.
788 * \since 12.0.0
789 */
791{
792 /*! Compact format, low human readability */
794 /*! Formatted for human readability */
796 /*! Keys sorted alphabetically */
798};
799
800/*!
801 * \brief Encode a JSON value to a compact string.
802 * \since 12.0.0
803 *
804 * Returned string must be freed by calling ast_json_free().
805 *
806 * \param root JSON value.
807 * \return String encoding of \a root.
808 * \retval NULL on error.
809 */
810#define ast_json_dump_string(root) ast_json_dump_string_format(root, AST_JSON_COMPACT)
811
812/*!
813 * \brief Encode a JSON value to a string.
814 * \since 12.0.0
815 *
816 * Returned string must be freed by calling ast_json_free().
817 *
818 * \param root JSON value.
819 * \param format encoding format type.
820 * \return String encoding of \a root.
821 * \retval NULL on error.
822 */
823char *ast_json_dump_string_format(struct ast_json *root, enum ast_json_encoding_format format);
824
825/*!
826 * \brief Encode a JSON value to a string, with its keys sorted.
827 *
828 * Returned string must be freed by calling ast_json_free().
829 *
830 * \param root JSON value.
831 * \return String encoding of \a root.
832 * \retval NULL on error.
833 */
834#define ast_json_dump_string_sorted(root) ast_json_dump_string_format(root, AST_JSON_SORTED)
835
836#define ast_json_dump_str(root, dst) ast_json_dump_str_format(root, dst, AST_JSON_COMPACT)
837
838/*!
839 * \brief Encode a JSON value to an \ref ast_str.
840 * \since 12.0.0
841 *
842 * If \a dst is too small, it will be grown as needed.
843 *
844 * \param root JSON value.
845 * \param dst \ref ast_str to store JSON encoding.
846 * \param format encoding format type.
847 * \retval 0 on success.
848 * \retval -1 on error. The contents of \a dst are undefined.
849 */
850int ast_json_dump_str_format(struct ast_json *root, struct ast_str **dst, enum ast_json_encoding_format format);
851
852#define ast_json_dump_file(root, output) ast_json_dump_file_format(root, output, AST_JSON_COMPACT)
853
854/*!
855 * \brief Encode a JSON value to a \c FILE.
856 * \since 12.0.0
857 *
858 * \param root JSON value.
859 * \param output File to write JSON encoding to.
860 * \param format encoding format type.
861 * \retval 0 on success.
862 * \retval -1 on error. The contents of \a output are undefined.
863 */
864int ast_json_dump_file_format(struct ast_json *root, FILE *output, enum ast_json_encoding_format format);
865
866#define ast_json_dump_new_file(root, path) ast_json_dump_new_file_format(root, path, AST_JSON_COMPACT)
867
868/*!
869 * \brief Encode a JSON value to a file at the given location.
870 * \since 12.0.0
871 *
872 * \param root JSON value.
873 * \param path Path to file to write JSON encoding to.
874 * \param format encoding format type.
875 * \retval 0 on success.
876 * \retval -1 on error. The contents of \a output are undefined.
877 */
878int ast_json_dump_new_file_format(struct ast_json *root, const char *path, enum ast_json_encoding_format format);
879
880#define AST_JSON_ERROR_TEXT_LENGTH 160
881#define AST_JSON_ERROR_SOURCE_LENGTH 80
882
883/*!
884 * \brief JSON parsing error information.
885 * \since 12.0.0
886 */
888 /*! Line number error occured on */
889 int line;
890 /*! Character (not byte, can be different for UTF-8) column on which the error occurred. */
892 /*! Position in bytes from start of input */
894 /*! Error message */
896 /*! Source of the error (filename or <string>) */
898};
899
900/*!
901 * \brief Parse null terminated string into a JSON object or array.
902 * \since 12.0.0
903 * \param input String to parse.
904 * \param[out] error Filled with information on error.
905 * \return Parsed JSON element.
906 * \retval NULL on error.
907 */
908struct ast_json *ast_json_load_string(const char *input, struct ast_json_error *error);
909
910/*!
911 * \brief Parse \ref ast_str into a JSON object or array.
912 * \since 12.0.0
913 * \param input \ref ast_str to parse.
914 * \param[out] error Filled with information on error.
915 * \return Parsed JSON element.
916 * \retval NULL on error.
917 */
918struct ast_json *ast_json_load_str(const struct ast_str *input, struct ast_json_error *error);
919
920/*!
921 * \brief Parse buffer with known length into a JSON object or array.
922 * \since 12.0.0
923 * \param buffer Buffer to parse.
924 * \param buflen Length of \a buffer.
925 * \param[out] error Filled with information on error.
926 * \return Parsed JSON element.
927 * \retval NULL on error.
928 */
929struct ast_json *ast_json_load_buf(const char *buffer, size_t buflen, struct ast_json_error *error);
930
931/*!
932 * \brief Parse a \c FILE into JSON object or array.
933 * \since 12.0.0
934 * \param input \c FILE to parse.
935 * \param[out] error Filled with information on error.
936 * \return Parsed JSON element.
937 * \retval NULL on error.
938 */
940
941/*!
942 * \brief Parse file at \a path into JSON object or array.
943 * \since 12.0.0
944 * \param path Path of file to parse.
945 * \param[out] error Filled with information on error.
946 * \return Parsed JSON element.
947 * \retval NULL on error.
948 */
949struct ast_json *ast_json_load_new_file(const char *path, struct ast_json_error *error);
950
951/*!
952 * \brief Helper for creating complex JSON values.
953 * \since 12.0.0
954 *
955 * See original Jansson docs at http://www.digip.org/jansson/doc/2.11/apiref.html#apiref-pack
956 * for more details.
957 */
958struct ast_json *ast_json_pack(char const *format, ...);
959
960/*!
961 * \brief Helper for creating complex JSON values simply.
962 * \since 12.0.0
963 *
964 * See original Jansson docs at http://www.digip.org/jansson/doc/2.11/apiref.html#apiref-pack
965 * for more details.
966 */
967struct ast_json *ast_json_vpack(char const *format, va_list ap);
968
969/*!@}*/
970
971/*!@{*/
972
973/*!
974 * \brief Compare two JSON objects.
975 * \since 12.0.0
976 *
977 * Two JSON objects are equal if they are of the same type, and their contents are equal.
978 *
979 * \param lhs Value to compare.
980 * \param rhs Other value to compare.
981 * \retval True (non-zero) if \a lhs and \a rhs are equal.
982 * \retval False (zero) if they are not.
983 */
984int ast_json_equal(const struct ast_json *lhs, const struct ast_json *rhs);
985
986/*!
987 * \brief Copy a JSON value, but not its children.
988 * \since 12.0.0
989 *
990 * If \a value is a JSON object or array, its children are shared with the returned copy.
991 *
992 * \param value JSON value to copy.
993 * \return Shallow copy of \a value.
994 * \retval NULL on error.
995 */
996struct ast_json *ast_json_copy(const struct ast_json *value);
997
998/*!
999 * \brief Copy a JSON value, and its children.
1000 * \since 12.0.0
1001 *
1002 * If \a value is a JSON object or array, they are also copied.
1003 *
1004 * \param value JSON value to copy.
1005 * \return Deep copy of \a value.
1006 * \retval NULL on error.
1007 */
1008struct ast_json *ast_json_deep_copy(const struct ast_json *value);
1009
1010/*!@}*/
1011
1012/*!@{*/
1013
1014/*!
1015 * \brief Common JSON rendering functions for common 'objects'.
1016 */
1017
1018/*!
1019 * \brief Simple name/number pair.
1020 * \param name Name
1021 * \param number Number
1022 * \return JSON object with name and number fields
1023 * \retval NULL on error (non-UTF8 characters, NULL inputs, etc.)
1024 */
1025struct ast_json *ast_json_name_number(const char *name, const char *number);
1026
1027/*!
1028 * \brief Construct a timeval as JSON.
1029 *
1030 * JSON does not define a standard date format (boo), but the de facto standard
1031 * is to use ISO 8601 formatted string. We build a millisecond resolution string
1032 * from the \c timeval
1033 *
1034 * \param tv \c timeval to encode.
1035 * \param zone Text string of a standard system zoneinfo file. If NULL, the system localtime will be used.
1036 * \return JSON string with ISO 8601 formatted date/time.
1037 * \retval NULL on error.
1038 */
1039struct ast_json *ast_json_timeval(const struct timeval tv, const char *zone);
1040
1041/*!
1042 * \brief Construct an IP address as JSON
1043 *
1044 * XXX some comments describing the need for this here
1045 *
1046 * \param addr ast_sockaddr to encode
1047 * \param transport_type ast_transport to include in the address string if any. Should just be one.
1048 * \return JSON string containing the IP address with optional transport information
1049 * \retval NULL on error.
1050 */
1051struct ast_json *ast_json_ipaddr(const struct ast_sockaddr *addr, enum ast_transport transport_type);
1052
1053/*!
1054 * \brief Construct a context/exten/priority/application/application_data as JSON.
1055 *
1056 * If a \c NULL is passed for \c context or \c exten or \c app_name or \c app_data,
1057 * or -1 for \c priority, the fields is set to ast_json_null().
1058 *
1059 * \param context Context name.
1060 * \param exten Extension.
1061 * \param priority Dialplan priority.
1062 * \param app_name Application name.
1063 * \param app_data Application argument.
1064 * \return JSON object with \c context, \c exten and \c priority \c app_name \c app_data fields
1065 */
1067 const char *context, const char *exten, int priority, const char *app_name, const char *app_data);
1068
1069/*!
1070 * \brief Construct a context/exten/priority as JSON.
1071 *
1072 * If a \c NULL is passed for \c context or \c exten, or -1 for \c priority,
1073 * the fields is set to ast_json_null().
1074 *
1075 * \param context Context name.
1076 * \param exten Extension.
1077 * \param priority Dialplan priority.
1078 * \return JSON object with \c context, \c exten and \c priority fields
1079 */
1080struct ast_json *ast_json_dialplan_cep(const char *context, const char *exten, int priority);
1081
1084};
1085
1086/*!
1087 * \brief Create an ao2 object to pass json blobs as data payloads for stasis
1088 * \since 12.0.0
1089 *
1090 * \param json the ast_json blob we are loading
1091 *
1092 * \return pointer to the ast_json_payload created
1093 * \retval NULL if we fail to alloc it
1094 */
1096
1097struct ast_party_id;
1098/*!
1099 * \brief Construct an ast_party_id as JSON.
1100 * \since 12.0.0
1101 *
1102 * \param party The party ID to represent as JSON.
1103 *
1104 * \return JSON object with \c name, \c number and \c subaddress objects
1105 * for those that are valid in the party ID
1106 */
1107struct ast_json *ast_json_party_id(struct ast_party_id *party);
1108
1110 /*! \brief Conversion successful */
1112 /*!
1113 * \brief Conversion failed because invalid value type supplied.
1114 * \note Only string values allowed.
1115 */
1117 /*! \brief Conversion failed because of allocation failure. (Out Of Memory) */
1119};
1120
1121/*!
1122 * \brief Convert a \c ast_json list of key/value pair tuples into a \c ast_variable list
1123 * \since 12.5.0
1124 *
1125 * \param json_variables The JSON blob containing the variable
1126 * \param variables An out reference to the variables to populate.
1127 *
1128 * \code
1129 * struct ast_json *json_variables = ast_json_pack("[ { s: s } ]", "foo", "bar");
1130 * struct ast_variable *variables = NULL;
1131 * int res;
1132 *
1133 * res = ast_json_to_ast_variables(json_variables, &variables);
1134 * \endcode
1135 *
1136 * \return Conversion enum ast_json_to_ast_vars_code status
1137 */
1138enum ast_json_to_ast_vars_code ast_json_to_ast_variables(struct ast_json *json_variables, struct ast_variable **variables);
1139
1140struct varshead;
1141
1142/*!
1143 * \brief Construct a JSON object from a \c ast_var_t list
1144 * \since 14.2.0
1145 *
1146 * \param channelvars The list of \c ast_var_t to represent as JSON
1147 *
1148 * \return JSON object with variable names as keys and variable values as values
1149 */
1150struct ast_json *ast_json_channel_vars(struct varshead *channelvars);
1151
1152/*!@}*/
1153
1154#endif /* _ASTERISK_JSON_H */
const char * str
Definition: app_jack.c:147
static int input(yyscan_t yyscanner)
Definition: ast_expr2f.c:1570
#define AST_JSON_INT_T
Definition: autoconfig.h:11
static int priority
static const char type[]
Definition: chan_ooh323.c:109
static const char name[]
Definition: format_mp3.c:68
static int array(struct ast_channel *chan, const char *cmd, char *var, const char *value)
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
int ast_json_array_remove(struct ast_json *array, size_t index)
Remove an element from an array.
Definition: json.c:386
int ast_json_object_clear(struct ast_json *object)
Delete all elements from a JSON object.
Definition: json.c:422
struct ast_json * ast_json_false(void)
Get the JSON false value.
Definition: json.c:238
struct ast_json * ast_json_ipaddr(const struct ast_sockaddr *addr, enum ast_transport transport_type)
Construct an IP address as JSON.
Definition: json.c:682
struct ast_json * ast_json_object_iter_value(struct ast_json_iter *iter)
Get the value from an iterator.
Definition: json.c:455
struct ast_json * ast_json_dialplan_cep(const char *context, const char *exten, int priority)
Construct a context/exten/priority as JSON.
Definition: json.c:665
struct ast_json * ast_json_deep_copy(const struct ast_json *value)
Copy a JSON value, and its children.
Definition: json.c:641
int ast_json_is_array(const struct ast_json *value)
Check if value is JSON array.
Definition: json.c:253
int ast_json_array_clear(struct ast_json *array)
Remove all elements from an array.
Definition: json.c:390
struct ast_json * ast_json_string_create(const char *value)
Construct a JSON string from value.
Definition: json.c:278
int ast_json_object_update_missing(struct ast_json *object, struct ast_json *other)
Add new fields to object with the fields of other.
Definition: json.c:434
enum ast_json_type ast_json_typeof(const struct ast_json *value)
Get the type of value.
Definition: json.c:78
struct ast_json * ast_json_null(void)
Get the JSON null value.
Definition: json.c:248
void ast_json_unref(struct ast_json *value)
Decrease refcount on value. If refcount reaches zero, value is freed.
Definition: json.c:73
void ast_json_free(void *p)
Asterisk's custom JSON allocator. Exposed for use by unit tests.
Definition: json.c:52
struct ast_json_iter * ast_json_object_iter_next(struct ast_json *object, struct ast_json_iter *iter)
Get the next iterator.
Definition: json.c:447
int ast_json_array_set(struct ast_json *array, size_t index, struct ast_json *value)
Change an element in an array.
Definition: json.c:374
int ast_json_array_append(struct ast_json *array, struct ast_json *value)
Append to an array.
Definition: json.c:378
int ast_json_equal(const struct ast_json *lhs, const struct ast_json *rhs)
Compare two JSON objects.
Definition: json.c:357
int ast_json_is_false(const struct ast_json *value)
Check if value is JSON false.
Definition: json.c:268
size_t ast_json_object_size(struct ast_json *object)
Get size of JSON object.
Definition: json.c:403
struct ast_json * ast_json_object_create(void)
Create a new JSON object.
Definition: json.c:399
struct ast_json * ast_json_array_get(const struct ast_json *array, size_t index)
Get an element from an array.
Definition: json.c:370
struct ast_json * ast_json_name_number(const char *name, const char *number)
Common JSON rendering functions for common 'objects'.
Definition: json.c:646
const char * ast_json_typename(enum ast_json_type type)
Get the string name for the given type.
Definition: json.c:95
struct ast_json_payload * ast_json_payload_create(struct ast_json *json)
Create an ao2 object to pass json blobs as data payloads for stasis.
Definition: json.c:756
int ast_json_integer_set(struct ast_json *integer, intmax_t value)
Set the value of a JSON integer.
Definition: json.c:337
struct ast_json * ast_json_pack(char const *format,...)
Helper for creating complex JSON values.
Definition: json.c:612
int ast_json_array_insert(struct ast_json *array, size_t index, struct ast_json *value)
Insert into an array.
Definition: json.c:382
struct ast_json * ast_json_timeval(const struct timeval tv, const char *zone)
Construct a timeval as JSON.
Definition: json.c:670
struct ast_json * ast_json_load_str(const struct ast_str *input, struct ast_json_error *error)
Parse ast_str into a JSON object or array.
Definition: json.c:580
struct ast_json * ast_json_boolean(int value)
Get the JSON boolean corresponding to value.
Definition: json.c:243
struct ast_json * ast_json_integer_create(intmax_t value)
Create a JSON integer.
Definition: json.c:327
struct ast_json * ast_json_vstringf(const char *format, va_list args)
Create a JSON string, vprintf style.
Definition: json.c:303
struct ast_json * ast_json_stringf(const char *format,...)
Create a JSON string, printf style.
Definition: json.c:293
struct ast_json * ast_json_load_string(const char *input, struct ast_json_error *error)
Parse null terminated string into a JSON object or array.
Definition: json.c:567
struct ast_json * ast_json_array_create(void)
Create a empty JSON array.
Definition: json.c:362
struct ast_json * ast_json_party_id(struct ast_party_id *party)
Construct an ast_party_id as JSON.
Definition: json.c:805
#define AST_JSON_ERROR_TEXT_LENGTH
Definition: json.h:880
void * ast_json_malloc(size_t size)
Asterisk's custom JSON allocator. Exposed for use by unit tests.
Definition: json.c:47
void ast_json_reset_alloc_funcs(void)
Change alloc funcs back to the resource module defaults.
Definition: json.c:62
struct ast_json * ast_json_object_create_vars(const struct ast_variable *variables, const char *excludes)
Create a new JSON object using the given variables.
Definition: json.c:877
int ast_json_object_update_existing(struct ast_json *object, struct ast_json *other)
Update existing fields in object with the fields of other.
Definition: json.c:430
int ast_json_object_iter_set(struct ast_json *object, struct ast_json_iter *iter, struct ast_json *value)
Set the value of the field pointed to by an iterator.
Definition: json.c:459
struct ast_json * ast_json_true(void)
Get the JSON true value.
Definition: json.c:233
struct ast_json_iter * ast_json_object_iter_at(struct ast_json *object, const char *key)
Get an iterator pointing to a specified key in object.
Definition: json.c:443
int ast_json_object_del(struct ast_json *object, const char *key)
Delete a field from a JSON object.
Definition: json.c:418
struct ast_json_iter * ast_json_object_iter(struct ast_json *object)
Get an iterator pointing to the first field in a JSON object.
Definition: json.c:439
int ast_json_array_extend(struct ast_json *array, struct ast_json *tail)
Append all elements from tail to array.
Definition: json.c:394
int ast_json_dump_file_format(struct ast_json *root, FILE *output, enum ast_json_encoding_format format)
Encode a JSON value to a FILE.
Definition: json.c:526
ast_json_type
Valid types of a JSON element.
Definition: json.h:163
@ AST_JSON_STRING
Definition: json.h:166
@ AST_JSON_ARRAY
Definition: json.h:165
@ AST_JSON_NULL
Definition: json.h:171
@ AST_JSON_OBJECT
Definition: json.h:164
@ AST_JSON_FALSE
Definition: json.h:170
@ AST_JSON_REAL
Definition: json.h:168
@ AST_JSON_INTEGER
Definition: json.h:167
@ AST_JSON_TRUE
Definition: json.h:169
int ast_json_utf8_check_len(const char *str, size_t len)
Check the string of the given length for UTF-8 format.
Definition: json.c:186
int ast_json_real_set(struct ast_json *real, double value)
Set the value of a JSON real number.
Definition: json.c:352
struct ast_json * ast_json_load_file(FILE *input, struct ast_json_error *error)
Parse a FILE into JSON object or array.
Definition: json.c:592
ast_json_encoding_format
Encoding format type.
Definition: json.h:791
@ AST_JSON_SORTED
Definition: json.h:797
@ AST_JSON_COMPACT
Definition: json.h:793
@ AST_JSON_PRETTY
Definition: json.h:795
struct ast_json * ast_json_dialplan_cep_app(const char *context, const char *exten, int priority, const char *app_name, const char *app_data)
Construct a context/exten/priority/application/application_data as JSON.
Definition: json.c:653
struct ast_json * ast_json_ref(struct ast_json *value)
Increase refcount on value.
Definition: json.c:67
int ast_json_dump_str_format(struct ast_json *root, struct ast_str **dst, enum ast_json_encoding_format format)
Encode a JSON value to an ast_str.
Definition: json.c:520
int ast_json_object_set(struct ast_json *object, const char *key, struct ast_json *value)
Set a field in a JSON object.
Definition: json.c:414
int ast_json_dump_new_file_format(struct ast_json *root, const char *path, enum ast_json_encoding_format format)
Encode a JSON value to a file at the given location.
Definition: json.c:533
struct ast_json * ast_json_load_buf(const char *buffer, size_t buflen, struct ast_json_error *error)
Parse buffer with known length into a JSON object or array.
Definition: json.c:585
const char * ast_json_string_get(const struct ast_json *string)
Get the value of a JSON string.
Definition: json.c:283
const char * ast_json_object_iter_key(struct ast_json_iter *iter)
Get the key from an iterator.
Definition: json.c:451
ast_json_to_ast_vars_code
Definition: json.h:1109
@ AST_JSON_TO_AST_VARS_CODE_INVALID_TYPE
Conversion failed because invalid value type supplied.
Definition: json.h:1116
@ AST_JSON_TO_AST_VARS_CODE_SUCCESS
Conversion successful.
Definition: json.h:1111
@ AST_JSON_TO_AST_VARS_CODE_OOM
Conversion failed because of allocation failure. (Out Of Memory)
Definition: json.h:1118
struct ast_json * ast_json_object_get(struct ast_json *object, const char *key)
Get a field from a JSON object.
Definition: json.c:407
void ast_json_set_alloc_funcs(void *(*malloc_fn)(size_t), void(*free_fn)(void *))
Set custom allocators instead of the standard ast_malloc() and ast_free().
Definition: json.c:57
enum ast_json_to_ast_vars_code ast_json_to_ast_variables(struct ast_json *json_variables, struct ast_variable **variables)
Convert a ast_json list of key/value pair tuples into a ast_variable list.
Definition: json.c:818
int ast_json_init(void)
Initialize the JSON library.
Definition: json.c:726
intmax_t ast_json_integer_get(const struct ast_json *integer)
Get the value from a JSON integer.
Definition: json.c:332
int ast_json_is_object(const struct ast_json *value)
Check if value is JSON object.
Definition: json.c:258
struct ast_json * ast_json_channel_vars(struct varshead *channelvars)
Construct a JSON object from a ast_var_t list.
Definition: json.c:864
char * ast_json_dump_string_format(struct ast_json *root, enum ast_json_encoding_format format)
Encode a JSON value to a string.
Definition: json.c:484
struct ast_json * ast_json_copy(const struct ast_json *value)
Copy a JSON value, but not its children.
Definition: json.c:637
struct ast_json * ast_json_real_create(double value)
Create a JSON real number.
Definition: json.c:342
int ast_json_is_true(const struct ast_json *value)
Check if value is JSON true.
Definition: json.c:263
AST_JSON_INT_T ast_json_int_t
Primarily used to cast when packing to an "I" type.
Definition: json.h:87
struct ast_json * ast_json_load_new_file(const char *path, struct ast_json_error *error)
Parse file at path into JSON object or array.
Definition: json.c:604
int ast_json_utf8_check(const char *str)
Check the nul terminated string for UTF-8 format.
Definition: json.c:228
struct ast_json * ast_json_vpack(char const *format, va_list ap)
Helper for creating complex JSON values simply.
Definition: json.c:621
int ast_json_object_update(struct ast_json *object, struct ast_json *other)
Update object with all of the fields of other.
Definition: json.c:426
size_t ast_json_array_size(const struct ast_json *array)
Get the size of a JSON array.
Definition: json.c:366
int ast_json_is_null(const struct ast_json *value)
Check if value is JSON null.
Definition: json.c:273
double ast_json_real_get(const struct ast_json *real)
Get the value from a JSON real number.
Definition: json.c:347
int ast_json_string_set(struct ast_json *string, const char *value)
Change the value of a JSON string.
Definition: json.c:288
float real
Definition: lpc10.h:79
INT32 integer
Definition: lpc10.h:80
Network socket handling.
ast_transport
Definition: netsock2.h:59
const char * app_name(struct ast_app *app)
Definition: pbx_app.c:463
JSON parsing error information.
Definition: json.h:887
char source[AST_JSON_ERROR_TEXT_LENGTH]
Definition: json.h:897
int position
Definition: json.h:893
int line
Definition: json.h:889
int column
Definition: json.h:891
char text[AST_JSON_ERROR_TEXT_LENGTH]
Definition: json.h:895
Iterator for JSON object key/values.
struct ast_json * json
Definition: json.h:1083
Abstract JSON element (object, array, string, int, ...).
Information needed to identify an endpoint in a call.
Definition: channel.h:340
Socket address structure.
Definition: netsock2.h:97
Support for dynamic strings.
Definition: strings.h:623
Structure for variables, used for configurations and for channel variables.
Number structure.
Definition: app_followme.c:154
int value
Definition: syslog.c:37
const char * args
int error(const char *format,...)
Definition: utils/frame.c:999