voice-gateway-service/pjproject/pjlib-util/include/pjlib-util/json.h

/*
 * 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__ */