IXMLDomParser Class Reference

Class Defining the Incredible XML Dom Parser. More...

#include <IXMLParser.h>

Public Member Functions
	IXMLDomParser ()
	~IXMLDomParser ()
	Create a new Incredible XML DOM parser. More...
void	clear ()
void	setDomMemoryBlockSize (int blockSize=1024 *1024)
int	getDomMemoryBlockSize ()
	Returns the DomMemoryBlockSize parameter. More...
void	setDomMaxMemorySize (size_t maxMem=0)
int	getDomMaxMemorySize ()
	Returns the DomMaxMemorySize parameter (zero means "no limit") More...
void	setDefaultPullParserWorkspaceMemorySize (int memSize=1024 *1024)
int	getDefaultPullParserWorkspaceMemorySize ()
	return the "DefaultPullParserWorkspaceMemorySize" parameter More...
void	setSkipIgnorableSpaces (bool skipIgnorableSpaces=true)
bool	getSkipIgnorableSpaces ()
	return the skipIgnorableSpaces parameter More...
void	setTrimTexts (bool trimTexts=true)
bool	getTrimTexts ()
	return the trimTexts parameter More...
void	setTrimAttributes (bool trimAttributes=true)
bool	getTrimAttributes ()
	return the trimAttributes parameter More...
void	setRemoveClears (bool removeClears=true)
bool	getRemoveClears ()
	return the removeClears parameter More...
void	setRemoveProcessingInstructions (bool removeProcessingInstructions=true)
bool	getRemoveProcessingInstructions ()
	return the removeProcessingInstructions parameter More...
bool	getAutoDetectSourceEncoding ()
	return the autoDetectSourceEncoding parameter More...
ITCXMLNode	parseString (IXMLCStr lpIXMLString, IXMLCStr tag=NULL, IXMLResults *pResults=NULL)
	Parse an XML string and return the root of a IXMLNode tree representing the string. More...
ICXMLNode	parseStringNonT (IXMLCStr lpIXMLString, IXMLCStr tag=NULL, IXMLResults *pResults=NULL)
ITCXMLNode	parseFile (IXMLCStr filename, IXMLCStr tag=NULL, IXMLResults *pResults=NULL)
	Parse an XML file and return the root of a IXMLNode tree representing the file. More...
ICXMLNode	parseFileNonT (IXMLCStr filename, IXMLCStr tag=NULL, IXMLResults *pResults=NULL)
ITCXMLNode	openFileHelper (IXMLCStr filename, IXMLCStr tag=NULL)
	Parse an XML file and return the root of a IXMLNode tree representing the file. A very crude error checking is made. More...
ICXMLNode	openFileHelperNonT (IXMLCStr filename, IXMLCStr tag=NULL)
ITCXMLNode	parse (IPullParser *pp, IXMLCStr tag=NULL, IXMLResults *pResults=NULL)
ICXMLNode	parseNonT (IPullParser *pp, IXMLCStr tag=NULL, IXMLResults *pResults=NULL)
ITCXMLNode	parseOneChild (IPullParser *pp, IXMLResults *pResults=NULL)
ICXMLNode	parseOneChildNonT (IPullParser *pp, IXMLResults *pResults=NULL)
void	setAutoDetectSourceEncoding (bool autoDetectSource=false)
void	setCharEncoding (IXMLPullParser::IXMLCharEncoding sourceEncoding=IXMLPullParser::char_encoding_UTF8, IXMLPullParser::IXMLCharEncoding destinationEncoding=IXMLPullParser::char_encoding_UTF8)

Static Public Member Functions
static IXMLCStr	getErrorMessage (IXMLError error)
	this gives you a user-friendly explanation of the parsing error More...

Detailed Description

Class Defining the Incredible XML Dom Parser.

Definition at line 721 of file IXMLParser.h.

Constructor & Destructor Documentation

IXMLDomParser::IXMLDomParser

(

)

IXMLDomParser::~IXMLDomParser

(

)

Create a new Incredible XML DOM parser.

Member Function Documentation

void IXMLDomParser::clear

(

)

Call this function when you have finished using this object to release memory used by the internal buffers. WARNING: After calling the "clear()" function, all the UTCXMLNodes produced by this object are becoming invalid: You cannot access them anymore (the same thing happens when you delete the IXMLDomParser object). If you still need to access the content of some UTCXMLNodes after calling the "clear()" function, you need to convert them in UCXMLNodes or IXMLNodes (using the "deepCopyConstant()" or deepCopy()" functions).

Referenced by example2().

bool IXMLDomParser::getAutoDetectSourceEncoding

(

)

return the autoDetectSourceEncoding parameter

int IXMLDomParser::getDefaultPullParserWorkspaceMemorySize

(

)

return the "DefaultPullParserWorkspaceMemorySize" parameter

int IXMLDomParser::getDomMaxMemorySize

(

)

Returns the DomMaxMemorySize parameter (zero means "no limit")

int IXMLDomParser::getDomMemoryBlockSize

(

)

Returns the DomMemoryBlockSize parameter.

static IXMLCStr IXMLDomParser::getErrorMessage ( IXMLError  error )

static

this gives you a user-friendly explanation of the parsing error

bool IXMLDomParser::getRemoveClears

(

)

return the removeClears parameter

bool IXMLDomParser::getRemoveProcessingInstructions

(

)

return the removeProcessingInstructions parameter

bool IXMLDomParser::getSkipIgnorableSpaces

(

)

return the skipIgnorableSpaces parameter

bool IXMLDomParser::getTrimAttributes

(

)

return the trimAttributes parameter

bool IXMLDomParser::getTrimTexts

(

)

return the trimTexts parameter

ITCXMLNode IXMLDomParser::openFileHelper	(	IXMLCStr	filename,
		IXMLCStr	tag = NULL
	)

Parse an XML file and return the root of a IXMLNode tree representing the file. A very crude error checking is made.

Referenced by example1(), and example2().

ICXMLNode IXMLDomParser::openFileHelperNonT	(	IXMLCStr	filename,
		IXMLCStr	tag = NULL
	)

The "openFileHelper" function reports to the screen all the warnings and errors that occurred during parsing of the XML file. Since each application has its own way to report and deal with errors, you should rather use the "parseFile" function to parse XML files and program yourself thereafter an "error reporting" tailored for your needs (instead of using the very crude "error reporting" mechanism included inside the "openFileHelper" function).

If the XML document is corrupted, the "openFileHelper" method will:

• display an error message on the console (or inside a messageBox for windows).
• stop execution (exit).

I strongly suggest that you write your own "openFileHelper" method tailored to your needs. If you still want to parse the file, you can use the APPROXIMATE_PARSING option as explained inside the note at the beginning of the "IXMLParser.cpp" file.

Parameters

filename	the path of the XML file to parse.
tag	the name of the first tag inside the XML file. If the tag parameter is omitted, this function returns a node that represents the head of the xml document including the declaration term (<? ... ?>).

ITCXMLNode IXMLDomParser::parse	(	IPullParser *	pp,
		IXMLCStr	tag = NULL,
		IXMLResults *	pResults = NULL
	)

Referenced by example12().

ITCXMLNode IXMLDomParser::parseFile	(	IXMLCStr	filename,
		IXMLCStr	tag = NULL,
		IXMLResults *	pResults = NULL
	)

Parse an XML file and return the root of a IXMLNode tree representing the file.

ICXMLNode IXMLDomParser::parseFileNonT	(	IXMLCStr	filename,
		IXMLCStr	tag = NULL,
		IXMLResults *	pResults = NULL
	)

The "parseFile" function parse an XML file and return the root of a ITCXMLNode tree. The "opposite" of this function is the function "IXMLRenderer::writeToFile()" that re-creates an XML file from an IXMLNode tree. If the XML document is corrupted, the "parseFile" method will initialize the "pResults" variable with some information that can be used to trace the error. If you still want to parse the file, you can use the APPROXIMATE_PARSING option as explained inside the note at the beginning of the "IXMLParser.cpp" file.

Parameters

filename	the path to the XML file to parse
tag	the name of the first tag inside the XML file. If the tag parameter is omitted, this function returns a node that represents the head of the xml document including the declaration term (<? ... ?>).
pResults	a pointer to a XMLResults variable that will contain some information that can be used to trace the XML parsing error. You can have a user-friendly explanation of the parsing error with the "getError" function.

Referenced by example9().

ICXMLNode IXMLDomParser::parseNonT	(	IPullParser *	pp,
		IXMLCStr	tag = NULL,
		IXMLResults *	pResults = NULL
	)

The "parse" function read ALL the tokens produced by the Incredible XML Pull Parser and return the root of the corresponding ITCXMLNode tree. If the XML document is corrupted, the "parse" method will initialize the "pResults" variable with some information that can be used to trace the error. If you still want to parse the file, you can use the APPROXIMATE_PARSING option as explained inside the note at the beginning of the "IXMLParser.cpp" file.

Parameters

pp	a pointer to the IXMLPullParser that is used to produce the ITCXMLNode tree.
tag	the name of the first tag inside the XML file. If the tag parameter is omitted, this function returns a node that represents the head of the xml document including the declaration term (<? ... ?>).
pResults	a pointer to a XMLResults variable that will contain some information that can be used to trace the XML parsing error. You can have a user-friendly explanation of the parsing error with the "getError" function.

ITCXMLNode IXMLDomParser::parseOneChild	(	IPullParser *	pp,
		IXMLResults *	pResults = NULL
	)

Referenced by example7().

ICXMLNode IXMLDomParser::parseOneChildNonT	(	IPullParser *	pp,
		IXMLResults *	pResults = NULL
	)

The "parseOneChild" function does NOT read ALL the tokens produced by the Incredible XML Pull Parser. It stops as soon as it obtained a complete ChildNode xNode (see example 7). It then returns the xNode ChildNode. If the XML document is corrupted, the "parseOneChild" method will initialize the "pResults" variable with some information that can be used to trace the error. If you still want to parse the file, you can use the APPROXIMATE_PARSING option as explained inside the note at the beginning of the "IXMLParser.cpp" file. This function is typically used when using the "hot start" functionality of the Incredible XML Parser, to be able process unlimited file size while, at the same time, using very little RAM memory.

Parameters

pp	a pointer to the IXMLPullParser that is used to produce the xNode ChildNode.
pResults	a pointer to a XMLResults variable that will contain some information that can be used to trace the XML parsing error. You can have a user-friendly explanation of the parsing error with the "getError" function.

ITCXMLNode IXMLDomParser::parseString	(	IXMLCStr	lpIXMLString,
		IXMLCStr	tag = NULL,
		IXMLResults *	pResults = NULL
	)

Parse an XML string and return the root of a IXMLNode tree representing the string.

Referenced by example10(), example5(), and example6().

ICXMLNode IXMLDomParser::parseStringNonT	(	IXMLCStr	lpIXMLString,
		IXMLCStr	tag = NULL,
		IXMLResults *	pResults = NULL
	)

The "parseString" function parse an XML string and return the root of a IXMLNode tree. The "opposite" of this function is the function "IXMLRenderer::GetString()" that re-creates an XML string from an IXMLNode tree. If the XML document is corrupted, the "parseString" method will initialize the "pResults" variable with some information that can be used to trace the error. If you still want to parse the file, you can use the APPROXIMATE_PARSING option as explained inside the note at the beginning of the "IXMLParser.cpp" file.

Parameters

lpIXMLString	the XML string to parse
tag	the name of the first tag inside the XML file. If the tag parameter is omitted, this function returns a node that represents the head of the xml document including the declaration term (<? ... ?>).
pResults	a pointer to a XMLResults variable that will contain some information that can be used to trace the XML parsing error. You can have a user-friendly explanation of the parsing error with the "getError" function.

Referenced by example4().

void IXMLDomParser::setAutoDetectSourceEncoding

(

bool

autoDetectSource = false

)

The parseString, parseFile and openFileHelper are creating internally a new temporary Pull Parser that is used to perform the required parsing. The IXMLDomParser::AutoDetectSourceEncoding parameter is used to initialize the IXMLPullParser::AutoDetectSourceEncoding parameter of the Pull Parser.

void IXMLDomParser::setCharEncoding	(	IXMLPullParser::IXMLCharEncoding	sourceEncoding = IXMLPullParser::char_encoding_UTF8,
		IXMLPullParser::IXMLCharEncoding	destinationEncoding = IXMLPullParser::char_encoding_UTF8
	)

The parseString, parseFile and openFileHelper are creating internally a new temporary Pull Parser that is used to perform the required parsing. The IXMLDomParser::sourceCharEncoding and IXMLDomParser::destinationEncoding parameters are used to initialize the IXMLPullParser::sourceCharEncoding and the IXMLPullParser::destinationEncoding parameters of the Pull Parser.

void IXMLDomParser::setDefaultPullParserWorkspaceMemorySize

(

int

memSize = 1024 *1024

)

The IXMLDomParser::parseString(), IXMLDomParser::parseFile() and IXMLDomParser::openFileHelper() are creating internally a new temporary Pull Parser that is used to perform the required parsing. The size of the internal memory buffer of the internal Pull Parser is defined here using the "DefaultPullParserWorkspaceMemorySize" parameter.

void IXMLDomParser::setDomMaxMemorySize

(

size_t

maxMem = 0

)

The DomMaxMemorySize parameter defines an upper bound on the memory consumption of the DOM Parser. By default, there are no limit. When the memory limit is reached, the parse* functions return an empty ITCXMLNode and the errorCode is IXMLError_MaxMemoryReached.

void IXMLDomParser::setDomMemoryBlockSize

(

int

blockSize = 1024 *1024

)

To reduce the number of memory allocation calls performed during parsing, the Incredible XML DOM Parser allocate "big" blocks of memory. Each block store many ITCXMLNode objects. When all the blocks are "full", then a new memory allocation call is performed to ask for one new "big" block. A small value for the blockSize will force the parser to make many memory allocation calls and might slow-down the DOM Parser significantly. The IXMLDomParser class re-uses the memory allocated during the previous parsing. Thus, most of the time, the parsing is performed without any memory allocation at all.

void IXMLDomParser::setRemoveClears

(

bool

removeClears = true

)

For efficiency reason, it's better to set "removeClears=true" because the DOM Parser can then skip any Clear tags (it allows to reduce the computation time and the memory requirements). If you still need to get access to Clear tags inside the XMLNode tree, set "removeClears=false".

Referenced by example1(), and example7().

void IXMLDomParser::setRemoveProcessingInstructions

(

bool

removeProcessingInstructions = true

)

For efficiency reason, it's better to set "removeProcessingInstructions=true" because the DOM Parser can then skip any processing instructions (It allows to reduce the computation time and the memory requirements). If you still need to get access to processing instruction inside the XMLNode tree, set "removeProcessingInstructions=false".

void IXMLDomParser::setSkipIgnorableSpaces

(

bool

skipIgnorableSpaces = true

)

In most situations, text fields containing only white spaces (and carriage returns) are useless. Even more, these "empty" text fields are annoying because they increase the complexity of the user's code for parsing. So, 99% of the time, it's better to drop the "empty" text fields. However The XML specification indicates that no white spaces should be lost when parsing the file. So to be perfectly XML-compliant, you should set skipIgnorableSpaces=false. A note of caution: if you set "skipIgnorableSpaces=false", the parser will be slower and your code will be more complex.

void IXMLDomParser::setTrimAttributes

(

bool

trimAttributes = true

)

It's very common to be forced to remove the white spaces (and the carriage returns) located at the start and at the end of all the attribute values. But, to be perfectly XML-compliant, you should set "trimAttributes=false". A note of caution: if you set "trimAttributes=false", the parser will be slower and your code will most likely be more complex.

void IXMLDomParser::setTrimTexts

(

bool

trimTexts = true

)

It's very common to be forced to remove the white spaces (and the carriage returns) located at the start and at the end of all text fields.But, to be perfectly XML-compliant, you should set "trimTexts=false". A note of caution: if you set "trimTexts=false", the parser will be slower and your code will most likely be more complex.

---

The documentation for this class was generated from the following file:

• IXMLParser.h