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