|
Barracuda Application Server C/C++ Reference
Native APIs, integration guides, and platform interfaces
|
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.

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 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.
| typedef int(* xparser_callback) (xparser *parser, void *userdata, xparser_event event, const char *name, const char **attr, const char *data) |
xparser user callback.
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.
| enum 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 |
| enum xparser_textmode |
flags for text handling
| unsigned int xparser_col | ( | xparser * | parser | ) |
Read the source column.
| parser | Required initialized parser. |
| size_t xparser_count | ( | xparser * | parser | ) |
Read the input position.
| parser | Required initialized parser. |
| xparser * xparser_create | ( | void | ) |
create a parser.
| xparser * xparser_createalloc | ( | xparser_alloc | pa, |
| void * | ud | ||
| ) |
Create a parser with its own allocator callback and context.
| pa | Required allocation callback, retained through destruction. |
| ud | Optional borrowed callback context; must outlive the parser. |
| unsigned int xparser_depth | ( | xparser * | parser | ) |
Read the nesting depth.
| parser | Required initialized parser. |
| void xparser_destroy | ( | xparser * | parser | ) |
destroy a parser
the TERM handler will be called, if not already terminated.
| [in] | parser | The parser context. |
| const char * xparser_errormsg | ( | xparser * | parser | ) |
Read the last parser error.
| parser | Required initialized parser. |
| int xparser_finish | ( | xparser * | parser | ) |
Check end of input without invoking callbacks.
| parser | Required initialized parser; remains owned by the caller. |
| unsigned int xparser_flags | ( | xparser * | parser | ) |
Read whitespace-processing flags.
| parser | Required initialized parser. |
| int xparser_has_doc | ( | xparser * | parser | ) |
Check whether the document node was parsed.
| parser | Required initialized parser. |
| 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()
| [in] | parser | The parser context. |
| [in] | handlers | pointer to handlers |
| [in] | userdata | opaque user data that will be returned by xparser_userdata() |
| [in] | options | one of the values of enum xparser_textmode |
| unsigned int xparser_line | ( | xparser * | parser | ) |
Read the source line.
| parser | Required initialized parser. |
| 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.
| [in] | parser | The parser context. |
| [in] | pData | pointer to data to be parsed. |
| [in] | datalen | size of data in pData |
| int xparser_reset | ( | xparser * | parser, |
| int | full | ||
| ) |
reset a parser to post-create state.
the RESET handler will be called, if supplied.
| [in] | parser | The parser context. |
| [in] | full | the 'full' flag will cause reset() to deallocate all internal buffers. |
| 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.
| pa | Default allocation callback, or NULL to restore the configured internal allocator. |
| ud | Optional borrowed allocator context retained by subsequently created parsers. |
| 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.
| [in] | parser | The parser context. |
| void * xparser_userdata | ( | xparser * | parser | ) |
Retrieve the application context.
| parser | Required initialized parser. |
|
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"