XMPP Stream parser for JabberWerxC. More...

#include <event2/buffer.h>
#include "../dom.h"
#include "../eventing.h"

Macros
#define	JW_PARSER_EVENT_CLOSED "parserEventClosed"

#define	JW_PARSER_EVENT_OPEN "parserEventOpened"

#define	JW_PARSER_EVENT_ELEMENT "parserEventElement"

Typedefs
typedef struct _jw_parser	jw_parser

Functions
JABBERWERX_API bool	jw_parser_create (bool stream_parser, jw_parser *parser, jw_err err)

JABBERWERX_API void	jw_parser_destroy (jw_parser *parser)

JABBERWERX_API bool	jw_parser_process (jw_parser parser, struct evbuffer buffer, jw_err *err)

JABBERWERX_API bool	jw_parse_xml (const char source, jw_dom_node parsed_dom, jw_err err)

JABBERWERX_API bool	jw_parse_xml_buffer (struct evbuffer buffer, jw_dom_node parsed_dom, jw_err err)

JABBERWERX_API jw_event *	jw_parser_event (jw_parser parser, const char name)

Detailed Description

XMPP Stream parser for JabberWerxC.

Copyrights

Macro Definition Documentation

#define JW_PARSER_EVENT_CLOSED "parserEventClosed"

Root closing tag has been parsed

#define JW_PARSER_EVENT_ELEMENT "parserEventElement"

A first level child of root has been parsed

#define JW_PARSER_EVENT_OPEN "parserEventOpened"

Root open tag has been parsed and is held "open"

Typedef Documentation

typedef struct _jw_parser jw_parser

An instance of an xml parser

Function Documentation

JABBERWERX_API bool jw_parse_xml	(	const char *	source,
		jw_dom_node **	parsed_dom,
		jw_err *	err
	)

Stand alone parse of given string

Parse the given string into a new jw_dom_node. The parser does not own any new nodes created, the node MUST be freed by the caller. Failure to do so will result in memory leaks.

Returns false and sets error if source is bad xml or dom could not be created.

err is set when returning false:

JW_ERR_INVALID_ARG if buffer results in an xml parse error
JW_ERR_NO_MEMORY if dom could not be created

Invariant: parsed_dom != NULL

Parameters

[in]	source	The xml fragment to parse. May be NULL or empty.
[out]	parsed_dom	The resultant DOM. NULL if source was NULL or empty
[out]	err	The error information (provide NULL to ignore)

Return values

bool	True if source could be parsed into dom.

JABBERWERX_API bool jw_parse_xml_buffer	(	struct evbuffer *	buffer,
		jw_dom_node **	parsed_dom,
		jw_err *	err
	)

Parse the given buffer

Parse the given buffer into a new jw_dom_node. The parser does not own any new nodes created, the node MUST be freed by the caller. Failure to do so will result in memory leaks.

Returns false and sets error if source is bad xml or dom could not be created.

err is set when returning false:

JW_ERR_INVALID_ARG if buffer results in an xml parse error
JW_ERR_NO_MEMORY if dom could not be created

Invariant: parsed_dom != NULL

Parameters

[in]	buffer	The evbuffer to parse. May be NULL or empty. The buffer will be completely drained on success. Its contents are undefined if an error occurs.
[out]	parsed_dom	The resultant DOM. NULL if buffer was NULL or empty
[out]	err	The error information (provide NULL to ignore)

Return values

bool	True if buffer could be parsed into dom.

JABBERWERX_API bool jw_parser_create	(	bool	stream_parser,
		jw_parser **	parser,
		jw_err *	err
	)

Create a new XML parser. Parser may be created as either a "stream" parser or an element parser. A stream parser treats the root element as a special stream element, firing JW_PARSER_OPEN when its open tag is found, JW_PARSER_ELEMENT when each of its first level children are parsed and JW_PARSER_CLOSED when the root element is closed.

Non stream parsers do not fire stream open and close events. The root element(s) invokes a JW_PARSER_ELEMENT when it has been completely parsed.

This allows jw_parser to be used to continuously parse elements from an XMPP stream and as a stand alone parser for xml fragments.

A parser may fire three events; open, element and closed.

JW_PARSER_EVENT_OPEN will fire when the root's open element has been parsed. The parsed stream open element is passed to the event
JW_PARSER_EVENT_ELEMENT will fire when a child of root has been parsed, passing the child to the event.
JW_PARSER_EVENT_CLOSED will fire when a root close is parsed. A NULL is passed as the element.

Note - A non-NULL element will be destroyed by the parser once all callbacks have completed. The parser may create a new jw_dom_ctx for every element passed through these events.

err is set when returning false:

JW_ERR_NO_MEMORY if the parser could not be allocated

Invariant: parser != NULL

Parameters

[in]	stream_parser	true if parser is a stream parser, false creates an element parser.
[out]	parser	The new parser
[out]	err	The error information (provide NULL to ignore)

Return values

bool	True if parser was successfully created, else false.

JABBERWERX_API void jw_parser_destroy ( jw_parser * parser )

Destroy the given parser.

Invariant: parser != NULL

Parameters

[in] parser The new parser to destroy

JABBERWERX_API jw_event* jw_parser_event	(	jw_parser *	parser,
		const char *	name
	)

Get a parser event. Returns the event on success and NULL if event is not found. The memory allocated for the event will continue to be owned by the parser.

Invariant: parser != NULL; name != NULL; *name != '\0'

Parameters

[in]	parser	The parser owning the event dispatcher.
[in]	name	The name of the event.

Return values

jw_event The found event or NULL if it does not exist.

JABBERWERX_API bool jw_parser_process	(	jw_parser *	parser,
		struct evbuffer *	buffer,
		jw_err *	err
	)

Parse the given buffer and fire corresponding events.

err is set when returning false:

JW_ERR_INVALID_ARG if buffer results in an xml parse error
JW_ERR_INVALID_STATE if a previous parse error was enccountered.
JW_ERR_NO_MEMORY if the parser could not be allocated

If an error occurs during a process call the parser is moved to an invalid state and cannot be used for parsing again. Subsequent calls to jw_parser_process will always return a JW_ERR_INVALID_STATE error. The parser should be destroyed and recreated to continue parsing.

Invariant: parser != NULL

Parameters

[in]	parser	The parser to use.
[in]	buffer	The evbuffer to parse. May be NULL or empty. buffer is completely drained on success. Its contents are undefined if an error occurred.
[out]	err	The error information (provide NULL to ignore)

Return values

bool	True If buffer does not generate an xml parse error.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation