JSON Encoding and Decoding

Data Structures
struct	apr_json_string_t
struct	apr_json_value_t
struct	apr_json_kv_t
struct	apr_json_object_t
struct	apr_json_array_t

Macros
#define	APR_JSON_VALUE_STRING   (-1)
#define	APR_JSON_FLAGS_NONE   0
#define	APR_JSON_FLAGS_WHITESPACE   1
#define	APR_JSON_FLAGS_STRICT   2

Typedefs
typedef struct apr_json_object_t	apr_json_object_t
typedef struct apr_json_array_t	apr_json_array_t
typedef enum apr_json_type_e	apr_json_type_e
typedef struct apr_json_string_t	apr_json_string_t
typedef struct apr_json_value_t	apr_json_value_t
typedef struct apr_json_kv_t	apr_json_kv_t

Enumerations
enum	apr_json_type_e {   APR_JSON_OBJECT , APR_JSON_ARRAY , APR_JSON_STRING , APR_JSON_LONG ,   APR_JSON_DOUBLE , APR_JSON_BOOLEAN , APR_JSON_NULL }

Functions
apr_json_value_t *	apr_json_value_create (apr_pool_t *pool) __attribute__((nonnull(1)))
apr_json_value_t *	apr_json_string_create (apr_pool_t *pool, const char *val, apr_ssize_t len) __attribute__((nonnull(1)))
apr_json_value_t *	apr_json_array_create (apr_pool_t *pool, int nelts) __attribute__((nonnull(1)))
apr_json_value_t *	apr_json_object_create (apr_pool_t *pool) __attribute__((nonnull(1)))
apr_json_value_t *	apr_json_long_create (apr_pool_t *pool, apr_int64_t lnumber) __attribute__((nonnull(1)))
apr_json_value_t *	apr_json_double_create (apr_pool_t *pool, double dnumber) __attribute__((nonnull(1)))
apr_json_value_t *	apr_json_boolean_create (apr_pool_t *pool, int boolean) __attribute__((nonnull(1)))
apr_json_value_t *	apr_json_null_create (apr_pool_t *pool) __attribute__((nonnull(1)))
apr_status_t	apr_json_object_set (apr_json_value_t *obj, const char *key, apr_ssize_t klen, apr_json_value_t *val, apr_pool_t *pool) __attribute__((nonnull(1
apr_status_t apr_status_t	apr_json_object_set_ex (apr_json_value_t *obj, apr_json_value_t *key, apr_json_value_t *val, apr_pool_t *pool) __attribute__((nonnull(1
apr_status_t apr_status_t apr_json_kv_t *	apr_json_object_get (apr_json_value_t *obj, const char *key, apr_ssize_t klen) __attribute__((nonnull(1
apr_status_t apr_status_t apr_json_kv_t apr_json_kv_t *	apr_json_object_first (apr_json_value_t *obj) __attribute__((nonnull(1)))
apr_json_kv_t *	apr_json_object_next (apr_json_value_t *obj, apr_json_kv_t *kv) __attribute__((nonnull(1
apr_json_kv_t apr_status_t	apr_json_array_add (apr_json_value_t *arr, apr_json_value_t *val) __attribute__((nonnull(1
apr_json_kv_t apr_status_t apr_json_value_t *	apr_json_array_get (apr_json_value_t *arr, int index) __attribute__((nonnull(1)))
apr_json_value_t *	apr_json_array_first (const apr_json_value_t *arr) __attribute__((nonnull(1)))
apr_json_value_t *	apr_json_array_next (const apr_json_value_t *arr, const apr_json_value_t *val) __attribute__((nonnull(1
apr_json_value_t apr_status_t	apr_json_decode (apr_json_value_t **retval, const char *injson, apr_ssize_t size, apr_off_t *offset, int flags, int level, apr_pool_t *pool) __attribute__((nonnull(1
apr_json_value_t apr_status_t apr_status_t	apr_json_encode (apr_bucket_brigade *brigade, apr_brigade_flush flush, void *ctx, const apr_json_value_t *json, int flags, apr_pool_t *pool) __attribute__((nonnull(1
apr_json_value_t apr_status_t apr_status_t apr_json_value_t *	apr_json_overlay (apr_pool_t *p, apr_json_value_t *overlay, apr_json_value_t *base, int flags) __attribute__((nonnull(1)))

Detailed Description

Macro Definition Documentation

APR_JSON_FLAGS_NONE

#define APR_JSON_FLAGS_NONE   0

Flag indicating no special processing.

APR_JSON_FLAGS_STRICT

#define APR_JSON_FLAGS_STRICT   2

Flag indicating strict overlay.

APR_JSON_FLAGS_WHITESPACE

#define APR_JSON_FLAGS_WHITESPACE   1

Flag indicating include whitespace.

APR_JSON_VALUE_STRING

#define APR_JSON_VALUE_STRING   (-1)

When passing a string to one of the encode functions, this value can be passed to indicate a string-valued key, and have the length computed automatically.

Typedef Documentation

apr_json_array_t

typedef struct apr_json_array_t apr_json_array_t

A structure to hold a JSON array.

apr_json_kv_t

typedef struct apr_json_kv_t apr_json_kv_t

A structure to hold a JSON object key value pair.

Use apr_json_object_set() to allocate.

apr_json_object_t

typedef struct apr_json_object_t apr_json_object_t

A structure to hold a JSON object.

apr_json_string_t

typedef struct apr_json_string_t apr_json_string_t

A structure to hold a UTF-8 encoded JSON string.

apr_json_type_e

typedef enum apr_json_type_e apr_json_type_e

Enum that represents the type of the given JSON value.

apr_json_value_t

typedef struct apr_json_value_t apr_json_value_t

A structure that holds a JSON value.

Use apr_json_value_create() to allocate.

Enumeration Type Documentation

apr_json_type_e

enum apr_json_type_e

Enum that represents the type of the given JSON value.

Enumerator
APR_JSON_OBJECT
APR_JSON_ARRAY
APR_JSON_STRING
APR_JSON_LONG
APR_JSON_DOUBLE
APR_JSON_BOOLEAN
APR_JSON_NULL

Function Documentation

apr_json_array_add()

apr_json_kv_t apr_status_t apr_json_array_add	(	apr_json_value_t *	arr,
		apr_json_value_t *	val
	)

Add the value to the end of this array.

Parameters

arr	The JSON array.
val	Value to add to the array.

Returns

APR_SUCCESS on success, APR_EINVAL if the array value is not an APR_JSON_ARRAY.

apr_json_array_create()

apr_json_value_t* apr_json_array_create	(	apr_pool_t *	pool,
		int	nelts
	)

Allocate and return a JSON array.

Parameters

pool	The pool to allocate from.
nelts	the number of elements in the initial array

Returns

The apr_json_value_t structure.

apr_json_array_first()

apr_json_value_t* apr_json_array_first

(

const apr_json_value_t *

arr

)

Get the first value associated with an array.

If the value is an array, this function returns the first value.

Parameters

arr	The JSON array.

Returns

Returns the first value, or NULL if not an array, or the array is empty.

apr_json_array_get()

apr_json_kv_t apr_status_t apr_json_value_t* apr_json_array_get	(	apr_json_value_t *	arr,
		int	index
	)

Look up the value associated with a key in a JSON object.

Parameters

arr	The JSON array.
index	The index of the element in the array.

Returns

Returns NULL if the element is out of bounds.

apr_json_array_next()

apr_json_value_t* apr_json_array_next	(	const apr_json_value_t *	arr,
		const apr_json_value_t *	val
	)

Get the next value associated with an array.

This function returns the next value in the array, or NULL if no more values are present.

Parameters

arr	The JSON array.
val	The previous element of the array.

Returns

Returns the next value in the array, or NULL if not an array, or we have reached the end of the array.

apr_json_boolean_create()

apr_json_value_t* apr_json_boolean_create	(	apr_pool_t *	pool,
		int	boolean
	)

Allocate and return a JSON boolean.

Parameters

pool	The pool to allocate from.
boolean	The boolean value.

Returns

The apr_json_value_t structure.

apr_json_decode()

apr_json_value_t apr_status_t apr_json_decode	(	apr_json_value_t **	retval,
		const char *	injson,
		apr_ssize_t	size,
		apr_off_t *	offset,
		int	flags,
		int	level,
		apr_pool_t *	pool
	)

Decode utf8-encoded JSON string into apr_json_value_t.

Parameters

retval	the result
injson	utf8-encoded JSON string.
size	length of the input string.
offset	number of characters processed.
flags	set to APR_JSON_FLAGS_WHITESPACE to preserve whitespace, or APR_JSON_FLAGS_NONE to filter whitespace.
level	maximum nesting level we are prepared to decode.
pool	pool used to allocate the result from.

Returns

APR_SUCCESS on success, APR_EOF if the JSON text is truncated. APR_BADCH when a decoding error has occurred (the location of the error is at offset), APR_EINVAL if the level has been exceeded, or APR_ENOTIMPL on platforms where not implemented.

apr_json_double_create()

apr_json_value_t* apr_json_double_create	(	apr_pool_t *	pool,
		double	dnumber
	)

Allocate and return a JSON double.

Parameters

pool	The pool to allocate from.
dnumber	The double value.

Returns

The apr_json_value_t structure.

apr_json_encode()

apr_json_value_t apr_status_t apr_status_t apr_json_encode	(	apr_bucket_brigade *	brigade,
		apr_brigade_flush	flush,
		void *	ctx,
		const apr_json_value_t *	json,
		int	flags,
		apr_pool_t *	pool
	)

Encode data represented as apr_json_value_t to utf8-encoded JSON string and append it to the specified brigade.

All JSON strings are checked for invalid UTF-8 character sequences, and if found invalid sequences are replaced with the replacement character "�" (U+FFFD).

Parameters

brigade	brigade the result will be appended to.
flush	optional flush function for the brigade. Can be NULL.
ctx	optional contaxt for the flush function. Can be NULL.
json	the JSON data.
flags	set to APR_JSON_FLAGS_WHITESPACE to preserve whitespace, or APR_JSON_FLAGS_NONE to filter whitespace.
pool	pool used to allocate the buckets from.

Returns

APR_SUCCESS on success, or APR_ENOTIMPL on platforms where not implemented.

apr_json_long_create()

apr_json_value_t* apr_json_long_create	(	apr_pool_t *	pool,
		apr_int64_t	lnumber
	)

Allocate and return a JSON long.

Parameters

pool	The pool to allocate from.
lnumber	The long value.

Returns

The apr_json_value_t structure.

apr_json_null_create()

apr_json_value_t* apr_json_null_create

(

apr_pool_t *

pool

)

Allocate and return a JSON null.

Parameters

pool	The pool to allocate from.

Returns

The apr_json_value_t structure.

apr_json_object_create()

apr_json_value_t* apr_json_object_create

(

apr_pool_t *

pool

)

Allocate and return a JSON object.

Parameters

pool	The pool to allocate from.

Returns

The apr_json_value_t structure.

apr_json_object_first()

apr_status_t apr_status_t apr_json_kv_t apr_json_kv_t* apr_json_object_first

(

apr_json_value_t *

obj

)

Get the first value associated with an object.

If the value is an object, this function returns the first key value pair.

Parameters

obj	The JSON object.

Returns

Returns the first value, or NULL if not an object, or the object is empty.

apr_json_object_get()

apr_status_t apr_status_t apr_json_kv_t* apr_json_object_get	(	apr_json_value_t *	obj,
		const char *	key,
		apr_ssize_t	klen
	)

Look up the value associated with a key in a JSON object.

Parameters

obj	The JSON object.
key	Pointer to the key.
klen	Length of the key, or APR_JSON_VALUE_STRING if NUL terminated.

Returns

Returns NULL if the key is not present.

apr_json_object_next()

apr_json_kv_t* apr_json_object_next	(	apr_json_value_t *	obj,
		apr_json_kv_t *	kv
	)

Get the next value associated with an object.

This function returns the next key value pair, or NULL if no more pairs are present.

Parameters

obj	The JSON object.
kv	The previous JSON key value pair.

Returns

Returns the next key value pair, or NULL if not an object, or the object is empty.

apr_json_object_set()

apr_status_t apr_json_object_set	(	apr_json_value_t *	obj,
		const char *	key,
		apr_ssize_t	klen,
		apr_json_value_t *	val,
		apr_pool_t *	pool
	)

Associate a value with a key in a JSON object.

Parameters

obj	The JSON object.
key	Pointer to the key string.
klen	Length of the key, or APR_JSON_VALUE_STRING if NUL terminated.
val	Value to associate with the key.
pool	Pool to use.

Returns

APR_SUCCESS on success, APR_EINVAL if the key is NULL or not a string, or the object is not an APR_JSON_OBJECT.

Remarks

If the value is NULL the key value pair is deleted.

apr_json_object_set_ex()

apr_status_t apr_status_t apr_json_object_set_ex	(	apr_json_value_t *	obj,
		apr_json_value_t *	key,
		apr_json_value_t *	val,
		apr_pool_t *	pool
	)

Associate a value with a key in a JSON object, preserving whitespace.

Parameters

obj	The JSON object.
key	Pointer to the key string, including any whitespace required.
val	Value to associate with the key.
pool	Pool to use.

Returns

APR_SUCCESS on success, APR_EINVAL if the key is NULL or not a string, or the object is not an APR_JSON_OBJECT.

Remarks

If the value is NULL the key value pair is deleted.

apr_json_overlay()

apr_json_value_t apr_status_t apr_status_t apr_json_value_t* apr_json_overlay	(	apr_pool_t *	p,
		apr_json_value_t *	overlay,
		apr_json_value_t *	base,
		int	flags
	)

Overlay one JSON value over a second JSON value.

If the values are objects, a new object will be returned containing all keys from the overlay superimposed on the base.

Keys that appear in the overlay will replace keys in the base, unless APR_JSON_FLAGS_STRICT is specified, in which case NULL will be returned.

If either the base or the overlay are not objects, overlay will be returned.

Parameters

p	pool to use
overlay	the JSON object to overlay on top of base. If NULL, the base will be returned.
base	the base JSON object. If NULL, the overlay will be returned.
flags	set to APR_JSON_FLAGS_STRICT to fail if object keys are not unique, or APR_JSON_FLAGS_NONE to replace keys in base with overlay.

Returns

A new object containing the result. If APR_JSON_FLAGS_STRICT was specified and a key was present in overlay that was also present in base, NULL will be returned.

apr_json_string_create()

apr_json_value_t* apr_json_string_create	(	apr_pool_t *	pool,
		const char *	val,
		apr_ssize_t	len
	)

Allocate and return a JSON string with the given value.

Parameters

pool	The pool to allocate from.
val	The UTF-8 encoded string value.
len	The length of the string, or APR_JSON_VALUE_STRING.

Returns

The apr_json_value_t structure.

apr_json_value_create()

apr_json_value_t* apr_json_value_create

(

apr_pool_t *

pool

)

Allocate and return a apr_json_value_t structure.

Parameters

pool	The pool to allocate from.

Returns

The apr_json_value_t structure.