yajl_parse.h File Reference

#include <yajl/yajl_common.h>

Go to the source code of this file.

Data Structures
struct	yajl_callbacks
struct	yajl_parser_config
Typedefs
typedef struct yajl_handle_t *	yajl_handle
Enumerations
enum	yajl_status { yajl_status_ok, yajl_status_client_canceled, yajl_status_insufficient_data, yajl_status_error }
Functions
YAJL_API const char *	yajl_status_to_string (yajl_status code)
YAJL_API yajl_handle	yajl_alloc (const yajl_callbacks *callbacks, const yajl_parser_config *config, const yajl_alloc_funcs *allocFuncs, void *ctx)
YAJL_API void	yajl_free (yajl_handle handle)
YAJL_API yajl_status	yajl_parse (yajl_handle hand, const unsigned char *jsonText, unsigned int jsonTextLength)
YAJL_API yajl_status	yajl_parse_complete (yajl_handle hand)
YAJL_API unsigned char *	yajl_get_error (yajl_handle hand, int verbose, const unsigned char *jsonText, unsigned int jsonTextLength)
YAJL_API unsigned int	yajl_get_bytes_consumed (yajl_handle hand)
YAJL_API void	yajl_free_error (yajl_handle hand, unsigned char *str)

---

Detailed Description

Interface to YAJL's JSON parsing facilities.

---

Typedef Documentation

typedef struct yajl_handle_t* yajl_handle

an opaque handle to a parser

---

Enumeration Type Documentation

enum yajl_status

error codes returned from this interface

Enumerator:

yajl_status_ok	no error was encountered
yajl_status_client_canceled	a client callback returned zero, stopping the parse
yajl_status_insufficient_data	The parse cannot yet complete because more json input text is required, call yajl_parse with the next buffer of input text. (pertinent only when stream parsing)
yajl_status_error	An error occured during the parse. Call yajl_get_error for more information about the encountered error

---

Function Documentation

YAJL_API yajl_handle yajl_alloc	(	const yajl_callbacks *	callbacks,
		const yajl_parser_config *	config,
		const yajl_alloc_funcs *	allocFuncs,
		void *	ctx
	)

allocate a parser handle

Parameters:

callbacks	a yajl callbacks structure specifying the functions to call when different JSON entities are encountered in the input text. May be NULL, which is only useful for validation.
config	configuration parameters for the parse.
ctx	a context pointer that will be passed to callbacks.

YAJL_API void yajl_free

(

yajl_handle

handle

)

free a parser handle

YAJL_API void yajl_free_error	(	yajl_handle	hand,
		unsigned char *	str
	)

free an error returned from yajl_get_error

YAJL_API unsigned int yajl_get_bytes_consumed

(

yajl_handle

hand

)

get the amount of data consumed from the last chunk passed to YAJL.

In the case of a successful parse this can help you understand if the entire buffer was consumed (which will allow you to handle "junk at end of input".

In the event an error is encountered during parsing, this function affords the client a way to get the offset into the most recent chunk where the error occured. 0 will be returned if no error was encountered.

YAJL_API unsigned char* yajl_get_error	(	yajl_handle	hand,
		int	verbose,
		const unsigned char *	jsonText,
		unsigned int	jsonTextLength
	)

get an error string describing the state of the parse.

If verbose is non-zero, the message will include the JSON text where the error occured, along with an arrow pointing to the specific char.

Returns:

A dynamically allocated string will be returned which should be freed with yajl_free_error

YAJL_API yajl_status yajl_parse	(	yajl_handle	hand,
		const unsigned char *	jsonText,
		unsigned int	jsonTextLength
	)

Parse some json!

Parameters:

hand	- a handle to the json parser allocated with yajl_alloc
jsonText	- a pointer to the UTF8 json text to be parsed
jsonTextLength	- the length, in bytes, of input text

YAJL_API yajl_status yajl_parse_complete

(

yajl_handle

hand

)

Parse any remaining buffered json. Since yajl is a stream-based parser, without an explicit end of input, yajl sometimes can't decide if content at the end of the stream is valid or not. For example, if "1" has been fed in, yajl can't know whether another digit is next or some character that would terminate the integer token.

Parameters:

hand	- a handle to the json parser allocated with yajl_alloc

YAJL_API const char* yajl_status_to_string

(

yajl_status

code

)

attain a human readable, english, string for an error