diff options
Diffstat (limited to 'pjlib-util/include/pjlib-util/json.h')
| -rw-r--r-- | pjlib-util/include/pjlib-util/json.h | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/pjlib-util/include/pjlib-util/json.h b/pjlib-util/include/pjlib-util/json.h new file mode 100644 index 00000000..56d55b46 --- /dev/null +++ b/pjlib-util/include/pjlib-util/json.h @@ -0,0 +1,228 @@ +/* $Id$ */ +/* + * Copyright (C) 2013 Teluu Inc. (http://www.teluu.com) + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJLIB_UTIL_JSON_H__ +#define __PJLIB_UTIL_JSON_H__ + + +/** + * @file json.h + * @brief PJLIB JSON Implementation + */ + +#include <pj/types.h> +#include <pj/list.h> +#include <pj/pool.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJ_JSON JSON Writer and Loader + * @ingroup PJ_FILE_FMT + * @{ + * This API implements JSON file format according to RFC 4627. It can be used + * to parse, write, and manipulate JSON documents. + */ + +/** + * Type of JSON value. + */ +typedef enum pj_json_val_type +{ + PJ_JSON_VAL_NULL, /**< Null value (null) */ + PJ_JSON_VAL_BOOL, /**< Boolean value (true, false) */ + PJ_JSON_VAL_NUMBER, /**< Numeric (float or fixed point) */ + PJ_JSON_VAL_STRING, /**< Literal string value. */ + PJ_JSON_VAL_ARRAY, /**< Array */ + PJ_JSON_VAL_OBJ /**< Object. */ +} pj_json_val_type; + +/* Forward declaration for JSON element */ +typedef struct pj_json_elem pj_json_elem; + +/** + * JSON list to store child elements. + */ +typedef struct pj_json_list +{ + PJ_DECL_LIST_MEMBER(pj_json_elem); +} pj_json_list; + +/** + * This represents JSON element. A JSON element is basically a name/value + * pair, where the name is a string and the value can be one of null, boolean + * (true and false constants), number, string, array (containing zero or more + * elements), or object. An object can be viewed as C struct, that is a + * compound element containing other elements, each having name/value pair. + */ +struct pj_json_elem +{ + PJ_DECL_LIST_MEMBER(pj_json_elem); + pj_str_t name; /**< ELement name. */ + pj_json_val_type type; /**< Element type. */ + union + { + pj_bool_t is_true; /**< Boolean value. */ + float num; /**< Number value. */ + pj_str_t str; /**< String value. */ + pj_json_list children; /**< Object and array children */ + } value; /**< Element value. */ +}; + +/** + * Structure to be specified to pj_json_parse() to be filled with additional + * info when parsing failed. + */ +typedef struct pj_json_err_info +{ + unsigned line; /**< Line location of the error */ + unsigned col; /**< Column location of the error */ + int err_char; /**< The offending character. */ +} pj_json_err_info; + +/** + * Type of function callback to write JSON document in pj_json_writef(). + * + * @param s The string to be written to the document. + * @param size The length of the string + * @param user_data User data that was specified to pj_json_writef() + * + * @return If the callback returns non-PJ_SUCCESS, it will + * stop the pj_json_writef() function and this error + * will be returned to caller. + */ +typedef pj_status_t (*pj_json_writer)(const char *s, + unsigned size, + void *user_data); + +/** + * Initialize null element. + * + * @param el The element. + * @param name Name to be given to the element, or NULL. + */ +PJ_DECL(void) pj_json_elem_null(pj_json_elem *el, pj_str_t *name); + +/** + * Initialize boolean element with the specified value. + * + * @param el The element. + * @param name Name to be given to the element, or NULL. + * @param val The value. + */ +PJ_DECL(void) pj_json_elem_bool(pj_json_elem *el, pj_str_t *name, + pj_bool_t val); + +/** + * Initialize number element with the specified value. + * + * @param el The element. + * @param name Name to be given to the element, or NULL. + * @param val The value. + */ +PJ_DECL(void) pj_json_elem_number(pj_json_elem *el, pj_str_t *name, + float val); + +/** + * Initialize string element with the specified value. + * + * @param el The element. + * @param name Name to be given to the element, or NULL. + * @param val The value. + */ +PJ_DECL(void) pj_json_elem_string(pj_json_elem *el, pj_str_t *name, + pj_str_t *val); + +/** + * Initialize element as an empty array + * + * @param el The element. + * @param name Name to be given to the element, or NULL. + */ +PJ_DECL(void) pj_json_elem_array(pj_json_elem *el, pj_str_t *name); + +/** + * Initialize element as an empty object + * + * @param el The element. + * @param name Name to be given to the element, or NULL. + */ +PJ_DECL(void) pj_json_elem_obj(pj_json_elem *el, pj_str_t *name); + +/** + * Add an element to an object or array. + * + * @param el The object or array element. + * @param child Element to be added to the object or array. + */ +PJ_DECL(void) pj_json_elem_add(pj_json_elem *el, pj_json_elem *child); + +/** + * Parse a JSON document in the buffer. The buffer MUST be NULL terminated, + * or if not then it must have enough size to put the NULL character. + * + * @param pool The pool to allocate memory for creating elements. + * @param buffer String buffer containing JSON document. + * @param size Size of the document. + * @param err_info Optional structure to be filled with info when + * parsing failed. + * + * @return The root element from the document. + */ +PJ_DECL(pj_json_elem*) pj_json_parse(pj_pool_t *pool, + char *buffer, + unsigned *size, + pj_json_err_info *err_info); + +/** + * Write the specified element to the string buffer. + * + * @param elem The element to be written. + * @param buffer Output buffer. + * @param size On input, it must be set to the size of the buffer. + * Upon successful return, this will be set to + * the length of the written string. + * + * @return PJ_SUCCESS on success or the appropriate error. + */ +PJ_DECL(pj_status_t) pj_json_write(const pj_json_elem *elem, + char *buffer, unsigned *size); + +/** + * Incrementally write the element to arbitrary medium using the specified + * callback to write the document chunks. + * + * @param elem The element to be written. + * @param writer Callback function which will be called to write + * text chunks. + * @param user_data Arbitrary user data which will be given back when + * calling the callback. + * + * @return PJ_SUCCESS on success or the appropriate error. + */ +PJ_DECL(pj_status_t) pj_json_writef(const pj_json_elem *elem, + pj_json_writer writer, + void *user_data); + +/** + * @} + */ + +PJ_END_DECL + +#endif /* __PJLIB_UTIL_JSON_H__ */ |