Barracuda Application Server C/C++ Reference
Native APIs, integration guides, and platform interfaces

Detailed Description

This group documents the streaming xparser C API used by BAS's Lua XML binding.

Start with xparser_create() and xparser_parse(), and follow their allocator, callback, and input-buffer contracts. BASCore.c includes this parser; the supplied BWSCore.c does not.

The separate parser in SimpleXml.h builds nodes in caller-supplied storage and modifies the input document in place. It is used by WebDAV and is not an xparser wrapper.

Collaboration diagram for XML parsing:

Typedefs

typedef int(* xparser_callback) (xparser *parser, void *userdata, xparser_event event, const char *name, const char **attr, const char *data)
 xparser user callback. More...
 
typedef void *(* xparser_alloc) (void *ud, void *ptr, size_t osize, size_t nsize)
 define XPARSER_ALLOC non-zero to enable a user memory allocator. More...
 

Enumerations

enum  xparser_event {
  xparserNOEVENT = 0 , xparserINIT , xparserRESET , xparserTERM ,
  xparserSTART , xparserXML , xparserSTART_ELEMENT , xparserEND_ELEMENT ,
  xparserEMPTY_ELEMENT , xparserPI , xparserCOMMENT , xparserCDATA ,
  xparserTEXT , xparserLAST
}
 events for user callbacks More...
 
enum  xparser_textmode
 flags for text handling More...
 

Functions

xparser * xparser_create (void)
 create a parser. More...
 
int xparser_init (xparser *parser, xparser_handlers *handlers, void *userdata, unsigned int options)
 initialise a parser. More...
 
int xparser_term (xparser *parser)
 destroy a parser, WITHOUT deallocating pointer. More...
 
void xparser_destroy (xparser *parser)
 destroy a parser More...
 
int xparser_reset (xparser *parser, int full)
 reset a parser to post-create state. More...
 
int xparser_parse (xparser *parser, const char *pData, size_t datalen)
 parse a chunk of xml data. More...
 
int xparser_finish (xparser *parser)
 Check end of input without invoking callbacks. More...
 
const char * xparser_errormsg (xparser *parser)
 Read the last parser error. More...
 
unsigned int xparser_line (xparser *parser)
 Read the source line. More...
 
unsigned int xparser_col (xparser *parser)
 Read the source column. More...
 
size_t xparser_count (xparser *parser)
 Read the input position. More...
 
unsigned int xparser_depth (xparser *parser)
 Read the nesting depth. More...
 
unsigned int xparser_flags (xparser *parser)
 Read whitespace-processing flags. More...
 
int xparser_has_doc (xparser *parser)
 Check whether the document node was parsed. More...
 
void * xparser_userdata (xparser *parser)
 Retrieve the application context. More...
 
xparser * xparser_createalloc (xparser_alloc pa, void *ud)
 Create a parser with its own allocator callback and context. More...
 
void xparser_setalloc (xparser_alloc pa, void *ud)
 Install the default allocator for subsequent xparser_create calls. More...
 

Variables

const char *const xparser_eventname [xparserLAST]
 array lookup for event names More...
 

Typedef Documentation

◆ xparser_alloc

typedef void *(* xparser_alloc) (void *ud, void *ptr, size_t osize, size_t nsize)

define XPARSER_ALLOC non-zero to enable a user memory allocator.

if XPARSER_ALLOC == 1, parser will default to internal allocator; xparser_setalloc() MAY be called to supply a replacement allocator.

if XPARSER_ALLOC == 2, parser will default to an internal stub which will always return NULL, and xparser_setalloc() must supply an allocator for xparser_create(). xparser_createalloc() instead supplies an allocator for one instance.

If XPARSER_ALLOC is 0, the parser uses baRealloc/baFree directly and does not expose custom-allocator entry points. user memory allocator.

◆ xparser_callback

typedef int(* xparser_callback) (xparser *parser, void *userdata, xparser_event event, const char *name, const char **attr, const char *data)

xparser user callback.

Returns
non-zero to terminate parse or return value from init handler

Unused name/data parameters point to an empty string. attr points to a NULL-terminated list (possibly empty). Callback arguments are borrowed until the callback returns. Read-only accessors may be used in callbacks; do not mutate or destroy this parser from an event or allocator callback. Reentrant operations returning int are rejected with -1 without changing parser state; reentrant destruction does nothing. Callbacks must return normally, without longjmp or a C++ exception across the parser frame.

Enumeration Type Documentation

◆ xparser_event

events for user callbacks

Enumerator
xparserNOEVENT 

internal flag for no event set.

xparserINIT 

called from xparser_init()

xparserRESET 

called from xparser_reset()

xparserTERM 

called from xparser_destroy()

xparserSTART 

called from xparser_parse(), on first call since init() or reset()

xparserXML 

xml declaration : <?xml attrs ?>

xparserSTART_ELEMENT 

start element : <name attrs >

xparserEND_ELEMENT 

end element : </name>

xparserEMPTY_ELEMENT 

empty element : <name attrs />

xparserPI 

processing instruction : <?name data?>

xparserCOMMENT 

comment : <!–data-->

xparserCDATA 

cdata : data

xparserTEXT 

text : data

xparserLAST 

dummy for array sizing

◆ xparser_textmode

flags for text handling

Function Documentation

◆ xparser_col()

unsigned int xparser_col ( xparser *  parser)

Read the source column.

Parameters
parserRequired initialized parser.
Returns
Current source column number, starting at 1.

◆ xparser_count()

size_t xparser_count ( xparser *  parser)

Read the input position.

Parameters
parserRequired initialized parser.
Returns
Number of source bytes parsed.

◆ xparser_create()

xparser * xparser_create ( void  )

create a parser.

Returns
pointer to newly-created parser, or NULL.

◆ xparser_createalloc()

xparser * xparser_createalloc ( xparser_alloc  pa,
void *  ud 
)

Create a parser with its own allocator callback and context.

Parameters
paRequired allocation callback, retained through destruction.
udOptional borrowed callback context; must outlive the parser.
Returns
New parser or NULL if pa is NULL or allocation fails. The callback must preserve an existing block on positive-size failure. All parser storage, including the parser itself, uses this allocator.

◆ xparser_depth()

unsigned int xparser_depth ( xparser *  parser)

Read the nesting depth.

Parameters
parserRequired initialized parser.
Returns
Current tag-stack depth.

◆ xparser_destroy()

void xparser_destroy ( xparser *  parser)

destroy a parser

the TERM handler will be called, if not already terminated.

Parameters
[in]parserThe parser context.

◆ xparser_errormsg()

const char * xparser_errormsg ( xparser *  parser)

Read the last parser error.

Parameters
parserRequired initialized parser.
Returns
Borrowed error-message text, or an empty string when no error message is set.

◆ xparser_finish()

int xparser_finish ( xparser *  parser)

Check end of input without invoking callbacks.

Parameters
parserRequired initialized parser; remains owned by the caller.
Returns
0 if one root and all trailing syntax are complete, -1 otherwise. Repeated successful calls are harmless. After success, reset before parsing another document. Failure requires reset; xparser_errormsg() describes it.

◆ xparser_flags()

unsigned int xparser_flags ( xparser *  parser)

Read whitespace-processing flags.

Parameters
parserRequired initialized parser.
Returns
Current parser whitespace flags.

◆ xparser_has_doc()

int xparser_has_doc ( xparser *  parser)

Check whether the document node was parsed.

Parameters
parserRequired initialized parser.
Returns
Nonzero if the document node has been parsed; zero otherwise.

◆ xparser_init()

int xparser_init ( xparser *  parser,
xparser_handlers *  handlers,
void *  userdata,
unsigned int  options 
)

initialise a parser.

handlers is a pointer to a table of event handlers.
options is one of the textmode flags.
If the parser was previously initialised and not terminated,
its TERM handler will be called !
the INIT handler will be called, if supplied, from init()

Parameters
[in]parserThe parser context.
[in]handlerspointer to handlers
[in]userdataopaque user data that will be returned by xparser_userdata()
[in]optionsone of the values of enum xparser_textmode
Returns
return value from the init handler, or 0.

◆ xparser_line()

unsigned int xparser_line ( xparser *  parser)

Read the source line.

Parameters
parserRequired initialized parser.
Returns
Current source line number, starting at 1.

◆ xparser_parse()

int xparser_parse ( xparser *  parser,
const char *  pData,
size_t  datalen 
)

parse a chunk of xml data.

the event handlers will be called as events occur.
parse() can be called repeatedly with successive nonempty chunks of text. has_doc() indicates that the root closed, not that trailing input is complete. Call xparser_finish() after supplying all chunks to check end of input. An error or nonzero callback return requires reset before further parsing.

Parameters
[in]parserThe parser context.
[in]pDatapointer to data to be parsed.
[in]datalensize of data in pData
Returns
returns 0 on successful parse, -1 on error, or non-zero callback return value.

◆ xparser_reset()

int xparser_reset ( xparser *  parser,
int  full 
)

reset a parser to post-create state.

the RESET handler will be called, if supplied.

Parameters
[in]parserThe parser context.
[in]fullthe 'full' flag will cause reset() to deallocate all internal buffers.
Returns
0 or reset handler return code

◆ xparser_setalloc()

void xparser_setalloc ( xparser_alloc  pa,
void *  ud 
)

Install the default allocator for subsequent xparser_create calls.

Existing parsers retain their allocator and context through destruction. The caller must serialize changes to this default and parser creation. Call with NULL allocator to revert to the internal allocator.

Parameters
paDefault allocation callback, or NULL to restore the configured internal allocator.
udOptional borrowed allocator context retained by subsequently created parsers.

◆ xparser_term()

int xparser_term ( xparser *  parser)

destroy a parser, WITHOUT deallocating pointer.

the TERM handler will be called, if supplied This function is supplied for ease of interfacing with Lua.

Parameters
[in]parserThe parser context.
Returns
value is 0, or TERM handler return.

◆ xparser_userdata()

void * xparser_userdata ( xparser *  parser)

Retrieve the application context.

Parameters
parserRequired initialized parser.
Returns
The borrowed user-data pointer supplied during creation or initialization.

Variable Documentation

◆ xparser_eventname

const char* const xparser_eventname[xparserLAST]
extern

array lookup for event names

one of the following ordered values - "NONE", "INIT", "RESET", "TERM", "START", "XML", "START_ELEMENT", "END_ELEMENT", "EMPTY_ELEMENT", "PI", "COMMENT", "CDATA", "TEXT"

See also
xparser_event these values are the same names as xparser_event with the prefix removed