Barracuda Application Server C/C++ Reference
NO
UBJSON Reference

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,
 
)    &(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, &(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, &(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, (o)->m

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

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

Typedef Documentation

◆ 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
sizeRequiredis 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
othe interface object
vthe parsed value
recLevelgoes from 0 to N and represents object nesting level

Enumeration Type Documentation

◆ 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
countmust be set to the number of elements in the array when formatting an optimized array with count or to -1 if not used.
typemust 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
countmust be set to the number of elements in the object when formatting an optimized object with count or to -1 if not used.
typemust 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
fmtformat flags:
UBJSON typeFormat flagC type
boolbU8*
int8iS8*
uint8UU8*
int16IS16*
int32lS32*
int64LS64*
float32dfloat*
float64Ddouble*
charCS8
stringSchar**

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
bufa pointer to the UBJSON chunk.
sizeis 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
fmtformat flags:
UBJSON typeFormat flagC type
boolbU8
int8iS8
uint8UU8
int16IS16
int32lS32
int64LS64
float32dfloat
float64Ddouble
charCS8
stringSchar*
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
bufis 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 }).
bufSizethe size of 'buf'
extraStackLenis 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
cbthe expand or flush callback.
bufthe (initial) encoder buffer
bufLenis length of buffer (min 14 bytes)

◆ UBJEncoder()

UBJEncoder::UBJEncoder ( UBJEBuf buf)

Create/initialize an UBJEncoder instance.

Parameters
bufa 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
intfthe callback interface object.
nameis a buffer used for storing an object member name during parsing.
memberNameLenis the length of the object member name buffer. The length must be no less than the largest member name expected.
extraStackLeninforms 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
sthe parser service callback function.