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