JSON Reference

Detailed Description

JSON Reference Manual.

Examples:

See the JSON tutorial for an introduction to using the JSON API.

Collaboration diagram for JSON Reference:

Modules
	JSON Parser Callback
	JSON Parser Callback Interface.

Classes
struct	JVal
	JVal represents a value in a JSON tree. More...
struct	JValFact
	The JValFact enables one to manually create a JVal syntax tree or add nodes to an existing syntax tree. More...
struct	JErr
	The JSON error container object. More...
struct	JParserVal
	The parser sets a JParserVal before calling the parser callback JParserIntf. More...
struct	JParser
	The JSON parser parses a JSON stream and calls the JParserIntf callback interface for each parsed object/primitive type. More...
struct	JEncoder
	The JEncoder can serialize a JSON JVAL syntax tree to the JSON text format. More...

Macros
#define	JE_MEMBER(o, m)   #m, (o)->m
	JEncoder::set helper macro, used when setting a value for an object. More...

Typedefs
typedef struct JValFact	JValFact
	The JValFact enables one to manually create a JVal syntax tree or add nodes to an existing syntax tree. More...
typedef struct JErr	JErr
	The JSON error container object.
typedef struct JParserVal	JParserVal
	The parser sets a JParserVal before calling the parser callback JParserIntf.
typedef U8	JParserStackNode
	The stack used internally by JParser.
typedef struct JEncoder	JEncoder
	The JEncoder can serialize a JSON JVAL syntax tree to the JSON text format. More...

Enumerations
enum	JVType {   JVType_InvalidType , JVType_String , JVType_Double , JVType_Int ,   JVType_Long , JVType_Boolean , JVType_Null , JVType_Object ,   JVType_Array }
	The JSON types. More...
enum	JErrT {   JErrT_NoErr =0 , JErrT_JsonErr , JErrT_WrongType , JErrT_InvalidMethodParams ,   JErrT_FmtValErr , JErrT_MemErr , JErrT_IOErr }
	JSON error codes. More...
enum	JParserT {   JParserT_InvalidType =0 , JParserT_Null , JParserT_String = 's' , JParserT_Double = 'f' ,   JParserT_Int = 'd' , JParserT_Long = 'l' , JParserT_Boolean = 'b' , JParserT_BeginObject = '{' ,   JParserT_BeginArray = '[' , JParserT_EndObject = '}' , JParserT_EndArray = ']' }
	Type 't' in JParserVal. More...
enum	JParsStat {   JParsStat_DoneEOS =1 , JParsStat_Done , JParsStat_NeedMoreData = 100 , JParsStat_ParseErr = 200 ,   JParsStat_IntfErr , JParsStat_MemErr , JParsStat_StackOverflow }
	JSON Parser Status. More...

Functions
JVType	JVal::getType ()
	Returns the JSON type.
JVal *	JVal::vget (JErr *err, const char **fmt, va_list *argList)
	Equivalent to get with variable argument list replaced by argList.
JVal *	JVal::get (JErr *err, const char *fmt,...)
	Get any type of value(s) from a JVal node or JVal tree. More...
S32	JVal::getInt (JErr *e)
	Returns the integer value for an integer JVal type or attempts to convert the value to an integer. More...
S64	JVal::getLong (JErr *e)
	Returns the integer as a long value for an integer JVal type or attempts to convert the value to a long integer. More...
double	JVal::getDouble (JErr *e)
	Returns the double value for a JVal float or attempts to convert the value to a float. More...
BaBool	JVal::getBoolean (JErr *e)
	Returns the boolean value for a boolean JVal type or false if the JVal is JVType_Null. More...
const char *	JVal::getString (JErr *e)
	Returns the string as a const or returns NULL if the JVAL is a NULL type. More...
char *	JVal::manageString (JErr *e)
	Similar to getString, but you must manage the value as the value is detached from the tree.
const char *	JVal::getName ()
	Returns the member name if this value is part of a JSON object.
char *	JVal::manageName ()
	Similar to getName, but you must manage the value as the value is detached from the tree.
JVal *	JVal::getNextElem ()
	Returns the next element if the parent is an object or an array.
JVal *	JVal::getObject (JErr *e)
	Returns the first child if an object. More...
JVal *	JVal::getArray (JErr *e)
	Returns the first child if an array. More...
JVal *	JVal::getJ (JErr *e)
	Returns the first child if an array or object. More...
JVal *	JVal::manageJ (JErr *e)
	Similar to getJ, but you must manage the JVal as the value is detached from the tree.
S32	JVal::getLength (JErr *e)
	Returns the elements left in the list. More...
void	JVal::setInt (JErr *e, S32 v)
	Sets a new integer value or changes the JSON type and sets the integer value.
void	JVal::setLong (JErr *e, S64 v)
	Sets a new integer value or changes the JSON type and sets the integer value.
void	JVal::setDouble (JErr *e, double v)
	Sets a new float value or changes the JSON type to float and sets the float value.
void	JVal::setBoolean (JErr *e, BaBool v)
	Sets a new boolean value or changes the JSON type and sets the boolean value.
void	JVal::setNull (JErr *e)
	Changes the JSON type if not NULL.
void	JVal::setString (JErr *e, char *v)
	Sets a string value and changes the JSON type if needed. More...
bool	JVal::isObjectMember ()
	Returns true if this is a child element in an object. More...
int	JVal::unlink (JVal *child)
	Remove a child. More...
int	JVal::addMember (JErr *e, const char *memberName, JVal *child, AllocatorIntf *dAlloc)
	Add a child to an object. More...
int	JVal::add (JErr *e, JVal *child)
	Add a child to an array. More...
void	JVal::terminate (AllocatorIntf *vAlloc, AllocatorIntf *dAlloc)
	Terminate the node and all sub nodes. More...
	JValFact::JValFact (AllocatorIntf *vAlloc, AllocatorIntf *dAlloc)
	create a JValFact JVal factory instance. More...
JVal *	JValFact::mkString (const char *v)
	Make a string. More...
JVal *	JValFact::mkDouble (double v)
	Make a float. More...
JVal *	JValFact::mkInt (S32 v)
	Make an integer. More...
JVal *	JValFact::mkLong (S64 v)
	Make a long integer. More...
JVal *	JValFact::mkBoolean (bool v)
	Make a boolean. More...
JVal *	JValFact::mkNull ()
	Make a null value. More...
JVal *	JValFact::mkObject ()
	Make a JSON object. More...
JVal *	JValFact::mkArray ()
	Make a JSON array. More...
	JErr::JErr ()
	Create a new object.
void	JErr::reset ()
	Reset – remove any error so the object can be reused.
bool	JErr::isError ()
	Returns true if the error flag is set.
bool	JErr::noError ()
	Returns true if no error.
JErrT	JErr::getErrT ()
	Returns the error type.
JVType	JErr::getExpT ()
	Returns the expected type if this is a parse error. More...
JVType	JErr::getRecT ()
	Returns the parsed type if this is a parse error. More...
	JParser::JParser (JParserIntf *intf, char *nameBuf, int namebufSize, AllocatorIntf *alloc, int extraStackLen=0)
	Create a JSON parser object. More...
int	JParser::parse (const U8 *buf, U32 size)
	Parse a JSON text chunk. More...
	JParser::~JParser ()
	Terminate and release the internal buffers.
JParsStat	JParser::getStatus ()
	Returns the parser status. More...
	JEncoder::JEncoder (JErr *err, BufPrint *out)
	Create an instance of the JEncoder class.
int	JEncoder::setInt (S32 val)
	Format an integer value.
int	JEncoder::setLong (S64 val)
	Format a long integer value.
int	JEncoder::setDouble (double val)
	Format a double value.
int	JEncoder::fmtString (const char *fmt,...)
	Converts (according to format 'fmt') and writes to stream. More...
int	JEncoder::vFmtString (const char *fmt, va_list argList)
	Equivalent to fmtString with variable argument list replaced by argList.
int	JEncoder::setString (const char *val)
	Format a string value. More...
int	JEncoder::b64enc (const void *source, S32 slen)
	Encode and emit (binary) data using B64 encoding.
int	JEncoder::setBoolean (bool val)
	Format a boolean value.
int	JEncoder::setNull ()
	Set a JSON null value.
int	JEncoder::setJV (struct JVal *val, bool iterateNext=false)
	Format a node or a tree of JVal nodes.
int	JEncoder::set (const char *fmt,...)
	Encode/serialize C structs/data to JSON using formatted output. More...
int	JEncoder::setName (const char *name)
	Set the member name before calling any of the set<value> members if formatting an object. More...
int	JEncoder::beginObject ()
	Begin object formatting. More...
int	JEncoder::endObject ()
	End object formatting.
int	JEncoder::beginArray ()
	Begin array formatting.
int	JEncoder::endArray ()
	End array formatting.
JErr *	JEncoder::getErr ()
	Returns the JErr object.
int	JEncoder::flush ()
	Flush JEncoder data to the output stream.
int	JEncoder::commit ()
	Calls flush and enables the construction of a new object.
BufPrint *	JEncoder::getBufPrint ()
	Fetch the internal BufPrint object.

Macro Definition Documentation

JE_MEMBER

#define JE_MEMBER	(		o,
			m
	)		#m, (o)->m

JEncoder::set helper macro, used when setting a value for an object.

encoder.set("{d}", JE_MEMBER(structval, membername));

Typedef Documentation

JEncoder

typedef struct JEncoder JEncoder

The JEncoder can serialize a JSON JVAL syntax tree to the JSON text format.

The JEncoder can also be used for assembling JSON text from calling the primitive methods in this class.

Example:

JErr err;
char buf[40]; //Must be sufficiently large for the JSON string
BufPrint jBuf(buf,sizeof(buf));
JEncoder jEnc(&err,&jBuf);
jEnc.set("{d}", "The number of the day is", 5);
//jBuf.buf == buf
buf[jBuf.cursor]=0; // So we can use printf
printf("%s\n",buf); // Prints: {"The number of the day is":5}

JValFact

typedef struct JValFact JValFact

The JValFact enables one to manually create a JVal syntax tree or add nodes to an existing syntax tree.

See also

JParserValFact

Enumeration Type Documentation

JErrT

enum JErrT

JSON error codes.

Enumerator
JErrT_NoErr	No error.
JErrT_JsonErr	Generic error.
JErrT_WrongType	Unexpected JSON type when parsing. See also JErr::getExpT JErr::getRecT
JErrT_InvalidMethodParams	Invalid RPC method parameters.
JErrT_FmtValErr	A format error in JEncoder or JVal::get.
JErrT_MemErr	Memory allocation error.
JErrT_IOErr	I/O error.

JParserT

enum JParserT

Type 't' in JParserVal.

Enumerator
JParserT_InvalidType	InvalidType.
JParserT_Null	Null.
JParserT_String	String.
JParserT_Double	Double.
JParserT_Int	Int.
JParserT_Long	64 bit (long long)
JParserT_Boolean	Boolean.
JParserT_BeginObject	BeginObject.
JParserT_BeginArray	BeginArray.
JParserT_EndObject	EndObject.
JParserT_EndArray	EndArray.

JParsStat

enum JParsStat

JSON Parser Status.

Enumerator
JParsStat_DoneEOS	The parser completed parsing a new JSON object.
JParsStat_Done	The parser completed parsing a new JSON object, but found the start of a new object in the provided buffer.
JParsStat_NeedMoreData	The parser needs more data to complete.
JParsStat_ParseErr	JSON Parse error.
JParsStat_IntfErr	The JParserIntf interface reported a problem.
JParsStat_MemErr	Memory allocation error.
JParsStat_StackOverflow	Object nested too deep. Increase stack size in constructor

JVType

enum JVType

The JSON types.

Enumerator
JVType_InvalidType	Invalid JSON type.
JVType_String	JSON string.
JVType_Double	JSON Number encoded as a float.
JVType_Int	JSON Number encoded as an integer.
JVType_Long	JSON Number encoded as a long integer.
JVType_Boolean	JSON boolean.
JVType_Null	JSON NULL value.
JVType_Object	The JVAL is of type JSON object.
JVType_Array	The JVAL is of type JSON array.

Function Documentation

add()

int JVal::add	(	JErr *	e,
		JVal *	child
	)

Add a child to an array.

Parameters

e	the error container.
child	is the element to add.

addMember()

int JVal::addMember	(	JErr *	e,
		const char *	memberName,
		JVal *	child,
		AllocatorIntf *	dAlloc
	)

Add a child to an object.

Parameters

e	the error container.
memberName	is the object member name.
child	is the element to add.
dAlloc	is the allocator used for copying the memberName.

beginObject()

int JEncoder::beginObject

(

)

Begin object formatting.

All calls to the the set<value> members must be proceeded by a call to JEncoder::name after you call beginObject. This condition is terminated if you call JEncoder::endObject or call JEncoder::beginArray. Begin object formatting

fmtString()

int JEncoder::fmtString	(	const char *	fmt,
			...
	)

Converts (according to format 'fmt') and writes to stream.

The method is internally using BufPrint::vprintf, which means that you can use the specialized format flags such as %j.

get()

JVal * JVal::get	(	JErr *	err,
		const char *	fmt,
			...
	)

Get any type of value(s) from a JVal node or JVal tree.

The get method works in a similar fashion to the ANSI C function scanf; thus, it performs formatted input conversion.

The method internally uses the 'getXXX' methods in this class for extracting the actual value(s), where XXX is Int, Long, etc.. The following table shows the relationship between the format flags and the JSON value extracted:

JSON type	Format flag	C type	Method
Number	d	S32*	JVal::getInt
Number	l	S64*	JVal::getLong
Number	f	double*	JVal::getDouble
boolean	b	BaBool*	JVal::getBoolean
string	s	const char**	JVal::getString
Any type	J	JVal**	All methods
Start object	{	n/a	JVal::getObject
End object	}	n/a	n/a
Start array	[	n/a	JVal::getArray
End array	]	n/a	n/a
JVal[size]	A	Array of JVal	All getXXX methods

See the JSON tutorial, section Using JParserValFact , for examples on how to use JVal.

See also

JDecoder::get

JEncoder::set

Advanced C Example:

JVal* jForecast[7]; //Array for 7 day forecast
JVal_get(rootVal,
         &err,
         "{ssdddAJ}",
         "city",&city,
         "desc",&desc,
         "temp",&temp,
         "humidity",&humidity,
         "dt", &dt,
         "list",jForecast,7);//Flag '{A}' requires: member name, list, length
if(JErr_noError(&err))
{
   for(i=0 ; i < 7 && JErr_noError(&err) ; i++)
   {
      JVal_get(jForecast[i],
               &err,
               "{dddds}",
               "wday",&wday,
               "tmax",&tmax,
               "tmin",&tmin,
               "humidity",&humidity,
               "desc",&desc);
   }
}

getArray()

JVal * JVal::getArray

(

JErr *

e

)

Returns the first child if an array.

JErr is set for all other types.

getBoolean()

BaBool JVal::getBoolean

(

JErr *

e

)

Returns the boolean value for a boolean JVal type or false if the JVal is JVType_Null.

JErr is set for all other types.

getDouble()

double JVal::getDouble

(

JErr *

e

)

Returns the double value for a JVal float or attempts to convert the value to a float.

JErr is set if the method cannot convert the value.

getExpT()

JVType JErr::getExpT

(

)

Returns the expected type if this is a parse error.

See also

getErrT getRecT

getInt()

S32 JVal::getInt

(

JErr *

e

)

Returns the integer value for an integer JVal type or attempts to convert the value to an integer.

JErr is set if the method cannot convert the value.

getJ()

JVal * JVal::getJ

(

JErr *

e

)

Returns the first child if an array or object.

JErr is set for all other types.

getLength()

S32 JVal::getLength

(

JErr *

e

)

Returns the elements left in the list.

Returns the number of childs if called on the value returned by getObject, getArray, or getJ.

getLong()

S64 JVal::getLong

(

JErr *

e

)

Returns the integer as a long value for an integer JVal type or attempts to convert the value to a long integer.

JErr is set if the method cannot convert the value.

getObject()

JVal * JVal::getObject

(

JErr *

e

)

Returns the first child if an object.

JErr is set for all other types.

getRecT()

JVType JErr::getRecT

(

)

Returns the parsed type if this is a parse error.

See also

getErrT getExpT

getStatus()

JParsStat JParser::getStatus

(

)

Returns the parser status.

Typically used when method parse returns a non zero value.

See also

parse

getString()

const char * JVal::getString

(

JErr *

e

)

Returns the string as a const or returns NULL if the JVAL is a NULL type.

JErr is set for all other types.

isObjectMember()

bool JVal::isObjectMember

(

)

Returns true if this is a child element in an object.

Returns false if this is a child element in an array.

JParser()

JParser::JParser	(	JParserIntf *	intf,
		char *	nameBuf,
		int	namebufSize,
		AllocatorIntf *	alloc,
		int	extraStackLen = 0
	)

Create a JSON parser object.

Parameters

intf	is the parser callback/interface. Provide your own callback or use one of JParserValFact or JDecoder.
nameBuf	is a buffer required for temporarily storing parsed object member names.
namebufSize	sizeof(nameBuf)
alloc	is the allocator used for internal buffer management.
extraStackLen	is a non documented feature and must be set to 0.

JValFact()

JValFact::JValFact	(	AllocatorIntf *	vAlloc,
		AllocatorIntf *	dAlloc
	)

create a JValFact JVal factory instance.

Parameters

vAlloc	is used when allocating nodes.
dAlloc	is used when allocating strings. The two allocators can be the same.

mkArray()

JVal * JValFact::mkArray

(

)

Make a JSON array.

Returns null if the allocator failed.

mkBoolean()

JVal * JValFact::mkBoolean

(

bool

v

)

Make a boolean.

Returns null if the allocator failed.

mkDouble()

JVal * JValFact::mkDouble

(

double

v

)

Make a float.

Returns null if the allocator failed.

mkInt()

JVal * JValFact::mkInt

(

S32

v

)

Make an integer.

Returns null if the allocator failed.

mkLong()

JVal * JValFact::mkLong

(

S64

v

)

Make a long integer.

Returns null if the allocator failed.

mkNull()

JVal * JValFact::mkNull

(

)

Make a null value.

Returns null if the allocator failed.

mkObject()

JVal * JValFact::mkObject

(

)

Make a JSON object.

Returns null if the allocator failed.

mkString()

JVal * JValFact::mkString

(

const char *

v

)

Make a string.

Returns null if the allocators failed.

parse()

int JParser::parse	(	const U8 *	buf,
		U32	size
	)

Parse a JSON text chunk.

Parameters

buf	a pointer to the JSON text chunk buffer.
size	is the buffer length.

Returns

• 0: Needs more data. The JSON chunk parsed was only a partial object.
• > 0: A complete JSON object is assembled.
• < 0: Parse error.

See also

getStatus

set()

int JEncoder::set	(	const char *	fmt,
			...
	)

Encode/serialize C structs/data to JSON using formatted output.

The set method works in a similar fashion to the ANSII C function printf; thus, it performs formatted output conversion.

The method internally uses the 'setXXX' methods in this class for setting the actual value(s), where XXX is setInt, setLong, etc.. The following table shows the relationship between the format flags and the JSON value:

JSON type	Format flag	C type	Method
Number	d	S32	JVal::setInt
Number	l	S64	JVal::setLong
Number	f	double	JVal::setDouble
boolean	b	BaBool	JVal::setBoolean
string	s	const char*	JVal::setString
Any type	J	JVal*	All methods
Start object	{	n/a	JVal::beginObject
End object	}	n/a	JVal::endObject
Start array	[	n/a	JVal::beginArray
End array	]	n/a	JVal::endArray
JVal[size]	A	Array of JVal	All setXXX methods

See also

JE_MEMBER

JVal::get

JDecoder::get

setName()

int JEncoder::setName

(

const char *

name

)

Set the member name before calling any of the set<value> members if formatting an object.

Parameters

name	the object member name.

See also

beginObject

setString() [1/2]

int JEncoder::setString

(

const char *

val

)

Format a string value.

The method is internally using BufPrint::jsonString.

setString() [2/2]

void JVal::setString	(	JErr *	e,
		char *	v
	)

Sets a string value and changes the JSON type if needed.

The pointer is directly stored and not copied. The string must, therefore, have been allocated with the dynamic allocator used by the JVal tree. You cannot set a new string without managing the old string.

terminate()

void JVal::terminate	(	AllocatorIntf *	vAlloc,
		AllocatorIntf *	dAlloc
	)

Terminate the node and all sub nodes.

The element to terminate must be managed.

Parameters

vAlloc	is the allocator that was used for allocating the nodes.
dAlloc	is the allocator that was used for allocating the strings.

See also

unlink manageJ JParserValFact::manageFirstVal

unlink()

int JVal::unlink

(

JVal *

child

)

Remove a child.

Typically used together with method terminate.

Parameters

child

is the child to remove.