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