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