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