# json_tokener.h File Reference

## Data Structures
struct | json_tokener_srec
struct | json_tokener
## Defines
#define | JSON_TOKENER_MAX_DEPTH 32
## Enumerations
enum | json_tokener_error { json_tokener_success, json_tokener_continue, json_tokener_error_depth, json_tokener_error_parse_eof, json_tokener_error_parse_unexpected, json_tokener_error_parse_null, json_tokener_error_parse_boolean, json_tokener_error_parse_number, json_tokener_error_parse_array, json_tokener_error_parse_object_key_name, json_tokener_error_parse_object_key_sep, json_tokener_error_parse_object_value_sep, json_tokener_error_parse_string, json_tokener_error_parse_comment }
enum | json_tokener_state { json_tokener_state_eatws, json_tokener_state_start, json_tokener_state_finish, json_tokener_state_null, json_tokener_state_comment_start, json_tokener_state_comment, json_tokener_state_comment_eol, json_tokener_state_comment_end, json_tokener_state_string, json_tokener_state_string_escape, json_tokener_state_escape_unicode, json_tokener_state_boolean, json_tokener_state_number, json_tokener_state_array, json_tokener_state_array_add, json_tokener_state_array_sep, json_tokener_state_object_field_start, json_tokener_state_object_field, json_tokener_state_object_field_end, json_tokener_state_object_value, json_tokener_state_object_value_add, json_tokener_state_object_sep }
## Functions
const char * | json_tokener_error_desc (enum json_tokener_error jerr)
enum json_tokener_error | json_tokener_get_error (struct json_tokener *tok)
struct json_tokener * | json_tokener_new (void)
void | json_tokener_free (struct json_tokener *tok)
void | json_tokener_reset (struct json_tokener *tok)
struct json_object * | json_tokener_parse (const char *str)
struct json_object * | json_tokener_parse_verbose (const char *str, enum json_tokener_error *error)
struct json_object * | json_tokener_parse_ex (struct json_tokener *tok, const char *str, int len)
## Variables
const char * | json_tokener_errors []

## Define Documentation

#define JSON_TOKENER_MAX_DEPTH 32

## Enumeration Type Documentation

enum json_tokener_error

Enumerator:

  json_tokener_success |
  json_tokener_continue |
  json_tokener_error_depth |
  json_tokener_error_parse_eof |
  json_tokener_error_parse_unexpected |
  json_tokener_error_parse_null |
  json_tokener_error_parse_boolean |
  json_tokener_error_parse_number |
  json_tokener_error_parse_array |
  json_tokener_error_parse_object_key_name |
  json_tokener_error_parse_object_key_sep |
  json_tokener_error_parse_object_value_sep |
  json_tokener_error_parse_string |
  json_tokener_error_parse_comment |

enum json_tokener_state

Enumerator:

  json_tokener_state_eatws |
  json_tokener_state_start |
  json_tokener_state_finish |
  json_tokener_state_null |
  json_tokener_state_comment_start |
  json_tokener_state_comment |
  json_tokener_state_comment_eol |
  json_tokener_state_comment_end |
  json_tokener_state_string |
  json_tokener_state_string_escape |
  json_tokener_state_escape_unicode |
  json_tokener_state_boolean |
  json_tokener_state_number |
  json_tokener_state_array |
  json_tokener_state_array_add |
  json_tokener_state_array_sep |
  json_tokener_state_object_field_start |
  json_tokener_state_object_field |
  json_tokener_state_object_field_end |
  json_tokener_state_object_value |
  json_tokener_state_object_value_add |
  json_tokener_state_object_sep |

## Function Documentation

const char* json_tokener_error_desc | ( | enum json_tokener_error | jerr | ) |

Given an error previously returned by json_tokener_get_error(), return a human readable description of the error.

Returns:
  a generic error message is returned if an invalid error value is provided.

void json_tokener_free | ( | struct json_tokener * | tok | ) |

enum json_tokener_error json_tokener_get_error | ( | struct json_tokener * | tok | ) |

Retrieve the error caused by the last call to json_tokener_parse_ex(), or json_tokener_success if there is no error.

When parsing a JSON string in pieces, if the tokener is in the middle of parsing this will return json_tokener_continue.

See also json_tokener_error_desc().

struct json_tokener* json_tokener_new | ( | void |  | ) | `[read]`

struct json_object* json_tokener_parse | ( | const char * | str | ) | `[read]`

struct json_object* json_tokener_parse_ex | ( | struct json_tokener * | tok,
|  | const char * | str,
|  | int | len |
| ) |  |  | `[read]`

Parse a string and return a non-NULL json_object if a valid JSON value is found. The string does not need to be a JSON object or array; it can also be a string, number or boolean value.

A partial JSON string can be parsed. If the parsing is incomplete, NULL will be returned and json_tokener_get_error() will be return json_tokener_continue. json_tokener_parse_ex() can then be called with additional bytes in str to continue the parsing.

If json_tokener_parse_ex() returns NULL and the error anything other than json_tokener_continue, a fatal error has occurred and parsing must be halted. Then tok object must not be re-used until json_tokener_reset() is called.

When a valid JSON value is parsed, a non-NULL json_object will be returned. Also, json_tokener_get_error() will return json_tokener_success. Be sure to check the type with json_object_is_type() or json_object_get_type() before using the object.

XXX this shouldn't use internal fields: Trailing characters after the parsed value do not automatically cause an error. It is up to the caller to decide whether to treat this as an error or to handle the additional characters, perhaps by parsing another json value starting from that point.

Extra characters can be detected by comparing the tok->char_offset against the length of the last len parameter passed in.

The tokener does not maintain an internal buffer so the caller is responsible for calling json_tokener_parse_ex with an appropriate str parameter starting with the extra characters.

Example:

    json_object *jobj = NULL;
    const char *mystring = NULL;
    int stringlen = 0;
    enum json_tokener_error jerr;
    do {
            mystring = ...  // get JSON string, e.g. read from file, etc...
            stringlen = strlen(mystring);
            jobj = json_tokener_parse_ex(tok, mystring, stringlen);
    } while ((jerr = json_tokener_get_error(tok)) == json_tokener_continue);
    if (jerr != json_tokener_success)
    {
            fprintf(stderr, "Error: %s\n", json_tokener_error_desc(jerr));
            // Handle errors, as appropriate for your application.
    }
    if (tok->char_offset < stringlen) // XXX shouldn't access internal fields
    {
            // Handle extra characters after parsed object as desired.
            // e.g. issue an error, parse another object from that point, etc...
    }
    // Success, use jobj here.

Parameters:

  | tok | a json_tokener previously allocated with json_tokener_new()
  | str | an string with any valid JSON expression, or portion of. This does not need to be null terminated.
  | len | the length of str

struct json_object* json_tokener_parse_verbose | ( | const char * | str,
|  | enum json_tokener_error * | error |
| ) |  |  | `[read]`

void json_tokener_reset | ( | struct json_tokener * | tok | ) |

## Variable Documentation

const char* json_tokener_errors[]

XXX do not use json_tokener_errors directly. After v0.10 this will be removed.

See json_tokener_error_desc() instead.