Barracuda Application Server C/C++ Reference
NO
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.
 
JValJVal::vget (JErr *err, const char **fmt, va_list *argList)
 Equivalent to get with variable argument list replaced by argList.
 
JValJVal::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.
 
JValJVal::getNextElem ()
 Returns the next element if the parent is an object or an array.
 
JValJVal::getObject (JErr *e)
 Returns the first child if an object. More...
 
JValJVal::getArray (JErr *e)
 Returns the first child if an array. More...
 
JValJVal::getJ (JErr *e)
 Returns the first child if an array or object. More...
 
JValJVal::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...
 
JValJValFact::mkString (const char *v)
 Make a string. More...
 
JValJValFact::mkDouble (double v)
 Make a float. More...
 
JValJValFact::mkInt (S32 v)
 Make an integer. More...
 
JValJValFact::mkLong (S64 v)
 Make a long integer. More...
 
JValJValFact::mkBoolean (bool v)
 Make a boolean. More...
 
JValJValFact::mkNull ()
 Make a null value. More...
 
JValJValFact::mkObject ()
 Make a JSON object. More...
 
JValJValFact::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.
 
JErrJEncoder::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.
 
BufPrintJEncoder::getBufPrint ()
 Fetch the internal BufPrint object.
 

Macro Definition Documentation

◆ JE_MEMBER

#define JE_MEMBER (   o,
 
)    #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
ethe error container.
childis the element to add.

◆ addMember()

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

Add a child to an object.

Parameters
ethe error container.
memberNameis the object member name.
childis the element to add.
dAllocis 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 typeFormat flagC type Method
Numberd S32* JVal::getInt
Numberl S64* JVal::getLong
Numberf double* JVal::getDouble
booleanb BaBool* JVal::getBoolean
strings const char** JVal::getString
Any typeJ 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
intfis the parser callback/interface. Provide your own callback or use one of JParserValFact or JDecoder.
nameBufis a buffer required for temporarily storing parsed object member names.
namebufSizesizeof(nameBuf)
allocis the allocator used for internal buffer management.
extraStackLenis a non documented feature and must be set to 0.

◆ JValFact()

JValFact::JValFact ( AllocatorIntf vAlloc,
AllocatorIntf dAlloc 
)

create a JValFact JVal factory instance.

Parameters
vAllocis used when allocating nodes.
dAllocis 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
bufa pointer to the JSON text chunk buffer.
sizeis 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 typeFormat flagC type Method
Numberd S32 JVal::setInt
Numberl S64 JVal::setLong
Numberf double JVal::setDouble
booleanb BaBool JVal::setBoolean
strings const char* JVal::setString
Any typeJ 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
namethe 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
vAllocis the allocator that was used for allocating the nodes.
dAllocis 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
childis the child to remove.
JEncoder
The JEncoder can serialize a JSON JVAL syntax tree to the JSON text format.
Definition: JEncoder.h:66
JVal
JVal represents a value in a JSON tree.
Definition: JVal.h:73
BufPrint
The BufPrint class, which implements an ANSI compatible printf method, is a base class used by severa...
Definition: BufPrint.h:122
JErr
The JSON error container object.
Definition: JParser.h:155