XML stream serializer for JabberWerxC. More...

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

Typedefs
typedef struct _jw_serializer	jw_serializer

Functions
JABBERWERX_API bool	jw_serializer_create (struct evbuffer out, jw_serializer ser, jw_err err)

JABBERWERX_API void	jw_serializer_destroy (jw_serializer *ser)

JABBERWERX_API struct evbuffer *	jw_serializer_get_output (jw_serializer *ser)

JABBERWERX_API bool	jw_serializer_is_open (jw_serializer *ser)

JABBERWERX_API bool	jw_serializer_write_start (jw_serializer ser, jw_dom_node root, jw_err *err)

JABBERWERX_API bool	jw_serializer_write (jw_serializer ser, jw_dom_node node, jw_err *err)

JABBERWERX_API bool	jw_serializer_write_end (jw_serializer ser, jw_err err)

JABBERWERX_API bool	jw_serialize_xml (jw_dom_node dom, char xml, size_t len, jw_err *err)

JABBERWERX_API bool	jw_serialize_xml_buffer (jw_dom_node dom, struct evbuffer buffer, size_t len, jw_err err)

Detailed Description

XML stream serializer for JabberWerxC.

NOTE: This API is not thread-safe. Users MUST ensure access to all instances of a serializer is limited to a single thread.

Copyrights

Typedef Documentation

typedef struct _jw_serializer jw_serializer

An instance of a xml serializer

Function Documentation

JABBERWERX_API bool jw_serialize_xml	(	jw_dom_node *	dom,
		char **	xml,
		size_t *	len,
		jw_err *	err
	)

Serializes the given DOM element into an XML string.

NOTE: This function allocates the memory for the returned XML string as needed. Users MUST destroy the memory allocated via jw_data_free(xml), and SHOULD NOT allocate memory for xml directly.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if there is not enough memory to serialize dom

Invariant: dom != NULL; jw_dom_get_nodetype(dom) == JW_DOM_TYPE_ELEMENT; xml != NULL

Parameters

[in]	dom	The DOM element to serialize
[out]	xml	The XML string for dom
[out]	len	If non-NULL, the length of the XML string for dom
[out]	err	The error information (provide NULL to ignore)

Return values

bool	true if successful, false otherwise.

JABBERWERX_API bool jw_serialize_xml_buffer	(	jw_dom_node *	dom,
		struct evbuffer *	buffer,
		size_t *	len,
		jw_err *	err
	)

Serializes the given DOM element into an evbuffer.

NOTE: The data written to the buffer does NOT include a NULL terminator.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if there is not enough memory to serialize dom

Invariant: dom != NULL; jw_dom_get_nodetype(dom) == JW_DOM_TYPE_ELEMENT; buffer != NULL

Parameters

[in]	dom	The DOM element to serialize
[out]	buffer	The evbuffer containing serialized dom
[out]	len	The length of the serialized dom
[out]	err	The error information (provide NULL to ignore)

Return values

bool	true if successful, false otherwise.

JABBERWERX_API bool jw_serializer_create	(	struct evbuffer *	out,
		jw_serializer **	ser,
		jw_err *	err
	)

Creates a new serializer, using the given buffer for output.

NOTE: The output buffer is not owned by this serializer. The API user MUST free the buffer when finished; jw_serializer_destroy() does not destroy it.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the serializer could not be allocated

Invariant: ser != NULL; out != NULL

Parameters

[in]	out	The evbuffer to serialize to
[out]	ser	The new serializer
[out]	err	The error information (provide NULL to ignore)

Return values

bool	True if serializer was successfully created, else false.

JABBERWERX_API void jw_serializer_destroy ( jw_serializer * ser )

Destroys the given serializer.

NOTE: The output buffer associated with ser is not freed when this function is called. The API user MUST destroy the buffer manually.

Invariant: (ser != NULL)

Parameters

[in] ser The serializer to destroy

JABBERWERX_API struct evbuffer* jw_serializer_get_output ( jw_serializer * ser )

Retrieves the output buffer for the given serializer.

WARNING: Users SHOULD NOT write to this buffer directly without good reason; modifying the buffer directly can result in malformed XML.

Invariant: ser != NULL

Parameters

[in] ser The serializer

Return values

struct evbuffer * The output buffer

JABBERWERX_API bool jw_serializer_is_open ( jw_serializer * ser )

Retrieves the current open state of the given serializer. This function returns true after jw_serializer_open() but before jw_serializer_close().

Invariant: ser != NULL

Parameters

[in] ser The serializer

Return values

bool	True if the serializer is open, false otherwise

JABBERWERX_API bool jw_serializer_write	(	jw_serializer *	ser,
		jw_dom_node *	node,
		jw_err *	err
	)

Processes the given DOM node into this serializer. If this serializer is not open, it will open it using node, then close it before returning successfully.

NOTE: This function does not immediately free all memory allocated. Most will be freed when jw_serializer_destroy() is called, although any memory allocated to the configured buffer will be released when it is destroyed.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if memory could not be allocted for serializing.
JW_ERR_INVALID_ARG if this serializer is not open, and node is is not a JW_DOM_TYPE_ELEMENT

Invariant: ser != NULL; node != NULL; (jw_dom_get_nodetype(node) == JW_DOM_TYPE_ELEMENT) || (jw_dom_get_nodetype(node) == JW_DOM_TYPE_TEXT)

Parameters

[in]	ser	The serializer
[in]	node	The node DOM node to process
[out]	err	The error information (provide NULL to ignore)

Return values

bool	True if node was successfully processed, else false.

JABBERWERX_API bool jw_serializer_write_end	(	jw_serializer *	ser,
		jw_err *	err
	)

Closes the given serializer. This function writes the end tag that matches the root DOM element from jw_serializer_open().

NOTE: This function does not immediately free all memory allocated. Most will be freed when jw_serializer_destroy() is called, although any memory allocated to the configured buffer will be released when it is destroyed.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if memory could not be allocted for serializing.
JW_ERR_INVALID_STATE if the serializer is not open

Invariant: ser != NULL

Parameters

[in]	ser	The serializer
[out]	err	The error information (provide NULL to ignore)

Return values

bool	True if serializer was successfully closed, else false.

JABBERWERX_API bool jw_serializer_write_start	(	jw_serializer *	ser,
		jw_dom_node *	root,
		jw_err *	err
	)

Opens the given serializer, using the given root element. This function writes start tag based on the information from root (expanded name, namespace declarations, and attributes), but does not process any children of root.

NOTE: This function does not immediately free all memory allocated. Most will be freed when jw_serializer_destroy() is called, although any memory allocated to the configured buffer will be released when it is destroyed.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if memory could not be allocted for serializing.
JW_ERR_INVALID_STATE if the serializer is already open

Invariant: ser != NULL; root != NULL; jw_dom_get_nodetype(root) == JW_DOM_TYPE_ELEMENT

Parameters

[in]	ser	The serializer
[in]	root	The root DOM element
[out]	err	The error information (provide NULL to ignore)

Return values

bool	True if node was successfully opened, else false.

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation