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