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