The APG XML parser. More...

#include "xml.h"
#include "xmlgrammar.h"
#include "xmlp.h"

Include dependency graph for xml.c:

Data Structures
struct	input_info
	Information about the input data. More...

Macros
Misc. Constants
Some misc. constants used by the parser.
#define	TAB 9

#define	LF 10

#define	CR 13

#define	LINE_LEN 16

#define	LINE_LEN4 4

#define	LINE_LEN8 8

#define	LINE_LEN12 12

#define	LT 0x3C

#define	CHARS_LINE_LEN 8

#define	CHAR_BUF_LEN 256

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	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...

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

void	vXmlSetEmptyTagCallback (void vpCtx, pfnEmptyTagCallback pfnCallback, void vpUserData)
	Set the user's callback function for the empty 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	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	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...

Detailed Description

The APG XML parser.

This is meant to be a standards-compliant, non-validating XML parser. XML input may be UTF-8, UTF-16BE or UTF-16LE. If UTF-16, a Byte Order Mark (BOM) must be present and UTF-16 must be specified in the XML declaration which must be present. UTF-16 format is transcoded to UTF-8 prior to parsing. All line ends are converted to 0x0A (\n or LF) and all characters are checked for XML character validity.

The Document Type Declaration (DTD) internal subset, if present, is parsed and entity declarations and default attribute values are tabulated and used when parsing the document body.

All applicable well-formedness constraints are checked.

1.) Well-formedness constraint: PEs in Internal Subset
In the internal DTD subset, parameter-entity references MUST NOT occur within markup declarations; they may occur where markup declarations can occur. (This does not apply to references that occur in external parameter entities or to the external subset.)
2.) Well-formedness constraint: External Subset
The external subset, if any, MUST match the production for extSubset.
(Not Applicable - External subset not parsed.)
3.) Well-formedness constraint: PE Between Declarations
The replacement text of a parameter entity reference in a DeclSep MUST match the production extSubsetDecl.
(Not Applicable - Parameter Entities not read.)
4.) Well-formedness constraint: Element Type Match
The Name in an element's end-tag MUST match the element type in the start-tag.
5.0 Well-formedness constraint: Unique Att Spec
An attribute name MUST NOT appear more than once in the same start-tag or empty-element tag.
6.) Well-formedness constraint: No External Entity References
Attribute values MUST NOT contain direct or indirect entity references to external entities.
(Not Applicable - No external entities are read.)
7.) Well-formedness constraint: No < in Attribute Values
The replacement text of any entity referred to directly or indirectly in an attribute value MUST NOT contain a <.
8.) Well-formedness constraint: Legal Character
Characters referred to using character references MUST match the production for Char.
9.) Well-formedness constraint: Entity Declared
In a document without any DTD, a document with only an internal DTD subset which contains no parameter entity references, or a document with " standalone='yes' ", for an entity reference that does not occur within the external subset or a parameter entity, the Name given in the entity reference MUST match that in an entity declaration that does not occur within the external subset or a parameter entity, except that well-formed documents need not declare any of the following entities: amp, lt, gt, apos, quot. The declaration of a general entity MUST precede any reference to it which appears in a default value in an attribute-list declaration.
10.) Well-formedness constraint: Parsed Entity
An entity reference MUST NOT contain the name of an unparsed entity. Unparsed entities may be referred to only in attribute values declared to be of type ENTITY or ENTITIES.
(Not Applicable - No unparsed entities are read.)
11.) Well-formedness constraint: No Recursion
A parsed entity MUST NOT contain a recursive reference to itself, either directly or indirectly.
12.) Well-formedness constraint: In DTD
Parameter-entity references MUST NOT appear outside the DTD.
(The ABNF grammar prevents this.)

Definition in file xml.c.

Macro Definition Documentation

◆ CHAR_BUF_LEN

#define CHAR_BUF_LEN 256

Definition at line 106 of file xml.c.

◆ CHARS_LINE_LEN

#define CHARS_LINE_LEN 8

Definition at line 105 of file xml.c.

◆ CR

#define CR 13

Definition at line 99 of file xml.c.

◆ LF

#define LF 10

Definition at line 98 of file xml.c.

◆ LINE_LEN

#define LINE_LEN 16

Definition at line 100 of file xml.c.

◆ LINE_LEN12

#define LINE_LEN12 12

Definition at line 103 of file xml.c.

◆ LINE_LEN4

#define LINE_LEN4 4

Definition at line 101 of file xml.c.

◆ LINE_LEN8

#define LINE_LEN8 8

Definition at line 102 of file xml.c.

◆ LT

#define LT 0x3C

Definition at line 104 of file xml.c.

◆ TAB

#define TAB 9

Definition at line 97 of file xml.c.

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

Functions

Detailed Description

Macro Definition Documentation

◆ CHAR_BUF_LEN

◆ CHARS_LINE_LEN

◆ CR

◆ LF

◆ LINE_LEN

◆ LINE_LEN12

◆ LINE_LEN4

◆ LINE_LEN8

◆ LT

◆ TAB

Function Documentation

◆ bXmlValidate()

◆ vpXmlCtor()

◆ vpXmlGetMsgs()

◆ vXmlDisplayInput()

◆ vXmlDisplayMsgs()

◆ vXmlDtor()

◆ vXmlGetArray()

◆ vXmlGetFile()

◆ vXmlParse()

◆ vXmlSetCommentCallback()

◆ vXmlSetDTDCallback()

◆ vXmlSetEmptyTagCallback()

◆ vXmlSetEndTagCallback()

◆ vXmlSetPICallback()

◆ vXmlSetStartTagCallback()

◆ vXmlSetXmlDeclCallback()