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