libpjproject-dev 2.7.2~dfsg-1 / usr / include / pjlib-util / json.h

/* $Id: json.h 4704 2014-01-16 05:30:46Z ming $ */
/*
 * 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__ */