The Expat API wrapper is an RDR-discoverable interface that provides access to the Expat XML parser library. More...

Files
file	expatapi.h
	Header file defining the Expat XML parser interface API.

file	expatrdr.h
	Functions to register and deregister the Expat API.

Data Structures
struct	sw_expat_api_20201221
	The Expat API version 20201221. More...

Macros
#define	XML_ParserCreate_MM expat_api->XML_ParserCreate_MM
	Create an XML parser instance specifying memory handling functions and namespace processing. More...

#define	XML_ParserFree expat_api->XML_ParserFree
	Free an XML parser instance. More...

#define	XML_SetXmlDeclHandler expat_api->XML_SetXmlDeclHandler
	Set the XML declaration handler callback. More...

#define	XML_SetNamespaceDeclHandler expat_api->XML_SetNamespaceDeclHandler
	Set the namespace declaration handler callbacks. More...

#define	XML_SetDoctypeDeclHandler expat_api->XML_SetDoctypeDeclHandler
	Set the DOCTYPE declaration handler callbacks. More...

#define	XML_SetElementHandler expat_api->XML_SetElementHandler
	Set the element handler callbacks. More...

#define	XML_SetCharacterDataHandler expat_api->XML_SetCharacterDataHandler
	Set the CDATA handler callback. More...

#define	XML_SetProcessingInstructionHandler expat_api->XML_SetProcessingInstructionHandler
	Set the XML processing instruction handler callback. More...

#define	XML_SetCommentHandler expat_api->XML_SetCommentHandler
	Set the XML comment handler callback. More...

#define	XML_SetCdataSectionHandler expat_api->XML_SetCdataSectionHandler
	Set the CDATA section handler callbacks. More...

#define	XML_SetReturnNSTriplet expat_api->XML_SetReturnNSTriplet
	Set the XML comment handler callback. More...

#define	XML_SetUserData expat_api->XML_SetUserData
	Set the user data pointer passed to callback functions. More...

#define	XML_Parse expat_api->XML_Parse
	Parse a chunk of XML data. More...

#define	XML_GetBuffer expat_api->XML_GetBuffer
	Get a buffer to read XML data into. More...

#define	XML_ParseBuffer expat_api->XML_ParseBuffer
	Parse a chunk of XML data stored in an internal buffer. More...

#define	XML_StopParser expat_api->XML_StopParser
	Stop an XML parser. More...

#define	XML_GetErrorCode expat_api->XML_GetErrorCode
	Get the error code from a failed parsing operation. More...

#define	XML_GetCurrentLineNumber expat_api->XML_GetCurrentLineNumber
	Get the line number where an error occurred. More...

#define	XML_GetCurrentColumnNumber expat_api->XML_GetCurrentColumnNumber
	Get the column number where an error occurred. More...

#define	XML_GetCurrentByteIndex expat_api->XML_GetCurrentByteIndex
	Get the byte index where an error occurred. More...

#define	XML_ErrorString expat_api->XML_ErrorString
	Return an error string corresponding to an XML error code. More...

Detailed Description

The Expat API wrapper is an RDR-discoverable interface that provides access to the Expat XML parser library.

These calls are based on the Expat library API, but not all calls in the Expat API are exposed through this API.

Discovering Expat

An Expat API pointer must be discovered using RDR using class RDR_CLASS_API and type RDR_API_EXPAT and assigned to a suitably-named API pointer variable before the API macros are used. The Expat API is automatically registered when the Harlequin RIP is started. It is deregistered when the Harlequin RIP is shutdown.

Parsing XML with Expat

The normal sequence of calls to parse XML using this API is:

Create a parser object using XML_ParserCreate_MM(). Global Graphics recommends using memory allocation and free functions that allocate from the RIP or Skin's memory pools, such as SwAlloc() and SwFree() for RIP pools, or MemAlloc() and MemFree() for skin pools.
Set the handler callback functions for the required XML declarations, using XML_SetNamespaceDeclHandler(), XML_SetDoctypeDeclHandler(), XML_SetElementHandler(), XML_SetCharacterDataHandler(), XML_SetProcessingInstructionHandler(), XML_SetCommentHandler(), XML_SetCdataSectionHandler() and/or XML_SetReturnNSTriplet().
Set the user data pointer passed to callback functions with XML_SetUserData().
Repeatedly parse chunks of XML data by you provide by calling XML_Parse(), or calling XML_GetBuffer(), reading XML data into the buffer and then calling XML_ParseBuffer(). This will provoke callbacks to the functions registered previously. Callbacks may call XML_StopParser() to stop parsing.
Destroy the XML parser by calling XML_ParserFree().

Error handling

If you detect an error in a parser callback function, you can call XML_StopParser(parser, XML_FALSE) to abort XML parsing.

If there is an error detected during parsing, XML_Parse() or XML_ParseBuffer() will return XML_STATUS_ERROR. You can then call XML_GetErrorCode() to get the error code, and XML_ErrorString() to convert this code into a readable string. The line and column number where the error occurred can be found by calling XML_GetCurrentLineNumber() and XML_GetCurrentColumnNumber(). The byte index where the error occurred can be found by calling XML_GetCurrentByteIndex().

Macro Definition Documentation

◆ XML_ErrorString

#define XML_ErrorString expat_api->XML_ErrorString

Return an error string corresponding to an XML error code.

Parameters

[in] code An XML error code returned by XML_GetErrorCode().

Returns: A string describing the error in code.

See the Expat API documentation for more details.

◆ XML_GetBuffer

#define XML_GetBuffer expat_api->XML_GetBuffer

Get a buffer to read XML data into.

Parameters

[in] len The number of bytes to store in the buffer.

Returns: A buffer of at least len to read XML data into, or NULL on error.

Using XML_GetBuffer() and XML_ParseBuffer() avoids an extra data copy if you are reading data from a file or non-memory source. If the XML data is already in memory, using XML_Parse() is equivalent.

See the Expat API documentation for more details.

◆ XML_GetCurrentByteIndex

#define XML_GetCurrentByteIndex expat_api->XML_GetCurrentByteIndex

Get the byte index where an error occurred.

Parameters

[in] parser An XML parser handle.

Returns: The current byte index in the XML document.

See the Expat API documentation for more details.

◆ XML_GetCurrentColumnNumber

#define XML_GetCurrentColumnNumber expat_api->XML_GetCurrentColumnNumber

Get the column number where an error occurred.

Parameters

[in] parser An XML parser handle.

Returns: The current column number.

See the Expat API documentation for more details.

◆ XML_GetCurrentLineNumber

#define XML_GetCurrentLineNumber expat_api->XML_GetCurrentLineNumber

Get the line number where an error occurred.

Parameters

[in] parser An XML parser handle.

Returns: The current line number.

See the Expat API documentation for more details.

◆ XML_GetErrorCode

#define XML_GetErrorCode expat_api->XML_GetErrorCode

Get the error code from a failed parsing operation.

Parameters

[in] parser An XML parser handle.

Returns: One of the XML_ERROR_* enumeration codes. An error string corresponding to this error code can be returned by calling XML_ErrorString().

See the Expat API documentation for more details.

◆ XML_Parse

#define XML_Parse expat_api->XML_Parse

Parse a chunk of XML data.

Parameters

[in]	parser	An XML parser handle.
[in]	s	A buffer containing part or all of an XML document.
[in]	len	The number of bytes in buffer s.
[in]	isFinal	A flag indicating if this is the last buffer of data for the document.

Return values

XML_STATUS_OK	on success.
XML_STATUS_ERROR	if there was a parse error.

Calling this function will provoke callbacks to functions registered for the declarations, elements, comments, and character data.

Using XML_GetBuffer() and XML_ParseBuffer() avoids an extra data copy if you are reading data from a file or non-memory source. If the XML data is already in memory, using XML_Parse() is equivalent.

See the Expat API documentation for more details.

◆ XML_ParseBuffer

#define XML_ParseBuffer expat_api->XML_ParseBuffer

Parse a chunk of XML data stored in an internal buffer.

Parameters

[in]	parser	An XML parser handle.
[in]	len	The number of bytes in buffer s.
[in]	isFinal	A flag indicating if this is the last buffer of data for the document.

Return values

XML_STATUS_OK	on success.
XML_STATUS_ERROR	if there was a parse error.

This function parses data previously loaded into an Expat internal buffer allocated using XML_GetBuffer(). Calling this function will provoke callbacks to functions registered for the declarations, elements, comments, and character data.

Using XML_GetBuffer() and XML_ParseBuffer() avoids an extra data copy if you are reading data from a file or non-memory source. If the XML data is already in memory, using XML_Parse() is equivalent.

See the Expat API documentation for more details.

◆ XML_ParserCreate_MM

#define XML_ParserCreate_MM expat_api->XML_ParserCreate_MM

Create an XML parser instance specifying memory handling functions and namespace processing.

Parameters

[in]	encoding	The encoding of the XML, or `NULL` if none specified.
[in]	memsuite	A structure with allocation, reallocation, and free functions.
[in]	namespaceSeparator	Namespace expanded element names and attribute names are returned as a concatenation of the namespace URI, namespaceSeparator, and the local part of the name.

Returns: An XML parser handle on success, or NULL on failure.

Note: Global Graphics recommends using memory allocation and free functions that allocate from the RIP or Skin's memory pools, such as SwAlloc() and SwFree() for RIP pools, or MemAlloc() and MemFree() for skin pools.

See the Expat API documentation for more details.

◆ XML_ParserFree

#define XML_ParserFree expat_api->XML_ParserFree

Free an XML parser instance.

Parameters

[in] parser An XML parser handle.

See the Expat API documentation for more details.

◆ XML_SetCdataSectionHandler

#define XML_SetCdataSectionHandler expat_api->XML_SetCdataSectionHandler

Set the CDATA section handler callbacks.

Parameters

[in]	parser	An XML parser handle.
[in]	start	CDATA section start callback function. This function is called with user data only.
[in]	end	CDATA section end callback function. This function is called with user data only.

See the Expat API documentation for more details.

◆ XML_SetCharacterDataHandler

#define XML_SetCharacterDataHandler expat_api->XML_SetCharacterDataHandler

Set the CDATA handler callback.

Parameters

[in]	parser	An XML parser handle.
[in]	handler	CDATA callback function. This function is called with user data, a pointer to the character data, and the length of the character data.

See the Expat API documentation for more details.

◆ XML_SetCommentHandler

#define XML_SetCommentHandler expat_api->XML_SetCommentHandler

Set the XML comment handler callback.

Parameters

[in]	parser	An XML parser handle.
[in]	handler	Comment callback function. This function is called with user data and a pointer to the comment.

See the Expat API documentation for more details.

◆ XML_SetDoctypeDeclHandler

#define XML_SetDoctypeDeclHandler expat_api->XML_SetDoctypeDeclHandler

Set the DOCTYPE declaration handler callbacks.

Parameters

[in]	parser	An XML parser handle.
[in]	start	Document type start callback function. This function is called with user data, the DOCTYPE name, a SYSTEM ID, a PUBLIC ID and flag indicating if the document type has an internal subset.
[in]	end	Document type end callback function. This function is called with user data only.

See the Expat API documentation for more details.

◆ XML_SetElementHandler

#define XML_SetElementHandler expat_api->XML_SetElementHandler

Set the element handler callbacks.

Parameters

[in]	parser	An XML parser handle.
[in]	start	Element start callback function. This function is called with user data, the element name, and an array of element attribute name,value pairs terminated by a `NULL` pointers.
[in]	end	Element end callback function. This function is called with user data and the element name.

See the Expat API documentation for more details.

◆ XML_SetNamespaceDeclHandler

#define XML_SetNamespaceDeclHandler expat_api->XML_SetNamespaceDeclHandler

Set the namespace declaration handler callbacks.

Parameters

[in]	parser	An XML parser handle.
[in]	start	Namespace start callback function. This function is called with user data, the namespace prefix, and the namespace URI.
[in]	end	Namespace end callback function. This function is called with user data and the namespace prefix.

See the Expat API documentation for more details.

◆ XML_SetProcessingInstructionHandler

#define XML_SetProcessingInstructionHandler expat_api->XML_SetProcessingInstructionHandler

Set the XML processing instruction handler callback.

Parameters

[in]	parser	An XML parser handle.
[in]	handler	Processing instruction callback function. This function is called with user data, a target pointer and data pointer. The target is the first word in the processing instruction. The data is the rest of the characters in it after skipping all whitespace after the initial word.

See the Expat API documentation for more details.

◆ XML_SetReturnNSTriplet

#define XML_SetReturnNSTriplet expat_api->XML_SetReturnNSTriplet

Set the XML comment handler callback.

Parameters

[in]	parser	An XML parser handle.
[in]	do_nst	A flag indicating whether qualified namespace names are returned as three parts (URI, local name, and prefix), or as one.

See the Expat API documentation for more details.

◆ XML_SetUserData

#define XML_SetUserData expat_api->XML_SetUserData

Set the user data pointer passed to callback functions.

Parameters

[in]	parser	An XML parser handle.
[in]	userData	The user data pointer that is passed to callback functions.

See the Expat API documentation for more details.

◆ XML_SetXmlDeclHandler

#define XML_SetXmlDeclHandler expat_api->XML_SetXmlDeclHandler

Set the XML declaration handler callback.

Parameters

[in]	parser	An XML parser handle.
[in]	xmldecl	XML callback function. This function is called with user data, the XML version, the XML encoding and an indication of the state of the XML standalone attribute.

See the Expat API documentation for more details.

◆ XML_StopParser

#define XML_StopParser expat_api->XML_StopParser

Stop an XML parser.

Parameters

[in]	parser	An XML parser handle.
[in]	resumable	`XML_FALSE` if aborting the parse, `XML_TRUE` if the parsing may be resumed later.

Return values

XML_STATUS_OK	on success.
XML_STATUS_ERROR	if there was an error.

See the Expat API documentation for more details.

Files

Data Structures

Macros

Detailed Description

Discovering Expat

Parsing XML with Expat

Error handling

Macro Definition Documentation

◆ XML_ErrorString

◆ XML_GetBuffer

◆ XML_GetCurrentByteIndex

◆ XML_GetCurrentColumnNumber

◆ XML_GetCurrentLineNumber

◆ XML_GetErrorCode

◆ XML_Parse

◆ XML_ParseBuffer

◆ XML_ParserCreate_MM

◆ XML_ParserFree

◆ XML_SetCdataSectionHandler

◆ XML_SetCharacterDataHandler

◆ XML_SetCommentHandler

◆ XML_SetDoctypeDeclHandler

◆ XML_SetElementHandler

◆ XML_SetNamespaceDeclHandler

◆ XML_SetProcessingInstructionHandler

◆ XML_SetReturnNSTriplet

◆ XML_SetUserData

◆ XML_SetXmlDeclHandler

◆ XML_StopParser