Version 7.0
Copyright © 2021 Lowell D. Thomas
APG
… an ABNF Parser Generator
Data Structures | Macros | Typedefs | Functions
xml.h File Reference

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:

Go to the source code of 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
spCommentThe comment characters.
vpUserDataThe 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
spInfoThe DTD information
vpUserDataThe 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
spNameThe attribute name.
spAttNamesAn array of the attribute names.
spAttValuesAn array of the attribute values.
uiAttCountThe number of attributes in the array.
vpUserDataThe 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
spNameThe element name.
spContentThe element character data.
vpUserDataThe 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
spTargetThe Processing Instruction's target or name.
spInfoThe Processing Instruction's instructions or information.
vpUserDataThe 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
spNameThe attribute name.
spAttNamesAn array of the attribute names.
spAttValuesAn array of the attribute values.
uiAttCountThe number of attributes in the array.
vpUserDataThe 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
spInfoThe XML declaration information
vpUserDataThe 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]vpCtxpointer 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
spExPointer 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]vpCtxpointer 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]vpCtxpointer 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]vpCtxpointer 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]vpCtxpointer 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]vpCtxpointer 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]vpCtxpointer 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]vpCtxpointer 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]vpCtxpointer to the parser's context - previously returned from vpXmlCtor.
[in]pfnCallbackPointer 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]vpUserDataThis 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]vpCtxpointer to the parser's context - previously returned from vpXmlCtor.
[in]pfnCallbackPointer 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]vpUserDataThis 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]vpCtxpointer to the parser's context - previously returned from vpXmlCtor.
[in]pfnCallbackPointer 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]vpUserDataThis 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]vpCtxpointer to the parser's context - previously returned from vpXmlCtor.
[in]pfnCallbackPointer 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]vpUserDataThis 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]vpCtxpointer to the parser's context - previously returned from vpXmlCtor.
[in]pfnCallbackPointer 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]vpUserDataThis 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]vpCtxpointer to the parser's context - previously returned from vpXmlCtor.
[in]pfnCallbackPointer 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]vpUserDataThis 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]vpCtxpointer to the parser's context - previously returned from vpXmlCtor.
[in]pfnCallbackPointer 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]vpUserDataThis 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.

APG Version 7.0 is licensed under the 2-Clause BSD License,
an Open Source Initiative Approved License.