Better explained the depths of reference stealing.
[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 /*! \file
23  *
24  * \brief Asterisk JSON abstraction layer.
25  * \since 12.0.0
26  *
27  * This is a very thin wrapper around the Jansson API. For more details on it,
28  * see its docs at http://www.digip.org/jansson/doc/2.4/apiref.html.
29  *
30  * Rather than provide the multiple ways of doing things that the Jansson API
31  * does, the Asterisk wrapper is always reference-stealing, and always NULL
32  * safe.
33  *
34  * And by always, I mean that the reference is stolen even if the function
35  * fails. This avoids lots of conditional logic, and also avoids having to track
36  * zillions of local variables when building complex JSON objects. You can
37  * instead chain \c ast_json_* calls together safely and only worry about
38  * cleaning up the root object.
39  *
40  * In the cases where you have a need to introduce intermediate objects, just
41  * wrap them with json_ref() when passing them to other \c ast_json_*()
42  * functions.
43  *
44  * \code
45  *      // Example of how to use the Asterisk JSON API
46  *      static struct ast_json *foo(void) {
47  *              RAII_VAR(struct ast_json *, array, NULL, ast_json_unref);
48  *              RAII_VAR(struct ast_json *, obj, NULL, ast_json_unref);
49  *              int i, res;
50  *
51  *              array = ast_json_array_create();
52  *              if (!array) { return NULL; }
53  *
54  *              for (i = 0; i < 10; ++i) {
55  *                      // NULL safety and object stealing means calls can
56  *                      // be chained together directly.
57  *                      res = ast_json_array_append(array,
58  *                              ast_json_integer_create(i));
59  *                      if (res != 0) { return NULL; }
60  *              }
61  *
62  *              obj = ast_json_object_create();
63  *              if (!obj) { return NULL; }
64  *
65  *              // If you already have an object reference, ast_json_ref()
66  *              // can be used inline to bump the ref before passing it along
67  *              // to a ref-stealing call
68  *              res = ast_json_object_set(obj, "foo", ast_json_ref(array));
69  *              if (!res) { return NULL; }
70  *
71  *              return obj;
72  *      }
73  * \endcode
74  *
75  * \author David M. Lee, II <dlee@digium.com>
76  */
77
78 /*!@{*/
79
80 /*!
81  * \brief Initialize the JSON library.
82  */
83 void ast_json_init(void);
84
85 /*!
86  * \brief Set custom allocators instead of the standard ast_malloc() and ast_free().
87  * \since 12.0.0
88  *
89  * This is used by the unit tests to do JSON specific memory leak detection. Since it
90  * affects all users of the JSON library, shouldn't normally be used.
91  *
92  * \param malloc_fn Custom allocation function.
93  * \param free_fn Matching free function.
94  */
95 void ast_json_set_alloc_funcs(void *(*malloc_fn)(size_t), void (*free_fn)(void*));
96
97 /*!
98  * \brief Change alloc funcs back to the resource module defaults.
99  * \since 12.0.0
100  *
101  * If you use ast_json_set_alloc_funcs() to temporarily change the allocator functions
102  * (i.e., from in a unit test), this function sets them back to ast_malloc() and
103  * ast_free().
104  */
105 void ast_json_reset_alloc_funcs(void);
106
107 /*!
108  * \struct ast_json
109  * \brief Abstract JSON element (object, array, string, int, ...).
110  * \since 12.0.0
111  */
112 struct ast_json;
113
114 /*!
115  * \brief Increase refcount on \a value.
116  * \since 12.0.0
117  *
118  * \param value JSON value to reference.
119  * \return The given \a value.
120  */
121 struct ast_json *ast_json_ref(struct ast_json *value);
122
123 /*!
124  * \brief Decrease refcount on \a value. If refcount reaches zero, \a value is freed.
125  * \since 12.0.0
126  */
127 void ast_json_unref(struct ast_json *value);
128
129 /*!@}*/
130
131 /*!@{*/
132
133 /*!
134  * \brief Valid types of a JSON element.
135  * \since 12.0.0
136  */
137 enum ast_json_type
138 {
139         AST_JSON_OBJECT,
140         AST_JSON_ARRAY,
141         AST_JSON_STRING,
142         AST_JSON_INTEGER,
143         AST_JSON_REAL,
144         AST_JSON_TRUE,
145         AST_JSON_FALSE,
146         AST_JSON_NULL,
147 };
148
149 /*!
150  * \brief Get the type of \a value.
151  * \since 12.0.0
152  * \param value Value to query.
153  * \return Type of \a value.
154  */
155 enum ast_json_type ast_json_typeof(const struct ast_json *value);
156
157 /*!@}*/
158
159 /*!@{*/
160
161 /*!
162  * \brief Get the JSON true value.
163  * \since 12.0.0
164  *
165  * The returned value is a singleton, and does not need to be
166  * ast_json_unref()'ed.
167  *
168  * \return JSON true.
169  */
170 struct ast_json *ast_json_true(void);
171
172 /*!
173  * \brief Get the JSON false value.
174  * \since 12.0.0
175  *
176  * The returned value is a singleton, and does not need to be
177  * ast_json_unref()'ed.
178  *
179  * \return JSON false.
180  */
181 struct ast_json *ast_json_false(void);
182
183 /*!
184  * \brief Get the JSON boolean corresponding to \a value.
185  * \since 12.0.0
186  * \return JSON true if value is true (non-zero).
187  * \return JSON false if value is false (zero).
188  */
189 struct ast_json *ast_json_boolean(int value);
190
191 /*!
192  * \brief Get the JSON null value.
193  * \since 12.0.0
194  *
195  * The returned value is a singleton, and does not need to be
196  * ast_json_unref()'ed.
197  *
198  * \return JSON null.
199  */
200 struct ast_json *ast_json_null(void);
201
202 /*!
203  * \brief Check if \a value is JSON true.
204  * \since 12.0.0
205  * \return True (non-zero) if \a value == \ref ast_json_true().
206  * \return False (zero) otherwise..
207  */
208 int ast_json_is_true(const struct ast_json *value);
209
210 /*!
211  * \brief Check if \a value is JSON false.
212  * \since 12.0.0
213  * \return True (non-zero) if \a value == \ref ast_json_false().
214  * \return False (zero) otherwise.
215  */
216 int ast_json_is_false(const struct ast_json *value);
217
218 /*!
219  * \brief Check if \a value is JSON null.
220  * \since 12.0.0
221  * \return True (non-zero) if \a value == \ref ast_json_false().
222  * \return False (zero) otherwise.
223  */
224 int ast_json_is_null(const struct ast_json *value);
225
226 /*!@}*/
227
228 /*!@{*/
229
230 /*!
231  * \brief Construct a JSON string from \a value.
232  * \since 12.0.0
233  *
234  * The given \a value must be a valid ASCII or UTF-8 encoded string.
235  *
236  * \param value Value of new JSON string.
237  * \return Newly constructed string element.
238  * \return \c NULL on error.
239  */
240 struct ast_json *ast_json_string_create(const char *value);
241
242 /*!
243  * \brief Get the value of a JSON string.
244  * \since 12.0.0
245  * \param string JSON string.
246  * \return Value of the string.
247  * \return \c NULL on error.
248  */
249 const char *ast_json_string_get(const struct ast_json *string);
250
251 /*!
252  * \brief Change the value of a JSON string.
253  * \since 12.0.0
254  *
255  * The given \a value must be a valid ASCII or UTF-8 encoded string.
256  *
257  * \param string JSON string to modify.
258  * \param value New value to store in \a string.
259  * \return 0 on success.
260  * \return -1 on error.
261  */
262 int ast_json_string_set(struct ast_json *string, const char *value);
263
264 /*!
265  * \brief Create a JSON string, printf style.
266  * \since 12.0.0
267  *
268  * The formatted value must be a valid ASCII or UTF-8 encoded string.
269  *
270  * \param format \c printf style format string.
271  * \return Newly allocated string.
272  * \return \c NULL on error.
273  */
274 struct ast_json *ast_json_stringf(const char *format, ...) __attribute__((format(printf, 1, 2)));
275
276 /*!
277  * \brief Create a JSON string, vprintf style.
278  * \since 12.0.0
279  *
280  * The formatted value must be a valid ASCII or UTF-8 encoded string.
281  *
282  * \param format \c printf style format string.
283  * \return Newly allocated string.
284  * \return \c NULL on error.
285  */
286 struct ast_json *ast_json_vstringf(const char *format, va_list args) __attribute__((format(printf, 1, 0)));
287
288 /*!@}*/
289
290 /*!@{*/
291
292 /*!
293  * \brief Create a JSON integer.
294  * \since 12.0.0
295  * \param value Value of the new JSON integer.
296  * \return Newly allocated integer.
297  * \return \c NULL on error.
298  */
299 struct ast_json *ast_json_integer_create(intmax_t value);
300
301 /*!
302  * \brief Get the value from a JSON integer.
303  * \since 12.0.0
304  * \param integer JSON integer.
305  * \return Value of a JSON integer.
306  * \return 0 if \a integer is not a JSON integer.
307  */
308 intmax_t ast_json_integer_get(const struct ast_json *integer);
309
310 /*!
311  * \brief Set the value of a JSON integer.
312  * \since 12.0.0
313  * \param integer JSON integer to modify.
314  * \param value New value for \a integer.
315  * \return 0 on success.
316  * \return -1 on error.
317  */
318 int ast_json_integer_set(struct ast_json *integer, intmax_t value);
319
320 /*!@}*/
321
322 /*!@{*/
323
324 /*!
325  * \brief Create a empty JSON array.
326  * \since 12.0.0
327  * \return Newly allocated array.
328  * \return \c NULL on error.
329  */
330 struct ast_json *ast_json_array_create(void);
331
332 /*!
333  * \brief Get the size of a JSON array.
334  * \since 12.0.0
335  * \param array JSON array.
336  * \return Size of \a array.
337  * \return 0 if array is not a JSON array.
338  */
339 size_t ast_json_array_size(const struct ast_json *array);
340
341 /*!
342  * \brief Get an element from an array.
343  * \since 12.0.0
344  *
345  * The returned element is a borrowed reference; use ast_json_ref() to safely keep a
346  * pointer to it.
347  *
348  * \param array JSON array.
349  * \param index Zero-based index into \a array.
350  * \return The specified element.
351  * \return \c NULL if \a array not an array.
352  * \return \c NULL if \a index is out of bounds.
353  */
354 struct ast_json *ast_json_array_get(const struct ast_json *array, size_t index);
355
356 /*!
357  * \brief Change an element in an array.
358  * \since 12.0.0
359  *
360  * The \a array steals the \a value reference; use ast_json_ref() to safely keep a pointer
361  * to it.
362  *
363  * \param array JSON array to modify.
364  * \param index Zero-based index into array.
365  * \param value New JSON value to store in \a array at \a index.
366  * \return 0 on success.
367  * \return -1 on error.
368  */
369 int ast_json_array_set(struct ast_json *array, size_t index, struct ast_json *value);
370
371 /*!
372  * \brief Append to an array.
373  * \since 12.0.0
374  *
375  * The array steals the \a value reference; use ast_json_ref() to safely keep a pointer
376  * to it.
377  *
378  * \param array JSON array to modify.
379  * \param value New JSON value to store at the end of \a array.
380  * \return 0 on success.
381  * \return -1 on error.
382  */
383 int ast_json_array_append(struct ast_json *array, struct ast_json *value);
384
385 /*!
386  * \brief Insert into an array.
387  * \since 12.0.0
388  *
389  * The array steals the \a value reference; use ast_json_ref() to safely keep a pointer
390  * to it.
391  *
392  * \param array JSON array to modify.
393  * \param index Zero-based index into array.
394  * \param value New JSON value to store in \a array at \a index.
395  * \return 0 on success.
396  * \return -1 on error.
397  */
398 int ast_json_array_insert(struct ast_json *array, size_t index, struct ast_json *value);
399
400 /*!
401  * \brief Remove an element from an array.
402  * \since 12.0.0
403  * \param array JSON array to modify.
404  * \param index Zero-based index into array.
405  * \return 0 on success.
406  * \return -1 on error.
407  */
408 int ast_json_array_remove(struct ast_json *array, size_t index);
409
410 /*!
411  * \brief Remove all elements from an array.
412  * \since 12.0.0
413  * \param array JSON array to clear.
414  * \return 0 on success.
415  * \return -1 on error.
416  */
417 int ast_json_array_clear(struct ast_json *array);
418
419 /*!
420  * \brief Append all elements from \a tail to \a array.
421  * \since 12.0.0
422  *
423  * The \a tail argument is not changed, so ast_json_unref() it when you are done with it.
424  *
425  * \param array JSON array to modify.
426  * \param tail JSON array with contents to append to \a array.
427  * \return 0 on success.
428  * \return -1 on error.
429  */
430 int ast_json_array_extend(struct ast_json *array, struct ast_json *tail);
431
432 /*!@}*/
433
434 /*!@{*/
435
436 /*!
437  * \brief Create a new JSON object.
438  * \since 12.0.0
439  * \return Newly allocated object.
440  * \return \c NULL on error.
441  */
442 struct ast_json *ast_json_object_create(void);
443
444 /*!
445  * \brief Get size of JSON object.
446  * \since 12.0.0
447  * \param object JSON object.
448  * \return Size of \a object.
449  * \return Zero of \a object is not a JSON object.
450  */
451 size_t ast_json_object_size(struct ast_json *object);
452
453 /*!
454  * \brief Get a field from a JSON object.
455  * \since 12.0.0
456  *
457  * The returned element is a borrowed reference; use ast_json_ref() to safely keep a
458  * pointer to it.
459  *
460  * \param object JSON object.
461  * \param key Key of field to look up.
462  * \return Value with given \a key.
463  * \return \c NULL on error.
464  */
465 struct ast_json *ast_json_object_get(struct ast_json *object, const char *key);
466
467 /*!
468  * \brief Set a field in a JSON object.
469  * \since 12.0.0
470  *
471  * The object steals the \a value reference; use ast_json_ref() to safely keep a pointer
472  * to it.
473  *
474  * \param object JSON object to modify.
475  * \param key Key of field to set.
476  * \param value JSON value to set for field.
477  * \return 0 on success.
478  * \return -1 on error.
479  */
480 int ast_json_object_set(struct ast_json *object, const char *key, struct ast_json *value);
481
482 /*!
483  * \brief Delete a field from a JSON object.
484  * \since 12.0.0
485  *
486  * \param object JSON object to modify.
487  * \param key Key of field to delete.
488  * \return 0 on success, or -1 if key does not exist.
489  */
490 int ast_json_object_del(struct ast_json *object, const char *key);
491
492 /*!
493  * \brief Delete all elements from a JSON object.
494  * \since 12.0.0
495  * \param object JSON object to clear.
496  * \return 0 on success.
497  * \return -1 on error.
498  */
499 int ast_json_object_clear(struct ast_json *object);
500
501 /*!
502  * \brief Update \a object with all of the fields of \a other.
503  * \since 12.0.0
504  *
505  * All of the fields of \a other are copied into \a object, overwriting existing keys.
506  * The \a other object is not changed, so ast_json_unref() it when you are done with it.
507  *
508  * \param object JSON object to modify.
509  * \param other JSON object to copy into \a object.
510  * \return 0 on success.
511  * \return -1 on error.
512  */
513 int ast_json_object_update(struct ast_json *object, struct ast_json *other);
514
515 /*!
516  * \brief Update existing fields in \a object with the fields of \a other.
517  * \since 12.0.0
518  *
519  * Like ast_json_object_update(), but only existing fields are updated. No new fields
520  * will get added. The \a other object is not changed, so ast_json_unref() it when you
521  * are done with it.
522  *
523  * \param object JSON object to modify.
524  * \param other JSON object to copy into \a object.
525  * \return 0 on success.
526  * \return -1 on error.
527  */
528 int ast_json_object_update_existing(struct ast_json *object, struct ast_json *other);
529
530 /*!
531  * \brief Add new fields to \a object with the fields of \a other.
532  * \since 12.0.0
533  *
534  * Like ast_json_object_update(), but only missing fields are added. No existing fields
535  * will be modified. The \a other object is not changed, so ast_json_unref() it when you
536  * are done with it.
537  *
538  * \param object JSON object to modify.
539  * \param other JSON object to copy into \a object.
540  * \return 0 on success.
541  * \return -1 on error.
542  */
543 int ast_json_object_update_missing(struct ast_json *object, struct ast_json *other);
544
545 /*!
546  * \struct ast_json_iter
547  * \brief Iterator for JSON object key/values.
548  * \since 12.0.0
549  *
550  * Note that iteration order is not specified, and may change as fields are added to
551  * and removed from the object.
552  */
553 struct ast_json_iter;
554
555 /*!
556  * \brief Get an iterator pointing to the first field in a JSON object.
557  * \since 12.0.0
558  *
559  * The order of the fields in an object are not specified. However, iterating forward
560  * from this iterator will cover all fields in \a object. Adding or removing fields from
561  * \a object may invalidate its iterators.
562  *
563  * \param object JSON object.
564  * \return Iterator to the first field in \a object.
565  * \return \c NULL \a object is empty.
566  * \return \c NULL on error.
567  */
568 struct ast_json_iter *ast_json_object_iter(struct ast_json *object);
569
570 /*!
571  * \brief Get an iterator pointing to a specified \a key in \a object.
572  * \since 12.0.0
573  *
574  * Iterating forward from this iterator may not to cover all elements in \a object.
575  *
576  * \param object JSON object to iterate.
577  * \param key Key of field to lookup.
578  * \return Iterator pointing to the field with the given \a key.
579  * \return \c NULL if \a key does not exist.
580  * \return \c NULL on error.
581  */
582 struct ast_json_iter *ast_json_object_iter_at(struct ast_json *object, const char *key);
583
584 /*!
585  * \brief Get the next iterator.
586  * \since 12.0.0
587  * \param object JSON object \a iter was obtained from.
588  * \param iter JSON object iterator.
589  * \return Iterator to next field in \a object.
590  * \return \c NULL if \a iter was the last field.
591  */
592 struct ast_json_iter *ast_json_object_iter_next(struct ast_json *object, struct ast_json_iter *iter);
593
594 /*!
595  * \brief Get the key from an iterator.
596  * \since 12.0.0
597  * \param iter JSON object iterator.
598  * \return Key of the field \a iter points to.
599  */
600 const char *ast_json_object_iter_key(struct ast_json_iter *iter);
601
602 /*!
603  * \brief Get the value from an iterator.
604  * \since 12.0.0
605  *
606  * The returned element is a borrowed reference; use ast_json_ref() to safely
607  * keep a pointer to it.
608  *
609  * \param iter JSON object iterator.
610  * \return Value of the field \a iter points to.
611  */
612 struct ast_json *ast_json_object_iter_value(struct ast_json_iter *iter);
613
614 /*!
615  * \brief Set the value of the field pointed to by an iterator.
616  * \since 12.0.0
617  *
618  * The array steals the value reference; use ast_json_ref() to safely keep a
619  * pointer to it.
620  *
621  * \param object JSON object \a iter was obtained from.
622  * \param iter JSON object iterator.
623  * \param value JSON value to store in \iter's field.
624  * \return 0 on success.
625  * \return -1 on error.
626  */
627 int ast_json_object_iter_set(struct ast_json *object, struct ast_json_iter *iter, struct ast_json *value);
628
629 /*!@}*/
630
631 /*!@{*/
632
633 /*!
634  * \brief Encoding format type.
635  * \since 12.0.0
636  */
637 enum ast_json_encoding_format
638 {
639         /*! Compact format, low human readability */
640         AST_JSON_COMPACT,
641         /*! Formatted for human readability */
642         AST_JSON_PRETTY,
643 };
644
645 #define ast_json_dump_string(root) ast_json_dump_string_format(root, AST_JSON_COMPACT)
646
647 /*!
648  * \brief Encode a JSON value to a string.
649  * \since 12.0.0
650  *
651  * Returned string must be freed by calling ast_free().
652  *
653  * \param root JSON value.
654  * \param format encoding format type.
655  * \return String encoding of \a root.
656  * \return \c NULL on error.
657  */
658 char *ast_json_dump_string_format(struct ast_json *root, enum ast_json_encoding_format format);
659
660 #define ast_json_dump_str(root, dst) ast_json_dump_str_format(root, dst, AST_JSON_COMPACT)
661
662 /*!
663  * \brief Encode a JSON value to an \ref ast_str.
664  * \since 12.0.0
665  *
666  * If \a dst is too small, it will be grown as needed.
667  *
668  * \param root JSON value.
669  * \param dst \ref ast_str to store JSON encoding.
670  * \param format encoding format type.
671  * \return 0 on success.
672  * \return -1 on error. The contents of \a dst are undefined.
673  */
674 int ast_json_dump_str_format(struct ast_json *root, struct ast_str **dst, enum ast_json_encoding_format format);
675
676 #define ast_json_dump_file(root, output) ast_json_dump_file_format(root, output, AST_JSON_COMPACT)
677
678 /*!
679  * \brief Encode a JSON value to a \c FILE.
680  * \since 12.0.0
681  *
682  * \param root JSON value.
683  * \param output File to write JSON encoding to.
684  * \param format encoding format type.
685  * \return 0 on success.
686  * \return -1 on error. The contents of \a output are undefined.
687  */
688 int ast_json_dump_file_format(struct ast_json *root, FILE *output, enum ast_json_encoding_format format);
689
690 #define ast_json_dump_new_file(root, path) ast_json_dump_new_file_format(root, path, AST_JSON_COMPACT)
691
692 /*!
693  * \brief Encode a JSON value to a file at the given location.
694  * \since 12.0.0
695  *
696  * \param root JSON value.
697  * \param path Path to file to write JSON encoding to.
698  * \param format encoding format type.
699  * \return 0 on success.
700  * \return -1 on error. The contents of \a output are undefined.
701  */
702 int ast_json_dump_new_file_format(struct ast_json *root, const char *path, enum ast_json_encoding_format format);
703
704 #define AST_JSON_ERROR_TEXT_LENGTH    160
705 #define AST_JSON_ERROR_SOURCE_LENGTH   80
706
707 /*!
708  * \brief JSON parsing error information.
709  * \since 12.0.0
710  */
711 struct ast_json_error {
712         /*! Line number error occured on */
713         int line;
714         /*! Character (not byte, can be different for UTF-8) column on which the error occurred. */
715         int column;
716         /*! Position in bytes from start of input */
717         int position;
718         /*! Error message */
719         char text[AST_JSON_ERROR_TEXT_LENGTH];
720         /*! Source of the error (filename or <string>) */
721         char source[AST_JSON_ERROR_TEXT_LENGTH];
722 };
723
724 /*!
725  * \brief Parse null terminated string into a JSON object or array.
726  * \since 12.0.0
727  * \param input String to parse.
728  * \param[out] error Filled with information on error.
729  * \return Parsed JSON element.
730  * \return \c NULL on error.
731  */
732 struct ast_json *ast_json_load_string(const char *input, struct ast_json_error *error);
733
734 /*!
735  * \brief Parse \ref ast_str into a JSON object or array.
736  * \since 12.0.0
737  * \param input \ref ast_str to parse.
738  * \param[out] error Filled with information on error.
739  * \return Parsed JSON element.
740  * \return \c NULL on error.
741  */
742 struct ast_json *ast_json_load_str(const struct ast_str *input, struct ast_json_error *error);
743
744 /*!
745  * \brief Parse buffer with known length into a JSON object or array.
746  * \since 12.0.0
747  * \param buffer Buffer to parse.
748  * \param buflen Length of \a buffer.
749  * \param[out] error Filled with information on error.
750  * \return Parsed JSON element.
751  * \return \c NULL on error.
752  */
753 struct ast_json *ast_json_load_buf(const char *buffer, size_t buflen, struct ast_json_error *error);
754
755 /*!
756  * \brief Parse a \c FILE into JSON object or array.
757  * \since 12.0.0
758  * \param input \c FILE to parse.
759  * \param[out] error Filled with information on error.
760  * \return Parsed JSON element.
761  * \return \c NULL on error.
762  */
763 struct ast_json *ast_json_load_file(FILE *input, struct ast_json_error *error);
764
765 /*!
766  * \brief Parse file at \a path into JSON object or array.
767  * \since 12.0.0
768  * \param path Path of file to parse.
769  * \param[out] error Filled with information on error.
770  * \return Parsed JSON element.
771  * \return \c NULL on error.
772  */
773 struct ast_json *ast_json_load_new_file(const char *path, struct ast_json_error *error);
774
775 /*!
776  * \brief Helper for creating complex JSON values.
777  * \since 12.0.0
778  *
779  * See original Jansson docs at http://www.digip.org/jansson/doc/2.4/apiref.html#apiref-pack
780  * for more details.
781  */
782 struct ast_json *ast_json_pack(char const *format, ...);
783
784 /*!
785  * \brief Helper for creating complex JSON values simply.
786  * \since 12.0.0
787  *
788  * See original Jansson docs at http://www.digip.org/jansson/doc/2.4/apiref.html#apiref-pack
789  * for more details.
790  */
791 struct ast_json *ast_json_vpack(char const *format, va_list ap);
792
793 /*!@}*/
794
795 /*!@{*/
796
797 /*!
798  * \brief Compare two JSON objects.
799  * \since 12.0.0
800  *
801  * Two JSON objects are equal if they are of the same type, and their contents are equal.
802  *
803  * \param lhs Value to compare.
804  * \param rhs Other value to compare.
805  * \return True (non-zero) if \a lhs and \a rhs are equal.
806  * \return False (zero) if they are not.
807  */
808 int ast_json_equal(const struct ast_json *lhs, const struct ast_json *rhs);
809
810 /*!
811  * \brief Copy a JSON value, but not its children.
812  * \since 12.0.0
813  *
814  * If \a value is a JSON object or array, its children are shared with the returned copy.
815  *
816  * \param value JSON value to copy.
817  * \return Shallow copy of \a value.
818  * \return \c NULL on error.
819  */
820 struct ast_json *ast_json_copy(const struct ast_json *value);
821
822 /*!
823  * \brief Copy a JSON value, and its children.
824  * \since 12.0.0
825  *
826  * If \a value is a JSON object or array, they are also copied.
827  *
828  * \param value JSON value to copy.
829  * \return Deep copy of \a value.
830  * \return \c NULL on error.
831  */
832 struct ast_json *ast_json_deep_copy(const struct ast_json *value);
833
834 /*!@}*/
835
836 /*!@{*/
837
838 /*!
839  * \brief Common JSON rendering functions for common 'objects'.
840  */
841
842 /*!
843  * \brief Simple name/number pair.
844  * \param name Name
845  * \param number Number
846  * \return NULL if error (non-UTF8 characters, NULL inputs, etc.)
847  * \return JSON object with name and number fields
848  */
849 struct ast_json *ast_json_name_number(const char *name, const char *number);
850
851 /*!
852  * \brief Construct a timeval as JSON.
853  *
854  * JSON does not define a standard date format (boo), but the de facto standard
855  * is to use ISO 8601 formatted string. We build a millisecond resolution string
856  * from the \c timeval
857  *
858  * \param tv \c timeval to encode.
859  * \param zone Text string of a standard system zoneinfo file.  If NULL, the system localtime will be used.
860  * \return JSON string with ISO 8601 formatted date/time.
861  * \return \c NULL on error.
862  */
863 struct ast_json *ast_json_timeval(const struct timeval tv, const char *zone);
864
865 /*!
866  * \brief Construct a context/exten/priority as JSON.
867  *
868  * If a \c NULL is passed for \c context or \c exten, or -1 for \c priority,
869  * the fields is set to ast_json_null().
870  *
871  * \param context Context name.
872  * \param exten Extension.
873  * \param priority Dialplan priority.
874  * \return JSON object with \c context, \c exten and \c priority fields
875  */
876 struct ast_json *ast_json_dialplan_cep(const char *context, const char *exten, int priority);
877
878 struct ast_json_payload {
879         struct ast_json *json;
880 };
881
882 /*!
883  * \brief Create an ao2 object to pass json blobs as data payloads for stasis
884  * \since 12.0.0
885  *
886  * \param json the ast_json blob we are loading
887  *
888  * \retval NULL if we fail to alloc it
889  * \retval pointer to the ast_json_payload created
890  */
891 struct ast_json_payload *ast_json_payload_create(struct ast_json *json);
892
893 /*!@}*/
894
895 #endif /* _ASTERISK_JSON_H */