Public header file for the APG XML parser API.. More...

#include <limits.h>
#include "../utilities/utilities.h"

Include dependency graph for xml.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	xmldecl_info
	Information about the XML declaration. More...

struct	dtd_info
	Information about the Document Type Declaration. More...

Macros
#define	DEFAULT_CALLBACK (void*)1
	Indicator for a pre-defined, default callback function. More...

Typedefs
typedef void(*	pfnXmlDeclCallback) (xmldecl_info spInfo, void vpUserData)
	Defines the function type that is called after parsing the XML declaration. More...

typedef void(*	pfnDTDCallback) (dtd_info spInfo, void vpUserData)
	Defines the function type that is called after parsing the Document Type Declaration (DTD). More...

typedef void(*	pfnStartTagCallback) (u32_phrase spName, u32_phrase spAttNames, u32_phrase spAttValues, uint32_t uiAttCount, void vpUserData)
	Defines the function type that is called after an element's start tag has been found. More...

typedef void(*	pfnEmptyTagCallback) (u32_phrase spName, u32_phrase spAttrNames, u32_phrase spAttrValues, uint32_t uiAttrCount, void vpUserData)
	Defines the function type that is called after an empty tag has been found. More...

typedef void(*	pfnEndTagCallback) (u32_phrase spName, u32_phrase spContent, void *vpUserData)
	Defines the function type that is called after an element's end tag has been found. More...

typedef void(*	pfnPICallback) (u32_phrase spTarget, u32_phrase spInfo, void *vpUserData)
	Defines the function type that is called after a Processing Instruction has been found. More...

typedef void(*	pfnCommentCallback) (u32_phrase spComment, void vpUserData)
	Defines the function type that is called after a comment is found. More...

Functions
void *	vpXmlCtor (exception *spEx)
	The XML Parser constructor. More...

void	vXmlDtor (void *vpCtx)
	The XML Parser component destructor. More...

abool	bXmlValidate (void *vpCtx)
	Validate an XML context pointer. More...

void	vXmlGetFile (void vpCtx, const char cpFileName)
	Gets the XML byte stream from a file. More...

void	vXmlGetArray (void vpCtx, uint8_t ucpData, aint uiDataLen)
	Gets the XML byte stream from a byte array. More...

void	vXmlParse (void *vpCtx)
	Parse the XML data from vXmlGetFile or vXmlGetArray. More...

void	vXmlSetXmlDeclCallback (void vpCtx, pfnXmlDeclCallback pfnCallback, void vpUserData)
	Set the user's callback function for the XML declaration. More...

void	vXmlSetDTDCallback (void vpCtx, pfnDTDCallback pfnCallback, void vpUserData)
	Set the user's callback function for the Processing Instruction tags(`<?target instructions?>`). More...

void	vXmlSetEmptyTagCallback (void vpCtx, pfnEmptyTagCallback pfnCallback, void vpUserData)
	Set the user's callback function for the empty tags (`<name attr="10"/>`). More...

void	vXmlSetStartTagCallback (void vpCtx, pfnStartTagCallback pfnCallback, void vpUserData)
	Set the user's callback function for the start tags (`<name attr="10">`). More...

void	vXmlSetEndTagCallback (void vpCtx, pfnEndTagCallback pfnCallback, void vpUserData)
	Set the user's callback function for the end tags (`</name>`). More...

void	vXmlSetPICallback (void vpCtx, pfnPICallback pfnCallback, void vpUserData)
	Set the user's callback function for the Processing Instruction tags(`<?target instructions?>`). More...

void	vXmlSetCommentCallback (void vpCtx, pfnCommentCallback pfnCallback, void vpUserData)
	Set the user's callback function for comments. More...

void	vXmlDisplayInput (void *vpCtx, abool bShowLines)
	Display input file. More...

void	vXmlDisplayMsgs (void *vpCtx)
	Display the parser's messages on stdout, if any. More...

void *	vpXmlGetMsgs (void *vpCtx)
	Give the user a handle to the message log. More...

Detailed Description

Public header file for the APG XML parser API..

This file contains all of the public type definitions and the prototypes for the XML parser object.

Definition in file xml.h.

Macro Definition Documentation

◆ DEFAULT_CALLBACK

#define DEFAULT_CALLBACK (void*)1

Indicator for a pre-defined, default callback function.

For usage, see, for example, vXmlSetXmlDeclCallback().

Definition at line 51 of file xml.h.

Typedef Documentation

◆ pfnCommentCallback

pfnCommentCallback

Defines the function type that is called after a comment is found.

Note that all pointers are valid only for the duration of the called function. Applications must copy data to their own storage space if needed beyond the scope of this function call.

Parameters

spComment	The comment characters.
vpUserData	The user's private data, or NULL if none. This private data pointer is set in the function vXmlSetCommentCallback.

Definition at line 195 of file xml.h.

◆ pfnDTDCallback

pfnDTDCallback

Defines the function type that is called after parsing the Document Type Declaration (DTD).

This function is called whether the DTD exists or not.
Note that all pointers are valid only for the duration of the call. Applications must copy data to their own memory space if needed beyond the scope of this function call.

Parameters

spInfo	The DTD information
vpUserData	The user's private data, or NULL if none. This private data pointer is set in the function vXmlSetDTDCallback().

Definition at line 127 of file xml.h.

◆ pfnEmptyTagCallback

* pfnEmptyTagCallback

Defines the function type that is called after an empty tag has been found.

Note that this is in all respects similar to pfnStartTagCallback. The user may assign the same function to both of these pointers. They are separated to give the user the opportunity to recognize when to expect a matching end tag and not.
Note that all pointers are valid only for the duration of the called function. Applications must copy data to their own storage space if needed beyond the scope of this function call.

Parameters

spName	The attribute name.
spAttNames	An array of the attribute names.
spAttValues	An array of the attribute values.
uiAttCount	The number of attributes in the array.
vpUserData	The user's private data, or NULL if none. This private data pointer is set in the function vXmlSetEmptyTagCallback.

Definition at line 159 of file xml.h.

◆ pfnEndTagCallback

pfnEndTagCallback

Defines the function type that is called after an element's end tag has been found.

Note that all pointers are valid only for the duration of the called function. Applications must copy data to their own storage space if needed beyond the scope of this function call.

Parameters

spName	The element name.
spContent	The element character data.
vpUserData	The user's private data, or NULL if none. This private data pointer is set in the function vXmlSetEndTagCallback.

Definition at line 172 of file xml.h.

◆ pfnPICallback

pfnPICallback

Defines the function type that is called after a Processing Instruction has been found.

Note that all pointers are valid only for the duration of the called function. Applications must copy data to their own storage space if needed beyond the scope of this function call.

Parameters

spTarget	The Processing Instruction's target or name.
spInfo	The Processing Instruction's instructions or information.
vpUserData	The user's private data, or NULL if none. This private data pointer is set in the function vXmlSetPICallback.

Definition at line 184 of file xml.h.

◆ pfnStartTagCallback

* pfnStartTagCallback

Defines the function type that is called after an element's start tag has been found.

Note that all pointers are valid only for the duration of the called function. Applications must copy data to their own storage space if needed beyond the scope of this function call.

Parameters

spName	The attribute name.
spAttNames	An array of the attribute names.
spAttValues	An array of the attribute values.
uiAttCount	The number of attributes in the array.
vpUserData	The user's private data, or NULL if none. This private data pointer is set in the function vXmlSetStartTagCallback().

Definition at line 141 of file xml.h.

◆ pfnXmlDeclCallback

pfnXmlDeclCallback

Defines the function type that is called after parsing the XML declaration.

This function is called whether the XML declaration exists or not.
Note that all pointers are valid only for the duration of the called function. Applications must copy data to their own storage space if needed beyond the scope of this function call.

Parameters

spInfo	The XML declaration information
vpUserData	The user's private data, or NULL if none. This private data pointer is set in the function vXmlSetXmlDeclCallback.

Definition at line 115 of file xml.h.

Function Documentation

◆ bXmlValidate()

abool bXmlValidate ( void * vpCtx )

Validate an XML context pointer.

Parameters

[in] vpCtx pointer to the parser's context - previously returned from vpXmlCtor.

Returns: True if the pointer is a valid XML context pointer. False otherwise.

Definition at line 261 of file xml.c.

◆ vpXmlCtor()

void* vpXmlCtor ( exception * spEx )

The XML Parser constructor.

Allocates memory for the XML Parser component and constructs all of the required working memory vectors. All display is to stdout and the default values of all callback function pointers are NULL. To set the callback functions see:
vXmlSetXmlDeclCallback
vXmlSetDTDCallback
vXmlSetEmptyTagCallback
vXmlSetStartTagCallback
vXmlSetEndTagCallback
vXmlSetPICallback
vXmlSetCommentCallback
Note that this parser assumes that input is always in the form of 8-bit byte streams and that the type "char" is also 8-bits. For string functions, it is always assumed that conversions from uint8_t to char is OK.

Parameters

spEx	Pointer to a valid exception structure.

Returns: Pointer to the parser's context. An exception is thrown on memory allocation errors.

Definition at line 159 of file xml.c.

◆ vpXmlGetMsgs()

void* vpXmlGetMsgs ( void * vpCtx )

Give the user a handle to the message log.

Parameters

[in] vpCtx pointer to the parser's context - previously returned from vpXmlCtor.

Returns: Pointer to the parser's message log context.

Definition at line 579 of file xml.c.

◆ vXmlDisplayInput()

void vXmlDisplayInput	(	void *	vpCtx,
		abool	bShowLines
	)

Display input file.

This utility function will display the (converted^*) input byte stream in hexdump format, displaying the data as both hex bytes and ASCII for printing characters.
^*

if type is UTF-16 (BE or LE) it is converted to UTF-8 before display and parsing
the BOM, if present, is stripped
to display the original, as-is, file, use a hexdump utility external to this XML processor
Parameters

[in] vpCtx pointer to the parser's context - previously returned from vpXmlCtor.

[in] bShowLines - if true (!= 0) data is displayed by line number. Otherwise, just a dump blob.

Returns
void - an exception is thrown on any fatal error.

Definition at line 781 of file xml.c.

◆ vXmlDisplayMsgs()

void vXmlDisplayMsgs ( void * vpCtx )

Display the parser's messages on stdout, if any.

Nothing is displayed if there are no messages. Messages are collected as the parser detects errors in the DTD. Other than the DTD, fatal errors result in a thrown exception.

Parameters

[in] vpCtx pointer to the parser's context - previously returned from vpXmlCtor.

Returns: void - an exception is thrown on any fatal error.

Definition at line 565 of file xml.c.

◆ vXmlDtor()

void vXmlDtor ( void * vpCtx )

The XML Parser component destructor.

Releases all heap memory and clears the context to prevent accidental use after release.

Parameters

[in] vpCtx pointer to the parser's context - previously returned from vpXmlCtor.

Returns: void - an exception is thrown on any fatal error.

Definition at line 242 of file xml.c.

◆ vXmlGetArray()

void vXmlGetArray	(	void *	vpCtx,
		uint8_t *	ucpData,
		aint	uiDataLen
	)

Gets the XML byte stream from a byte array.

The first four characters are examined to determine the encoding scheme. The data is the normalized as follows:

If UTF-16(BE or LE), the data is converted to UTF-8.
All line ends are converted, if necessary, to a single line feed (0x0A)
The all characters are examined for XML validity.
- no control characters other than 0x09, 0x0A, 0x0D (tab, line feed, carriage return)
- any Unicode character, excluding the surrogate blocks, FFFE, and FFFF
An exception is thrown if any characters are not valid.

Parameters

[in]	vpCtx	pointer to the parser's context - previously returned from vpXmlCtor.
[in]	ucpData	- The input byte stream as an array of unsigned characters.
[in]	uiDataLen	- The number of bytes in the stream.

Returns: void - an exception is thrown on any fatal error.

Definition at line 418 of file xml.c.

◆ vXmlGetFile()

void vXmlGetFile	(	void *	vpCtx,
		const char *	cpFileName
	)

Gets the XML byte stream from a file.

This function just serves to get the file into a memory array. vXmlGetArray is then called to do the actual work.

Parameters

[in]	vpCtx	pointer to the parser's context - previously returned from vpXmlCtor.
[in]	cpFileName	- The name of the XML file.

Returns: void - an exception is thrown on any fatal error.

Definition at line 277 of file xml.c.

◆ vXmlParse()

void vXmlParse ( void * vpCtx )

Parse the XML data from vXmlGetFile or vXmlGetArray.

Parameters

[in] vpCtx pointer to the parser's context - previously returned from vpXmlCtor.

Returns: void - an exception is thrown on any fatal error.

Definition at line 500 of file xml.c.

◆ vXmlSetCommentCallback()

void vXmlSetCommentCallback	(	void *	vpCtx,
		pfnCommentCallback	pfnCallback,
		void *	vpUserData
	)

Set the user's callback function for comments.

This function is called when a comment has been found. See pfnCommentCallback for the declaration.

Parameters

[in]	vpCtx	pointer to the parser's context - previously returned from vpXmlCtor.
[in]	pfnCallback	Pointer to the callback function to use. Use `DEFAULT_CALLBACK` to invoke a pre-defined callback function which will simply display the data to `stdout`. In this case, the vpUserData argument is ignored and my be NULL.
[in]	vpUserData	This pointer will be passed through to the user's callback function. It is never dereferenced by the XML parser and may be NULL.

Returns: void - an exception is thrown on any fatal error.

Definition at line 756 of file xml.c.

◆ vXmlSetDTDCallback()

void vXmlSetDTDCallback	(	void *	vpCtx,
		pfnDTDCallback	pfnCallback,
		void *	vpUserData
	)

Set the user's callback function for the Processing Instruction tags(<?target instructions?>).

This function is called when a Processing Instruction tag has been found. See pfnDTDCallback for the declaration.

Parameters

[in]	vpCtx	pointer to the parser's context - previously returned from vpXmlCtor.
[in]	pfnCallback	Pointer to the callback function to use. Use `DEFAULT_CALLBACK` to invoke a pre-defined callback function which will simply display the data to `stdout`. In this case, the vpUserData argument is ignored and my be NULL.
[in]	vpUserData	This pointer will be passed through to the user's callback function. It is never dereferenced by the XML parser and may be NULL.

Returns: void - an exception is thrown on any fatal error.

Definition at line 731 of file xml.c.

◆ vXmlSetEmptyTagCallback()

void vXmlSetEmptyTagCallback	(	void *	vpCtx,
		pfnEmptyTagCallback	pfnCallback,
		void *	vpUserData
	)

Set the user's callback function for the empty tags (<name attr="10"/>).

This function is called when an empty tag has been found. See pfnEmptyTagCallback for the declaration.
Note that this function presents the callback function with exactly the same information that a start tag callback will get. The user may assign the same callback function to both. The option to have separate callback functions for empty and start tags is simply a convenience in case a distinction needs to be made.
Note that the utility function vStartTagDisplay will make a simple display of the empty tag name and attributes.

Parameters

[in]	vpCtx	pointer to the parser's context - previously returned from vpXmlCtor.
[in]	pfnCallback	Pointer to the callback function to use. Use `DEFAULT_CALLBACK` to invoke a pre-defined callback function which will simply display the data to `stdout`. In this case, the vpUserData argument is ignored and my be NULL.
[in]	vpUserData	This pointer will be passed through to the user's callback function. It is never dereferenced by the XML parser and may be NULL.

Returns: void - an exception is thrown on any fatal error.

Definition at line 632 of file xml.c.

◆ vXmlSetEndTagCallback()

void vXmlSetEndTagCallback	(	void *	vpCtx,
		pfnEndTagCallback	pfnCallback,
		void *	vpUserData
	)

Set the user's callback function for the end tags (</name>).

This function is called when an end tag has been found. See pfnEndTagCallback for the declaration.

Parameters

[in]	vpCtx	pointer to the parser's context - previously returned from vpXmlCtor.
[in]	pfnCallback	Pointer to the callback function to use. Use `DEFAULT_CALLBACK` to invoke a pre-defined callback function which will simply display the data to `stdout`. In this case, the vpUserData argument is ignored and my be NULL.
[in]	vpUserData	This pointer will be passed through to the user's callback function. It is never dereferenced by the XML parser and may be NULL.

Returns: void - an exception is thrown on any fatal error.

Definition at line 656 of file xml.c.

◆ vXmlSetPICallback()

void vXmlSetPICallback	(	void *	vpCtx,
		pfnPICallback	pfnCallback,
		void *	vpUserData
	)

Set the user's callback function for the Processing Instruction tags(<?target instructions?>).

This function is called when a Processing Instruction tag has been found. See pfnPICallback for the declaration.

Parameters

[in]	vpCtx	pointer to the parser's context - previously returned from vpXmlCtor.
[in]	pfnCallback	Pointer to the callback function to use. Use `DEFAULT_CALLBACK` to invoke a pre-defined callback function which will simply display the data to `stdout`. In this case, the vpUserData argument is ignored and my be NULL.
[in]	vpUserData	This pointer will be passed through to the user's callback function. It is never dereferenced by the XML parser and may be NULL.

Returns: void - an exception is thrown on any fatal error.

Definition at line 681 of file xml.c.

◆ vXmlSetStartTagCallback()

void vXmlSetStartTagCallback	(	void *	vpCtx,
		pfnStartTagCallback	pfnCallback,
		void *	vpUserData
	)

Set the user's callback function for the start tags (<name attr="10">).

This function is called when a start tag has been found. See pfnStartTagCallback for the declaration.
Note that the utility function vStartTagDisplay will make a simple display of the start tag name and attributes.

Parameters

[in]	vpCtx	pointer to the parser's context - previously returned from vpXmlCtor.
[in]	pfnCallback	Pointer to the callback function to use. Use `DEFAULT_CALLBACK` to invoke a pre-defined callback function which will simply display the data to `stdout`. In this case, the vpUserData argument is ignored and my be NULL.
[in]	vpUserData	This pointer will be passed through to the user's callback function. It is never dereferenced by the XML parser and may be NULL.

Returns: void - an exception is thrown on any fatal error.

Definition at line 600 of file xml.c.

◆ vXmlSetXmlDeclCallback()

void vXmlSetXmlDeclCallback	(	void *	vpCtx,
		pfnXmlDeclCallback	pfnCallback,
		void *	vpUserData
	)

Set the user's callback function for the XML declaration.

This function is called when parsing the XML declaration has finished. See pfnXmlDeclCallback for the declaration.

Parameters

[in]	vpCtx	pointer to the parser's context - previously returned from vpXmlCtor.
[in]	pfnCallback	Pointer to the callback function to use. Use `DEFAULT_CALLBACK` to invoke a pre-defined callback function which will simply display the data to `stdout`. In this case, the vpUserData argument is ignored and my be NULL.
[in]	vpUserData	This pointer will be passed through to the user's callback function. It is never dereferenced by the XML parser and may be NULL.

Returns: void - an exception is thrown on any fatal error.

Definition at line 706 of file xml.c.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ DEFAULT_CALLBACK

Typedef Documentation

◆ pfnCommentCallback

◆ pfnDTDCallback

◆ pfnEmptyTagCallback

◆ pfnEndTagCallback

◆ pfnPICallback

◆ pfnStartTagCallback

◆ pfnXmlDeclCallback

Function Documentation

◆ bXmlValidate()

◆ vpXmlCtor()

◆ vpXmlGetMsgs()

◆ vXmlDisplayInput()

◆ vXmlDisplayMsgs()

◆ vXmlDtor()

◆ vXmlGetArray()

◆ vXmlGetFile()

◆ vXmlParse()

◆ vXmlSetCommentCallback()

◆ vXmlSetDTDCallback()

◆ vXmlSetEmptyTagCallback()

◆ vXmlSetEndTagCallback()

◆ vXmlSetPICallback()

◆ vXmlSetStartTagCallback()

◆ vXmlSetXmlDeclCallback()