/* $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 #include #include 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__ */