Asterisk - The Open Source Telephony Project  GIT-master-a24979a
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  */
92 int 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  */
104 void 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  */
114 void ast_json_reset_alloc_funcs(void);
115 
116 /*!
117  * \brief Asterisk's custom JSON allocator. Exposed for use by unit tests.
118  * \since 12.0.0
119  * \internal
120  */
121 void *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  */
128 void 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  */
135 struct 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  */
144 struct 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  */
152 void 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  */
180 enum 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  */
189 const 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  */
205 int 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  */
216 int 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  */
239 struct 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  */
250 struct 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  */
258 struct 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  */
269 struct ast_json *ast_json_null(void);
270 
271 /*!
272  * \brief Check if \a value is JSON true.
273  * \since 12.0.0
274  * \retval True (non-zero) if \a value == \ref ast_json_true().
275  * \retval False (zero) otherwise..
276  */
277 int ast_json_is_true(const struct ast_json *value);
278 
279 /*!
280  * \brief Check if \a value is JSON false.
281  * \since 12.0.0
282  * \retval True (non-zero) if \a value == \ref ast_json_false().
283  * \retval False (zero) otherwise.
284  */
285 int ast_json_is_false(const struct ast_json *value);
286 
287 /*!
288  * \brief Check if \a value is JSON null.
289  * \since 12.0.0
290  * \retval True (non-zero) if \a value == \ref ast_json_false().
291  * \retval False (zero) otherwise.
292  */
293 int ast_json_is_null(const struct ast_json *value);
294 
295 /*!@}*/
296 
297 /*!@{*/
298 
299 /*!
300  * \brief Construct a JSON string from \a value.
301  * \since 12.0.0
302  *
303  * The given \a value must be a valid ASCII or UTF-8 encoded string.
304  *
305  * \param value Value of new JSON string.
306  * \return Newly constructed string element.
307  * \retval NULL on error.
308  */
309 struct ast_json *ast_json_string_create(const char *value);
310 
311 /*!
312  * \brief Get the value of a JSON string.
313  * \since 12.0.0
314  * \param string JSON string.
315  * \return Value of the string.
316  * \retval NULL on error.
317  */
318 const char *ast_json_string_get(const struct ast_json *string);
319 
320 /*!
321  * \brief Change the value of a JSON string.
322  * \since 12.0.0
323  *
324  * The given \a value must be a valid ASCII or UTF-8 encoded string.
325  *
326  * \param string JSON string to modify.
327  * \param value New value to store in \a string.
328  * \retval 0 on success.
329  * \retval -1 on error.
330  */
331 int ast_json_string_set(struct ast_json *string, const char *value);
332 
333 /*!
334  * \brief Create a JSON string, printf style.
335  * \since 12.0.0
336  *
337  * The formatted value must be a valid ASCII or UTF-8 encoded string.
338  *
339  * \param format \c printf style format string.
340  * \return Newly allocated string.
341  * \retval NULL on error.
342  */
343 struct ast_json *ast_json_stringf(const char *format, ...) __attribute__((format(printf, 1, 2)));
344 
345 /*!
346  * \brief Create a JSON string, vprintf style.
347  * \since 12.0.0
348  *
349  * The formatted value must be a valid ASCII or UTF-8 encoded string.
350  *
351  * \param format \c printf style format string.
352  * \param args
353  *
354  * \return Newly allocated string.
355  * \retval NULL on error.
356  */
357 struct ast_json *ast_json_vstringf(const char *format, va_list args) __attribute__((format(printf, 1, 0)));
358 
359 /*!@}*/
360 
361 /*!@{*/
362 
363 /*!
364  * \brief Create a JSON integer.
365  * \since 12.0.0
366  * \param value Value of the new JSON integer.
367  * \return Newly allocated integer.
368  * \retval NULL on error.
369  */
370 struct ast_json *ast_json_integer_create(intmax_t value);
371 
372 /*!
373  * \brief Get the value from a JSON integer.
374  * \since 12.0.0
375  * \param integer JSON integer.
376  * \return Value of a JSON integer.
377  * \retval 0 if \a integer is not a JSON integer.
378  */
379 intmax_t ast_json_integer_get(const struct ast_json *integer);
380 
381 /*!
382  * \brief Set the value of a JSON integer.
383  * \since 12.0.0
384  * \param integer JSON integer to modify.
385  * \param value New value for \a integer.
386  * \retval 0 on success.
387  * \retval -1 on error.
388  */
389 int ast_json_integer_set(struct ast_json *integer, intmax_t value);
390 
391 /*!
392  * \brief Create a JSON real number.
393  * \since 12.0.0
394  * \param value Value of the new JSON real number.
395  * \return Newly allocated real number.
396  * \retval NULL on error.
397  */
398 struct ast_json *ast_json_real_create(double value);
399 
400 /*!
401  * \brief Get the value from a JSON real number.
402  * \since 12.0.0
403  * \param real JSON real number.
404  * \return Value of a JSON real number.
405  * \retval 0 if \a real is not a JSON real number.
406  */
407 double ast_json_real_get(const struct ast_json *real);
408 
409 /*!
410  * \brief Set the value of a JSON real number.
411  * \since 12.0.0
412  * \param real JSON real number to modify.
413  * \param value New value for \a real.
414  * \retval 0 on success.
415  * \retval -1 on error.
416  */
417 int ast_json_real_set(struct ast_json *real, double value);
418 
419 /*!@}*/
420 
421 /*!@{*/
422 
423 /*!
424  * \brief Create a empty JSON array.
425  * \since 12.0.0
426  * \return Newly allocated array.
427  * \retval NULL on error.
428  */
429 struct ast_json *ast_json_array_create(void);
430 
431 /*!
432  * \brief Get the size of a JSON array.
433  * \since 12.0.0
434  * \param array JSON array.
435  * \return Size of \a array.
436  * \retval 0 if array is not a JSON array.
437  */
438 size_t ast_json_array_size(const struct ast_json *array);
439 
440 /*!
441  * \brief Get an element from an array.
442  * \since 12.0.0
443  *
444  * The returned element is a borrowed reference; use ast_json_ref() to safely keep a
445  * pointer to it.
446  *
447  * \param array JSON array.
448  * \param index Zero-based index into \a array.
449  * \return The specified element.
450  * \retval NULL if \a array not an array.
451  * if \a index is out of bounds.
452  */
453 struct ast_json *ast_json_array_get(const struct ast_json *array, size_t index);
454 
455 /*!
456  * \brief Change an element in an array.
457  * \since 12.0.0
458  *
459  * \note The \a array steals the \a value reference even if it returns error;
460  * use ast_json_ref() to safely keep a pointer to it.
461  *
462  * \param array JSON array to modify.
463  * \param index Zero-based index into array.
464  * \param value New JSON value to store in \a array at \a index.
465  * \retval 0 on success.
466  * \retval -1 on error.
467  */
468 int ast_json_array_set(struct ast_json *array, size_t index, struct ast_json *value);
469 
470 /*!
471  * \brief Append to an array.
472  * \since 12.0.0
473  *
474  * \note The \a array steals the \a value reference even if it returns error;
475  * use ast_json_ref() to safely keep a pointer to it.
476  *
477  * \param array JSON array to modify.
478  * \param value New JSON value to store at the end of \a array.
479  * \retval 0 on success.
480  * \retval -1 on error.
481  */
482 int ast_json_array_append(struct ast_json *array, struct ast_json *value);
483 
484 /*!
485  * \brief Insert into an array.
486  * \since 12.0.0
487  *
488  * \note The \a array steals the \a value reference even if it returns error;
489  * use ast_json_ref() to safely keep a pointer to it.
490  *
491  * \param array JSON array to modify.
492  * \param index Zero-based index into array.
493  * \param value New JSON value to store in \a array at \a index.
494  * \retval 0 on success.
495  * \retval -1 on error.
496  */
497 int ast_json_array_insert(struct ast_json *array, size_t index, struct ast_json *value);
498 
499 /*!
500  * \brief Remove an element from an array.
501  * \since 12.0.0
502  * \param array JSON array to modify.
503  * \param index Zero-based index into array.
504  * \retval 0 on success.
505  * \retval -1 on error.
506  */
507 int ast_json_array_remove(struct ast_json *array, size_t index);
508 
509 /*!
510  * \brief Remove all elements from an array.
511  * \since 12.0.0
512  * \param array JSON array to clear.
513  * \retval 0 on success.
514  * \retval -1 on error.
515  */
516 int ast_json_array_clear(struct ast_json *array);
517 
518 /*!
519  * \brief Append all elements from \a tail to \a array.
520  * \since 12.0.0
521  *
522  * The \a tail argument is not changed, so ast_json_unref() it when you are done with it.
523  *
524  * \param array JSON array to modify.
525  * \param tail JSON array with contents to append to \a array.
526  * \retval 0 on success.
527  * \retval -1 on error.
528  */
529 int ast_json_array_extend(struct ast_json *array, struct ast_json *tail);
530 
531 /*!@}*/
532 
533 /*!@{*/
534 
535 /*!
536  * \brief Create a new JSON object.
537  * \since 12.0.0
538  * \return Newly allocated object.
539  * \retval NULL on error.
540  */
541 struct ast_json *ast_json_object_create(void);
542 
543 /*!
544  * \brief Create a new JSON object using the given variables
545  * \param variables A list of Asterisk variables
546  * \param excludes Comma separated string of variable names to exclude (optional)
547  * \return Newly allocated object.
548  * \retval NULL on error.
549  */
550 struct ast_json *ast_json_object_create_vars(const struct ast_variable *variables, const char *excludes);
551 
552 /*!
553  * \brief Get size of JSON object.
554  * \since 12.0.0
555  * \param object JSON object.
556  * \return Size of \a object.
557  * \retval Zero of \a object is not a JSON object.
558  */
559 size_t ast_json_object_size(struct ast_json *object);
560 
561 /*!
562  * \brief Get a field from a JSON object.
563  * \since 12.0.0
564  *
565  * The returned element is a borrowed reference; use ast_json_ref() to safely keep a
566  * pointer to it.
567  *
568  * \param object JSON object.
569  * \param key Key of field to look up.
570  * \return Value with given \a key.
571  * \retval NULL on error.
572  */
573 struct ast_json *ast_json_object_get(struct ast_json *object, const char *key);
574 
575 /*!
576  * \brief Get a string field from a JSON object.
577  * \since 16.3.0
578  *
579  * \param object JSON object.
580  * \param key Key of string field to look up.
581  * \return String value of given \a key.
582  * \retval NULL on error, or key value is not a string.
583  */
584 #define ast_json_object_string_get(object, key) ast_json_string_get(ast_json_object_get(object, key))
585 
586 /*!
587  * \brief Get an integer field from a JSON object.
588  * \param object JSON object.
589  * \param key Key of integer field to look up.
590  * \return Value of a JSON integer.
591  * \retval 0 if \a integer is not a JSON integer.
592  */
593 #define ast_json_object_integer_get(object, key) ast_json_integer_get(ast_json_object_get(object, key))
594 
595 /*!
596  * \brief Set a field in a JSON object.
597  * \since 12.0.0
598  *
599  * \note The object steals the \a value reference even if it returns error;
600  * use ast_json_ref() to safely keep a pointer to it.
601  *
602  * \param object JSON object to modify.
603  * \param key Key of field to set.
604  * \param value JSON value to set for field.
605  * \retval 0 on success.
606  * \retval -1 on error.
607  */
608 int ast_json_object_set(struct ast_json *object, const char *key, struct ast_json *value);
609 
610 /*!
611  * \brief Delete a field from a JSON object.
612  * \since 12.0.0
613  *
614  * \param object JSON object to modify.
615  * \param key Key of field to delete.
616  * \retval 0 on success, or -1 if key does not exist.
617  */
618 int ast_json_object_del(struct ast_json *object, const char *key);
619 
620 /*!
621  * \brief Delete all elements from a JSON object.
622  * \since 12.0.0
623  * \param object JSON object to clear.
624  * \retval 0 on success.
625  * \retval -1 on error.
626  */
627 int ast_json_object_clear(struct ast_json *object);
628 
629 /*!
630  * \brief Update \a object with all of the fields of \a other.
631  * \since 12.0.0
632  *
633  * All of the fields of \a other are copied into \a object, overwriting existing keys.
634  * The \a other object is not changed, so ast_json_unref() it when you are done with it.
635  *
636  * \param object JSON object to modify.
637  * \param other JSON object to copy into \a object.
638  * \retval 0 on success.
639  * \retval -1 on error.
640  */
641 int ast_json_object_update(struct ast_json *object, struct ast_json *other);
642 
643 /*!
644  * \brief Update existing fields in \a object with the fields of \a other.
645  * \since 12.0.0
646  *
647  * Like ast_json_object_update(), but only existing fields are updated. No new fields
648  * will get added. The \a other object is not changed, so ast_json_unref() it when you
649  * are done with it.
650  *
651  * \param object JSON object to modify.
652  * \param other JSON object to copy into \a object.
653  * \retval 0 on success.
654  * \retval -1 on error.
655  */
656 int ast_json_object_update_existing(struct ast_json *object, struct ast_json *other);
657 
658 /*!
659  * \brief Add new fields to \a object with the fields of \a other.
660  * \since 12.0.0
661  *
662  * Like ast_json_object_update(), but only missing fields are added. No existing fields
663  * will be modified. The \a other object is not changed, so ast_json_unref() it when you
664  * are done with it.
665  *
666  * \param object JSON object to modify.
667  * \param other JSON object to copy into \a object.
668  * \retval 0 on success.
669  * \retval -1 on error.
670  */
671 int ast_json_object_update_missing(struct ast_json *object, struct ast_json *other);
672 
673 /*!
674  * \struct ast_json_iter
675  * \brief Iterator for JSON object key/values.
676  * \since 12.0.0
677  *
678  * Note that iteration order is not specified, and may change as fields are added to
679  * and removed from the object.
680  */
681 struct ast_json_iter;
682 
683 /*!
684  * \brief Get an iterator pointing to the first field in a JSON object.
685  * \since 12.0.0
686  *
687  * The order of the fields in an object are not specified. However, iterating forward
688  * from this iterator will cover all fields in \a object. Adding or removing fields from
689  * \a object may invalidate its iterators.
690  *
691  * \param object JSON object.
692  * \return Iterator to the first field in \a object.
693  * \retval NULL \a object is empty.
694  * on error.
695  */
696 struct ast_json_iter *ast_json_object_iter(struct ast_json *object);
697 
698 /*!
699  * \brief Get an iterator pointing to a specified \a key in \a object.
700  * \since 12.0.0
701  *
702  * Iterating forward from this iterator may not to cover all elements in \a object.
703  *
704  * \param object JSON object to iterate.
705  * \param key Key of field to lookup.
706  * \return Iterator pointing to the field with the given \a key.
707  * \retval NULL if \a key does not exist.
708  * on error.
709  */
710 struct ast_json_iter *ast_json_object_iter_at(struct ast_json *object, const char *key);
711 
712 /*!
713  * \brief Get the next iterator.
714  * \since 12.0.0
715  * \param object JSON object \a iter was obtained from.
716  * \param iter JSON object iterator.
717  * \return Iterator to next field in \a object.
718  * \retval NULL if \a iter was the last field.
719  */
720 struct ast_json_iter *ast_json_object_iter_next(struct ast_json *object, struct ast_json_iter *iter);
721 
722 /*!
723  * \brief Get the key from an iterator.
724  * \since 12.0.0
725  * \param iter JSON object iterator.
726  * \return Key of the field \a iter points to.
727  */
728 const char *ast_json_object_iter_key(struct ast_json_iter *iter);
729 
730 /*!
731  * \brief Get the value from an iterator.
732  * \since 12.0.0
733  *
734  * The returned element is a borrowed reference; use ast_json_ref() to safely
735  * keep a pointer to it.
736  *
737  * \param iter JSON object iterator.
738  * \return Value of the field \a iter points to.
739  */
741 
742 /*!
743  * \brief Set the value of the field pointed to by an iterator.
744  * \since 12.0.0
745  *
746  * \note The object steals the \p value reference even if it returns error;
747  * use ast_json_ref() to safely keep a pointer to it.
748  *
749  * \param object JSON object \p iter was obtained from.
750  * \param iter JSON object iterator.
751  * \param value JSON value to store in \p iter's field.
752  * \retval 0 on success.
753  * \retval -1 on error.
754  */
755 int ast_json_object_iter_set(struct ast_json *object, struct ast_json_iter *iter, struct ast_json *value);
756 
757 /*!@}*/
758 
759 /*!@{*/
760 
761 /*!
762  * \brief Encoding format type.
763  * \since 12.0.0
764  */
766 {
767  /*! Compact format, low human readability */
769  /*! Formatted for human readability */
771 };
772 
773 /*!
774  * \brief Encode a JSON value to a compact string.
775  * \since 12.0.0
776  *
777  * Returned string must be freed by calling ast_json_free().
778  *
779  * \param root JSON value.
780  * \return String encoding of \a root.
781  * \retval NULL on error.
782  */
783 #define ast_json_dump_string(root) ast_json_dump_string_format(root, AST_JSON_COMPACT)
784 
785 /*!
786  * \brief Encode a JSON value to a string.
787  * \since 12.0.0
788  *
789  * Returned string must be freed by calling ast_json_free().
790  *
791  * \param root JSON value.
792  * \param format encoding format type.
793  * \return String encoding of \a root.
794  * \retval NULL on error.
795  */
797 
798 #define ast_json_dump_str(root, dst) ast_json_dump_str_format(root, dst, AST_JSON_COMPACT)
799 
800 /*!
801  * \brief Encode a JSON value to an \ref ast_str.
802  * \since 12.0.0
803  *
804  * If \a dst is too small, it will be grown as needed.
805  *
806  * \param root JSON value.
807  * \param dst \ref ast_str to store JSON encoding.
808  * \param format encoding format type.
809  * \retval 0 on success.
810  * \retval -1 on error. The contents of \a dst are undefined.
811  */
812 int ast_json_dump_str_format(struct ast_json *root, struct ast_str **dst, enum ast_json_encoding_format format);
813 
814 #define ast_json_dump_file(root, output) ast_json_dump_file_format(root, output, AST_JSON_COMPACT)
815 
816 /*!
817  * \brief Encode a JSON value to a \c FILE.
818  * \since 12.0.0
819  *
820  * \param root JSON value.
821  * \param output File to write JSON encoding to.
822  * \param format encoding format type.
823  * \retval 0 on success.
824  * \retval -1 on error. The contents of \a output are undefined.
825  */
826 int ast_json_dump_file_format(struct ast_json *root, FILE *output, enum ast_json_encoding_format format);
827 
828 #define ast_json_dump_new_file(root, path) ast_json_dump_new_file_format(root, path, AST_JSON_COMPACT)
829 
830 /*!
831  * \brief Encode a JSON value to a file at the given location.
832  * \since 12.0.0
833  *
834  * \param root JSON value.
835  * \param path Path to file to write JSON encoding to.
836  * \param format encoding format type.
837  * \retval 0 on success.
838  * \retval -1 on error. The contents of \a output are undefined.
839  */
840 int ast_json_dump_new_file_format(struct ast_json *root, const char *path, enum ast_json_encoding_format format);
841 
842 #define AST_JSON_ERROR_TEXT_LENGTH 160
843 #define AST_JSON_ERROR_SOURCE_LENGTH 80
844 
845 /*!
846  * \brief JSON parsing error information.
847  * \since 12.0.0
848  */
850  /*! Line number error occured on */
851  int line;
852  /*! Character (not byte, can be different for UTF-8) column on which the error occurred. */
853  int column;
854  /*! Position in bytes from start of input */
855  int position;
856  /*! Error message */
858  /*! Source of the error (filename or <string>) */
860 };
861 
862 /*!
863  * \brief Parse null terminated string into a JSON object or array.
864  * \since 12.0.0
865  * \param input String to parse.
866  * \param[out] error Filled with information on error.
867  * \return Parsed JSON element.
868  * \retval NULL on error.
869  */
870 struct ast_json *ast_json_load_string(const char *input, struct ast_json_error *error);
871 
872 /*!
873  * \brief Parse \ref ast_str into a JSON object or array.
874  * \since 12.0.0
875  * \param input \ref ast_str to parse.
876  * \param[out] error Filled with information on error.
877  * \return Parsed JSON element.
878  * \retval NULL on error.
879  */
880 struct ast_json *ast_json_load_str(const struct ast_str *input, struct ast_json_error *error);
881 
882 /*!
883  * \brief Parse buffer with known length into a JSON object or array.
884  * \since 12.0.0
885  * \param buffer Buffer to parse.
886  * \param buflen Length of \a buffer.
887  * \param[out] error Filled with information on error.
888  * \return Parsed JSON element.
889  * \retval NULL on error.
890  */
891 struct ast_json *ast_json_load_buf(const char *buffer, size_t buflen, struct ast_json_error *error);
892 
893 /*!
894  * \brief Parse a \c FILE into JSON object or array.
895  * \since 12.0.0
896  * \param input \c FILE to parse.
897  * \param[out] error Filled with information on error.
898  * \return Parsed JSON element.
899  * \retval NULL on error.
900  */
901 struct ast_json *ast_json_load_file(FILE *input, struct ast_json_error *error);
902 
903 /*!
904  * \brief Parse file at \a path into JSON object or array.
905  * \since 12.0.0
906  * \param path Path of file to parse.
907  * \param[out] error Filled with information on error.
908  * \return Parsed JSON element.
909  * \retval NULL on error.
910  */
911 struct ast_json *ast_json_load_new_file(const char *path, struct ast_json_error *error);
912 
913 /*!
914  * \brief Helper for creating complex JSON values.
915  * \since 12.0.0
916  *
917  * See original Jansson docs at http://www.digip.org/jansson/doc/2.11/apiref.html#apiref-pack
918  * for more details.
919  */
920 struct ast_json *ast_json_pack(char const *format, ...);
921 
922 /*!
923  * \brief Helper for creating complex JSON values simply.
924  * \since 12.0.0
925  *
926  * See original Jansson docs at http://www.digip.org/jansson/doc/2.11/apiref.html#apiref-pack
927  * for more details.
928  */
929 struct ast_json *ast_json_vpack(char const *format, va_list ap);
930 
931 /*!@}*/
932 
933 /*!@{*/
934 
935 /*!
936  * \brief Compare two JSON objects.
937  * \since 12.0.0
938  *
939  * Two JSON objects are equal if they are of the same type, and their contents are equal.
940  *
941  * \param lhs Value to compare.
942  * \param rhs Other value to compare.
943  * \retval True (non-zero) if \a lhs and \a rhs are equal.
944  * \retval False (zero) if they are not.
945  */
946 int ast_json_equal(const struct ast_json *lhs, const struct ast_json *rhs);
947 
948 /*!
949  * \brief Copy a JSON value, but not its children.
950  * \since 12.0.0
951  *
952  * If \a value is a JSON object or array, its children are shared with the returned copy.
953  *
954  * \param value JSON value to copy.
955  * \return Shallow copy of \a value.
956  * \retval NULL on error.
957  */
958 struct ast_json *ast_json_copy(const struct ast_json *value);
959 
960 /*!
961  * \brief Copy a JSON value, and its children.
962  * \since 12.0.0
963  *
964  * If \a value is a JSON object or array, they are also copied.
965  *
966  * \param value JSON value to copy.
967  * \return Deep copy of \a value.
968  * \retval NULL on error.
969  */
970 struct ast_json *ast_json_deep_copy(const struct ast_json *value);
971 
972 /*!@}*/
973 
974 /*!@{*/
975 
976 /*!
977  * \brief Common JSON rendering functions for common 'objects'.
978  */
979 
980 /*!
981  * \brief Simple name/number pair.
982  * \param name Name
983  * \param number Number
984  * \return JSON object with name and number fields
985  * \retval NULL on error (non-UTF8 characters, NULL inputs, etc.)
986  */
987 struct ast_json *ast_json_name_number(const char *name, const char *number);
988 
989 /*!
990  * \brief Construct a timeval as JSON.
991  *
992  * JSON does not define a standard date format (boo), but the de facto standard
993  * is to use ISO 8601 formatted string. We build a millisecond resolution string
994  * from the \c timeval
995  *
996  * \param tv \c timeval to encode.
997  * \param zone Text string of a standard system zoneinfo file. If NULL, the system localtime will be used.
998  * \return JSON string with ISO 8601 formatted date/time.
999  * \retval NULL on error.
1000  */
1001 struct ast_json *ast_json_timeval(const struct timeval tv, const char *zone);
1002 
1003 /*!
1004  * \brief Construct an IP address as JSON
1005  *
1006  * XXX some comments describing the need for this here
1007  *
1008  * \param addr ast_sockaddr to encode
1009  * \param transport_type ast_transport to include in the address string if any. Should just be one.
1010  * \return JSON string containing the IP address with optional transport information
1011  * \retval NULL on error.
1012  */
1013 struct ast_json *ast_json_ipaddr(const struct ast_sockaddr *addr, enum ast_transport transport_type);
1014 
1015 /*!
1016  * \brief Construct a context/exten/priority/application/application_data as JSON.
1017  *
1018  * If a \c NULL is passed for \c context or \c exten or \c app_name or \c app_data,
1019  * or -1 for \c priority, the fields is set to ast_json_null().
1020  *
1021  * \param context Context name.
1022  * \param exten Extension.
1023  * \param priority Dialplan priority.
1024  * \param app_name Application name.
1025  * \param app_data Application argument.
1026  * \return JSON object with \c context, \c exten and \c priority \c app_name \c app_data fields
1027  */
1029  const char *context, const char *exten, int priority, const char *app_name, const char *app_data);
1030 
1031 /*!
1032  * \brief Construct a context/exten/priority as JSON.
1033  *
1034  * If a \c NULL is passed for \c context or \c exten, or -1 for \c priority,
1035  * the fields is set to ast_json_null().
1036  *
1037  * \param context Context name.
1038  * \param exten Extension.
1039  * \param priority Dialplan priority.
1040  * \return JSON object with \c context, \c exten and \c priority fields
1041  */
1042 struct ast_json *ast_json_dialplan_cep(const char *context, const char *exten, int priority);
1043 
1045  struct ast_json *json;
1046 };
1047 
1048 /*!
1049  * \brief Create an ao2 object to pass json blobs as data payloads for stasis
1050  * \since 12.0.0
1051  *
1052  * \param json the ast_json blob we are loading
1053  *
1054  * \return pointer to the ast_json_payload created
1055  * \retval NULL if we fail to alloc it
1056  */
1058 
1059 struct ast_party_id;
1060 /*!
1061  * \brief Construct an ast_party_id as JSON.
1062  * \since 12.0.0
1063  *
1064  * \param party The party ID to represent as JSON.
1065  *
1066  * \return JSON object with \c name, \c number and \c subaddress objects
1067  * for those that are valid in the party ID
1068  */
1069 struct ast_json *ast_json_party_id(struct ast_party_id *party);
1070 
1072  /*! \brief Conversion successful */
1074  /*!
1075  * \brief Conversion failed because invalid value type supplied.
1076  * \note Only string values allowed.
1077  */
1079  /*! \brief Conversion failed because of allocation failure. (Out Of Memory) */
1081 };
1082 
1083 /*!
1084  * \brief Convert a \c ast_json list of key/value pair tuples into a \c ast_variable list
1085  * \since 12.5.0
1086  *
1087  * \param json_variables The JSON blob containing the variable
1088  * \param variables An out reference to the variables to populate.
1089  *
1090  * \code
1091  * struct ast_json *json_variables = ast_json_pack("[ { s: s } ]", "foo", "bar");
1092  * struct ast_variable *variables = NULL;
1093  * int res;
1094  *
1095  * res = ast_json_to_ast_variables(json_variables, &variables);
1096  * \endcode
1097  *
1098  * \return Conversion enum ast_json_to_ast_vars_code status
1099  */
1100 enum ast_json_to_ast_vars_code ast_json_to_ast_variables(struct ast_json *json_variables, struct ast_variable **variables);
1101 
1102 struct varshead;
1103 
1104 /*!
1105  * \brief Construct a JSON object from a \c ast_var_t list
1106  * \since 14.2.0
1107  *
1108  * \param channelvars The list of \c ast_var_t to represent as JSON
1109  *
1110  * \return JSON object with variable names as keys and variable values as values
1111  */
1112 struct ast_json *ast_json_channel_vars(struct varshead *channelvars);
1113 
1114 /*!@}*/
1115 
1116 #endif /* _ASTERISK_JSON_H */
const char * str
Definition: app_jack.c:147
static int input(yyscan_t yyscanner)
Definition: ast_expr2f.c:1584
#define AST_JSON_INT_T
Definition: autoconfig.h:11
static int priority
static char exten[AST_MAX_EXTENSION]
Definition: chan_alsa.c:122
static snd_pcm_format_t format
Definition: chan_alsa.c:106
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:120
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:376
int ast_json_object_clear(struct ast_json *object)
Delete all elements from a JSON object.
Definition: json.c:412
struct ast_json * ast_json_ref(struct ast_json *value)
Increase refcount on value.
Definition: json.c:67
struct ast_json * ast_json_true(void)
Get the JSON true value.
Definition: json.c:233
struct ast_json * ast_json_vpack(char const *format, va_list ap)
Helper for creating complex JSON values simply.
Definition: json.c:600
struct ast_json * ast_json_vstringf(const char *format, va_list args)
Create a JSON string, vprintf style.
Definition: json.c:293
struct ast_json * ast_json_channel_vars(struct varshead *channelvars)
Construct a JSON object from a ast_var_t list.
Definition: json.c:843
int ast_json_array_clear(struct ast_json *array)
Remove all elements from an array.
Definition: json.c:380
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:424
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_timeval(const struct timeval tv, const char *zone)
Construct a timeval as JSON.
Definition: json.c:649
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_unref(struct ast_json *value)
Decrease refcount on value. If refcount reaches zero, value is freed.
Definition: json.c:73
struct ast_json * ast_json_array_get(const struct ast_json *array, size_t index)
Get an element from an array.
Definition: json.c:360
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:463
void ast_json_free(void *p)
Asterisk's custom JSON allocator. Exposed for use by unit tests.
Definition: json.c:52
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:364
int ast_json_array_append(struct ast_json *array, struct ast_json *value)
Append to an array.
Definition: json.c:368
int ast_json_equal(const struct ast_json *lhs, const struct ast_json *rhs)
Compare two JSON objects.
Definition: json.c:347
int ast_json_is_false(const struct ast_json *value)
Check if value is JSON false.
Definition: json.c:258
struct ast_json * ast_json_copy(const struct ast_json *value)
Copy a JSON value, but not its children.
Definition: json.c:616
size_t ast_json_object_size(struct ast_json *object)
Get size of JSON object.
Definition: json.c:393
struct ast_json * ast_json_array_create(void)
Create a empty JSON array.
Definition: json.c:352
int ast_json_integer_set(struct ast_json *integer, intmax_t value)
Set the value of a JSON integer.
Definition: json.c:327
struct ast_json * ast_json_object_get(struct ast_json *object, const char *key)
Get a field from a JSON object.
Definition: json.c:397
int ast_json_array_insert(struct ast_json *array, size_t index, struct ast_json *value)
Insert into an array.
Definition: json.c:372
struct ast_json * ast_json_real_create(double value)
Create a JSON real number.
Definition: json.c:332
struct ast_json * ast_json_object_create(void)
Create a new JSON object.
Definition: json.c:389
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:644
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:559
const char * ast_json_string_get(const struct ast_json *string)
Get the value of a JSON string.
Definition: json.c:273
struct ast_json * ast_json_boolean(int value)
Get the JSON boolean corresponding to value.
Definition: json.c:243
struct ast_json * ast_json_stringf(const char *format,...)
Create a JSON string, printf style.
Definition: json.c:283
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:433
#define AST_JSON_ERROR_TEXT_LENGTH
Definition: json.h:842
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:661
struct ast_json * ast_json_null(void)
Get the JSON null value.
Definition: json.c:248
void ast_json_reset_alloc_funcs(void)
Change alloc funcs back to the resource module defaults.
Definition: json.c:62
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:735
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:420
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:449
struct ast_json * ast_json_pack(char const *format,...)
Helper for creating complex JSON values.
Definition: json.c:591
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:437
int ast_json_object_del(struct ast_json *object, const char *key)
Delete a field from a JSON object.
Definition: json.c:408
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:564
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:571
int ast_json_array_extend(struct ast_json *array, struct ast_json *tail)
Append all elements from tail to array.
Definition: json.c:384
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:429
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:505
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
struct ast_json * ast_json_deep_copy(const struct ast_json *value)
Copy a JSON value, and its children.
Definition: json.c:620
int ast_json_real_set(struct ast_json *real, double value)
Set the value of a JSON real number.
Definition: json.c:342
struct ast_json * ast_json_object_iter_value(struct ast_json_iter *iter)
Get the value from an iterator.
Definition: json.c:445
ast_json_encoding_format
Encoding format type.
Definition: json.h:766
@ AST_JSON_COMPACT
Definition: json.h:768
@ AST_JSON_PRETTY
Definition: json.h:770
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:499
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:404
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:512
struct ast_json * ast_json_integer_create(intmax_t value)
Create a JSON integer.
Definition: json.c:317
ast_json_to_ast_vars_code
Definition: json.h:1071
@ AST_JSON_TO_AST_VARS_CODE_INVALID_TYPE
Conversion failed because invalid value type supplied.
Definition: json.h:1078
@ AST_JSON_TO_AST_VARS_CODE_SUCCESS
Conversion successful.
Definition: json.h:1073
@ AST_JSON_TO_AST_VARS_CODE_OOM
Conversion failed because of allocation failure. (Out Of Memory)
Definition: json.h:1080
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:797
int ast_json_init(void)
Initialize the JSON library.
Definition: json.c:705
intmax_t ast_json_integer_get(const struct ast_json *integer)
Get the value from a JSON integer.
Definition: json.c:322
struct ast_json * ast_json_name_number(const char *name, const char *number)
Common JSON rendering functions for common 'objects'.
Definition: json.c:625
const char * ast_json_object_iter_key(struct ast_json_iter *iter)
Get the key from an iterator.
Definition: json.c:441
struct ast_json * ast_json_string_create(const char *value)
Construct a JSON string from value.
Definition: json.c:268
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:546
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:856
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:583
int ast_json_is_true(const struct ast_json *value)
Check if value is JSON true.
Definition: json.c:253
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_party_id(struct ast_party_id *party)
Construct an ast_party_id as JSON.
Definition: json.c:784
int ast_json_utf8_check(const char *str)
Check the nul terminated string for UTF-8 format.
Definition: json.c:228
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:416
const char * ast_json_typename(enum ast_json_type type)
Get the string name for the given type.
Definition: json.c:95
size_t ast_json_array_size(const struct ast_json *array)
Get the size of a JSON array.
Definition: json.c:356
int ast_json_is_null(const struct ast_json *value)
Check if value is JSON null.
Definition: json.c:263
double ast_json_real_get(const struct ast_json *real)
Get the value from a JSON real number.
Definition: json.c:337
int ast_json_string_set(struct ast_json *string, const char *value)
Change the value of a JSON string.
Definition: json.c:278
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:632
struct ast_json * ast_json_false(void)
Get the JSON false value.
Definition: json.c:238
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:849
char source[AST_JSON_ERROR_TEXT_LENGTH]
Definition: json.h:859
int position
Definition: json.h:855
int line
Definition: json.h:851
int column
Definition: json.h:853
char text[AST_JSON_ERROR_TEXT_LENGTH]
Definition: json.h:857
Iterator for JSON object key/values.
struct ast_json * json
Definition: json.h:1045
Abstract JSON element (object, array, string, int, ...).
Information needed to identify an endpoint in a call.
Definition: channel.h:338
Socket address structure.
Definition: netsock2.h:97
Support for dynamic strings.
Definition: strings.h:604
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