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