Detailed Description

Universal Binary JSON Reference Manual.

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

Collaboration diagram for UBJSON Reference:

Modules
	UBJSON Parser Callback
	UBJSON Parser Callback Interface.

Classes
struct	UBJVal
	UBJParser Value (passed into the parser callback interface UBJPIntf) More...

struct	UBJPStackNode
	The event based parser uses a stack instead of recursion and the UBJPStackNode type represent one entry in the stack. More...

struct	UBJPIntf
	The UBJPIntf interface class is the interface between the parser and an object that implements the UBJPIntf interface. More...

struct	UBJParser
	The UBJSON parser parses a binary UBJSON stream and calls the UBJPIntf callback interface for each parsed object/primitive type. More...

struct	UBJEBuf
	The UBJSON Encoder buffer is used by the encoder UBJEncoder. More...

struct	UBJEncoder
	UBJSON Encoder. More...

struct	UBJDecoderStackNode
	Used internally in UBJDecoder for nested data structures. More...

struct	UBJDecoderV
	Used internally in UBJDecoder, where one instance represents one node in the pointer value tree. More...

struct	UBJDecoder
	UBJDecoder implements the parser callback API UBJPIntf and builds a pointer value tree when UBJDecoder::get is called. More...

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

#define	UBJD_MNUM(o, m) #m, &(o)->m
	JDecoder::get helper macro, used when setting a number pointer in an object. More...

#define	UBJD_MSTR(o, m) #m, &(o)->m, sizeof((o)->m)
	JDecoder::get helper macro, used when setting a string pointer in an object. More...

#define	UBJD_ASTR(o, m) &(o)->m, sizeof((o)->m)
	JDecoder::get helper macro, used when setting a string pointer in an array. More...

Typedefs
typedef int(*	UBJPIntf_Service) (struct UBJPIntf o, UBJVal v, int recLevel)
	Parser callback function used by interface class UBJPIntf. More...

typedef struct UBJPIntf	UBJPIntf
	The UBJPIntf interface class is the interface between the parser and an object that implements the UBJPIntf interface. More...

typedef struct UBJParser	UBJParser
	The UBJSON parser parses a binary UBJSON stream and calls the UBJPIntf callback interface for each parsed object/primitive type. More...

typedef int(*	UBJEBuf_FlushCB) (struct UBJEBuf *o, int sizeRequired)
	UBJSON Encoder buffer callback can be used for flushing the buffer or for expanding the buffer. More...

typedef struct UBJEBuf	UBJEBuf
	The UBJSON Encoder buffer is used by the encoder UBJEncoder.

typedef struct UBJEncoder	UBJEncoder
	UBJSON Encoder. More...

typedef UBJDecoder	UBJDecoder
	UBJDecoder implements the parser callback API UBJPIntf and builds a pointer value tree when UBJDecoder::get is called. More...

Enumerations
enum	UBJT { UBJT_InvalidType =0 , UBJT_Null ='Z' , UBJT_NoOp ='N' , UBJT_Boolean , UBJT_Int8 ='i' , UBJT_Uint8 ='U' , UBJT_Int16 ='I' , UBJT_Int32 ='l' , UBJT_Int64 ='L' , UBJT_Float32 ='d' , UBJT_Float64 ='D' , UBJT_HNumber ='H' , UBJT_Char ='C' , UBJT_String ='S' , UBJT_BeginObject ='{' , UBJT_BeginArray ='[' , UBJT_Count ='#' , UBJT_EndObject ='}' , UBJT_EndArray =']' }
	UBJSON Value Type: See UBJVal::t and the UBJSON type reference for more information. More...

enum	UBJPStatus { UBJPStatus_DoneEOS =1 , UBJPStatus_Done , UBJPStatus_NeedMoreData = 100 , UBJPStatus_ParseErr = 200 , UBJPStatus_IntfErr , UBJPStatus_Overflow }
	UBJSON Parser Status. More...

enum	UBJEStatus { UBJEStatus_FlushErr = -100 , UBJEStatus_LengthRequired , UBJEStatus_StackOverflow , UBJEStatus_TypeMismatch , UBJEStatus_Unbalanced , UBJEStatus_Unknown , UBJEStatus_ok =0 }
	UBJSON Encoder status. More...

enum	UBJDecoderS { UBJDecoderS_FormatErr = -100 , UBJDecoderS_NameNotFound , UBJDecoderS_Overflow , UBJDecoderS_StringOverflow , UBJDecoderS_Unbalanced , UBJDecoderS_Underflow , UBJDecoderS_Unknown , UBJDecoderS_BufNotAligned , UBJDecoderS_ChainedErr , UBJDecoderS_OK = 0 }
	UBJDecoder Status Codes. More...

Functions
	UBJPIntf::UBJPIntf (UBJPIntf_Service s)
	Create the callback interface object. More...

	UBJParser::UBJParser (UBJPIntf intf, char name, int memberNameLen, int extraStackLen=0)
	Create the callback interface object. More...

	UBJParser::~UBJParser ()
	Destructor.

int	UBJParser::parse (const U8 *buf, U32 size)
	Parse a UBJSON chunk. More...

int	UBJParser::getIndex ()
	Returns the current container index position when parsing an optimized container.

int	UBJParser::getCount ()
	Returns the length of the optimized container when type (t) is UBJT_Count.

int	UBJParser::getStatus ()
	Returns the parser status. More...

	UBJEBuf::UBJEBuf (UBJEBuf_FlushCB cb, U8 *buf, S32 bufLen)
	Initialize the UBJSON Encoder buffer. More...

	UBJEncoder::UBJEncoder (UBJEBuf *buf)
	Create/initialize an UBJEncoder instance. More...

	UBJEncoder::~UBJEncoder ()
	Destructor.

int	UBJEncoder::setName (const char *n)
	Set member name. More...

int	UBJEncoder::null ()
	Set UBJSON NULL.

int	UBJEncoder::boolean (bool b)
	Set boolean.

int	UBJEncoder::uint8 (U8 v)
	Set uint8.

int	UBJEncoder::int8 (S8 v)
	Set int8.

int	UBJEncoder::character (char v)
	Set 'char'.

int	UBJEncoder::int16 (S16 v)
	Set int16.

int	UBJEncoder::int32 (S32 v)
	Set int32.

int	UBJEncoder::int64 (S64 v)
	Set int64.

int	UBJEncoder::float64 (double v)
	Set float64.

int	UBJEncoder::float32 (float v)
	Set float32.

int	UBJEncoder::string (const char *s, S32 len)
	Set string.

int	UBJEncoder::beginArray (S32 count=-1, UBJT type=UBJT_InvalidType)
	Begin formatting an array. More...

int	UBJEncoder::beginObject (S32 count=-1, UBJT type=UBJT_InvalidType)
	Begin formatting an object. More...

int	UBJEncoder::endArray ()
	End of array.

int	UBJEncoder::endObject ()
	End of object.

void	UBJEncoder::reset ()
	Resets the UBJEBuf cursor (the buffer provided in the constructor)

int	UBJEncoder::vset (const char *fmt, va_list argList, bool isObj)
	See UBJEncoder:set for details.

int	UBJEncoder::set (const char *fmt,...)
	Encode/serialize C structs/data to UBJSON using formatted output. More...

int	UBJDecoder::vget (const char fmt, va_list argList)
	See UBJDecoder::get for details.

int	UBJDecoder::get (const char *fmt,...)
	Build a pointer value tree that is used by the integrated parser callback function when the parser feeds elements to the JDecoder instance. More...

	UBJDecoder::UBJDecoder (U8 *buf, int bufSize, int extraStackLen=0)
	Create/initialize a UBJDecoder instance. More...

Macro Definition Documentation

◆ UBJD_ASTR

#define UBJD_ASTR	(	o,
		m
	)	&(o)->m, sizeof((o)->m)

JDecoder::get helper macro, used when setting a string pointer in an array.

encoder.set("[s]", UBJD_ASTR(structval, membername));

◆ UBJD_MNUM

#define UBJD_MNUM	(	o,
		m
	)	#m, &(o)->m

JDecoder::get helper macro, used when setting a number pointer in an object.

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

◆ UBJD_MSTR

#define UBJD_MSTR	(	o,
		m
	)	#m, &(o)->m, sizeof((o)->m)

JDecoder::get helper macro, used when setting a string pointer in an object.

encoder.set("{s}", UBJD_MSTR(structval, membername));

◆ UBJE_MEMBER

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

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

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

Typedef Documentation

◆ UBJDecoder

typedef UBJDecoder UBJDecoder

UBJDecoder implements the parser callback API UBJPIntf and builds a pointer value tree when UBJDecoder::get is called.

The pointer value tree is used by the parser callback when the parser feeds the callback with parsed data.

See the JSON and UBJSON tutorial for more information on using UBJDecoder.

◆ UBJEBuf_FlushCB

typedef int(* UBJEBuf_FlushCB) (struct UBJEBuf *o, int sizeRequired)

UBJSON Encoder buffer callback can be used for flushing the buffer or for expanding the buffer.

The callback must set the cursor position to zero if the buffer is flushed.

Parameters

o	UBJEBuf
sizeRequired	is the extra size required by the buffer (if expanding the buffer).

◆ UBJEncoder

typedef struct UBJEncoder UBJEncoder

UBJSON Encoder.

The encoder performs limited error checking and you can produce incorrect UBJSON data if you incorrectly use the methods in this class.

◆ UBJParser

typedef struct UBJParser UBJParser

The UBJSON parser parses a binary UBJSON stream and calls the UBJPIntf callback interface for each parsed object/primitive type.

See also: UBJVal; JParser

◆ UBJPIntf

typedef struct UBJPIntf UBJPIntf

The UBJPIntf interface class is the interface between the parser and an object that implements the UBJPIntf interface.

See also: UBJPIntf_Service

◆ UBJPIntf_Service

typedef int(* UBJPIntf_Service) (struct UBJPIntf *o, UBJVal *v, int recLevel)

Parser callback function used by interface class UBJPIntf.

Parameters

o	the interface object
v	the parsed value
recLevel	goes from 0 to N and represents object nesting level

Enumeration Type Documentation

◆ UBJDecoderS

enum UBJDecoderS

UBJDecoder Status Codes.

Enumerator
UBJDecoderS_FormatErr	Parsed data does not match the value tree that was created when method UBJDecoder::get was called.
UBJDecoderS_NameNotFound	Parsed data includes a member whose name is not in value tree.
UBJDecoderS_Overflow	Received more array or object member values from parsed data than found in value tree.
UBJDecoderS_StringOverflow	Parsed string longer than buffer provided.
UBJDecoderS_Unbalanced	Incorrect use of '{', '}', '[', or '[' in JDecoder::get.
UBJDecoderS_Underflow	Received less array or object member values from parsed data than found in value tree.
UBJDecoderS_Unknown	Unkown error.
UBJDecoderS_BufNotAligned	Memory buffer(s) provided in UBJDecoder constructor must be word aligned.
UBJDecoderS_ChainedErr	A chained parser callback, provided via the 'X' format flag in JDecoder::get, reported an error.
UBJDecoderS_OK	OK, no errors.

◆ UBJEStatus

enum UBJEStatus

UBJSON Encoder status.

Enumerator
UBJEStatus_FlushErr	UBJEBuf_FlushCB returned a non zero value.
UBJEStatus_LengthRequired	Length required for Optimized Strongly Typed Container.
UBJEStatus_StackOverflow	Object depth exceeding internal stack.
UBJEStatus_TypeMismatch	The value set does not mach type set for Optimized Strongly Typed
UBJEStatus_Unbalanced	(curly) bracket start/end mismatch
UBJEStatus_Unknown	Unknown type (Must be a type from UBJT)
UBJEStatus_ok	No error.

◆ UBJPStatus

enum UBJPStatus

UBJSON Parser Status.

Enumerator
UBJPStatus_DoneEOS	The parser completed parsing a new UBJSON object.
UBJPStatus_Done	The parser completed parsing a new UBJSON object, but found the start of a new object in the provided buffer.
UBJPStatus_NeedMoreData	The parser requires more data to complete.
UBJPStatus_ParseErr	UBJSON Parse error.
UBJPStatus_IntfErr	The UBJParserIntf interface reported a problem.
UBJPStatus_Overflow	Parsed data/array/object too big.

◆ UBJT

enum UBJT

UBJSON Value Type: See UBJVal::t and the UBJSON type reference for more information.

Enumerator
UBJT_InvalidType	Not a valid UBJSON type.
UBJT_Null	Type UBJT_Null.
UBJT_NoOp	Type UBJT_NoOp.
UBJT_Boolean	Type UBJT_Boolean.
UBJT_Int8	Type UBJT_Int8.
UBJT_Uint8	Type UBJT_Uint8.
UBJT_Int16	Type UBJT_Int16.
UBJT_Int32	Type UBJT_Int32.
UBJT_Int64	Type UBJT_Int64.
UBJT_Float32	Type UBJT_Float32.
UBJT_Float64	Type UBJT_Float64.
UBJT_HNumber	Type UBJT_HNumber.
UBJT_Char	Type UBJT_Char.
UBJT_String	Type UBJT_String.
UBJT_BeginObject	Type UBJT_BeginObject.
UBJT_BeginArray	Type UBJT_BeginArray.
UBJT_Count	Type UBJT_Count.
UBJT_EndObject	Type UBJT_EndObject.
UBJT_EndArray	Type UBJT_EndArray.

Function Documentation

◆ beginArray()

int UBJEncoder::beginArray	(	S32	count = `-1`,
		UBJT	type = `UBJT_InvalidType`
	)

Begin formatting an array.

Use the default values for the two parameters, or consult the UBJSON specification, section: Optimized Format.

Parameters

count	must be set to the number of elements in the array when formatting an optimized array with count or to -1 if not used.
type	must be set to the type of the optimized array if formatting a strongly typed array, or to UBJT_InvalidType if not used.

◆ beginObject()

int UBJEncoder::beginObject	(	S32	count = `-1`,
		UBJT	type = `UBJT_InvalidType`
	)

Begin formatting an object.

Use the default values for the two parameters, or consult the UBJSON specification, section: Optimized Format.

Parameters

count	must be set to the number of elements in the object when formatting an optimized object with count or to -1 if not used.
type	must be set to the type of the optimized object if formatting a strongly typed object, or to UBJT_InvalidType if not used.

◆ get()

int UBJDecoder::get	(	const char *	fmt,
			...
	)

Build a pointer value tree that is used by the integrated parser callback function when the parser feeds elements to the JDecoder instance.

Parameters

fmt

format flags:

UBJSON type	Format flag	C type
bool	b	U8*
int8	i	S8*
uint8	U	U8*
int16	I	S16*
int32	l	S32*
int64	L	S64*
float32	d	float*
float64	D	double*
char	C	S8
string	S	char**

See the JSON and UBJSON tutorial for more information on using this method.

See also: UBJD_MNUM; UBJD_MSTR; UBJD_ASTR; UBJEncoder::set

◆ getStatus()

int UBJParser::getStatus ( )

Returns the parser status.

Typically used when method parse returns a value less than zero.

See also: parse

◆ parse()

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

Parse a UBJSON chunk.

Parameters

buf	a pointer to the UBJSON chunk.
size	is the buffer length.

Returns

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

See also: getStatus

◆ set()

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

Encode/serialize C structs/data to UBJSON 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 uint8, float32, etc.. The following table shows the relationship between the format flags and the UBJSON values:

Parameters

fmt

format flags:

UBJSON type	Format flag	C type
bool	b	U8
int8	i	S8
uint8	U	U8
int16	I	S16
int32	l	S32
int64	L	S64
float32	d	float
float64	D	double
char	C	S8
string	S	char*

See also: UBJE_MEMBER; UBJDecoder::get

◆ setName()

int UBJEncoder::setName ( const char * n )

Set member name.

This function must be called for objects, but must not be called for arrays.

◆ UBJDecoder()

UBJDecoder::UBJDecoder	(	U8 *	buf,
		int	bufSize,
		int	extraStackLen = `0`
	)

Create/initialize a UBJDecoder instance.

Parameters

buf	is a pointer to a buffer used internally for memory storage when building the pointer value tree. The minimum size must be sizeof(UBJDecoderV) * N, where N is the number of format flags minus the end of array/object flags (] or }).
bufSize	the size of 'buf'
extraStackLen	is a non documented value and must be set to 0.

◆ UBJEBuf()

UBJEBuf::UBJEBuf	(	UBJEBuf_FlushCB	cb,
		U8 *	buf,
		S32	bufLen
	)

Initialize the UBJSON Encoder buffer.

Parameters

cb	the expand or flush callback.
buf	the (initial) encoder buffer
bufLen	is length of buffer (min 14 bytes)

◆ UBJEncoder()

UBJEncoder::UBJEncoder ( UBJEBuf * buf )

Create/initialize an UBJEncoder instance.

Parameters

buf	a buffer that either buffers all produced UBJSON data or small chunks, which are then flushed out to a stream when the buffer is full.

◆ UBJParser()

UBJParser::UBJParser	(	UBJPIntf *	intf,
		char *	name,
		int	memberNameLen,
		int	extraStackLen = `0`
	)

Create the callback interface object.

Parameters

intf	the callback interface object.
name	is a buffer used for storing an object member name during parsing.
memberNameLen	is the length of the object member name buffer. The length must be no less than the largest member name expected.
extraStackLen	informs the parser that it can use a stack larger than the default depth of 3. The memory for the UBJParser object must be constructed as follows: malloc(sizeof(UBJParser) + extraStackLen * sizeof(UBJPStackNode))

◆ UBJPIntf()

UBJPIntf::UBJPIntf ( UBJPIntf_Service s )

Create the callback interface object.

Parameters

s	the parser service callback function.

Detailed Description

Modules

Classes

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ UBJD_ASTR

◆ UBJD_MNUM

◆ UBJD_MSTR

◆ UBJE_MEMBER

Typedef Documentation

◆ UBJDecoder

◆ UBJEBuf_FlushCB

◆ UBJEncoder

◆ UBJParser

◆ UBJPIntf

◆ UBJPIntf_Service

Enumeration Type Documentation

◆ UBJDecoderS

◆ UBJEStatus

◆ UBJPStatus

◆ UBJT

Function Documentation

◆ beginArray()

◆ beginObject()

◆ get()

◆ getStatus()

◆ parse()

◆ set()

◆ setName()

◆ UBJDecoder()

◆ UBJEBuf()

◆ UBJEncoder()

◆ UBJParser()

◆ UBJPIntf()