XML

Detailed Description

v1.10 (23 April 2023)
The XML module includes the XML Manager and XML objects providing a full XML parsing system.

Each object loaded(a XML file) or created (a XML created on the fly) owns an internal state containing very important variables as the current node pointer and others.
In case you access to the same object from different functions or threads, you must keep in mind this internal state or unexpected results may happen. A workaround for it is to load an object, change its name and load the same object, this will allow you to have read-only concurrency from two different threads to the same but duplicated object.

This is a standard manager: objects are not shared and must be unique using its name as the key, in other words, you can not create an object with the same name of another one already created.

Only a single instance of the XML Manager exists which is created once Main is instantiated.
You can get a reference to this manager using Main::IXMLMgr() method.

Note

The XML Manager is automatically released when Main::Terminate() is called.
At this time, any resource still loaded, will be released avoding resource leaks.

Classes
class	CRM64Pro::XML
	XML Object class. More...
class	CRM64Pro::XMLMgr
	XML Manager class. More...

Functions
Sint32	CRM64Pro::XML::info (Sint32 iMode=0)
	Request XML object information.
Sint32	CRM64Pro::XML::getName (string &sName)
	Get the name.
Uint32	CRM64Pro::XML::getID ()
	Get the ID.
Sint32	CRM64Pro::XML::nodePointTo (Sint32 iParam, char *szNodes,...)
	Search and point to the given node or subnode at any level.
Sint32	CRM64Pro::XML::nodeFirst ()
	Point to the first XML node (the root node).
Sint32	CRM64Pro::XML::nodeNext ()
	Point to the next node (from current pointed node).
Sint32	CRM64Pro::XML::nodePrev ()
	Point to the previous node (from current pointed node).
Sint32	CRM64Pro::XML::nodeParent ()
	Point to the parent node (from current pointed node).
Sint32	CRM64Pro::XML::nodeChild ()
	Point to the first child node (from current pointed node).
Sint32	CRM64Pro::XML::nodeStore ()
	Store node pointer position.
Sint32	CRM64Pro::XML::nodeRestore ()
	Restore node pointer position.
Sint32	CRM64Pro::XML::nodeRemove ()
	Remove pointed node and all its subnodes and attributes.
Sint32	CRM64Pro::XML::nodeCreate (const string &sNode)
	Create a new node inside the pointed node and point to it.
Sint32	CRM64Pro::XML::nodeRename (const string &sNode)
	Rename pointed node.
Sint32	CRM64Pro::XML::nodeGetName (string &sNode)
	Get the name of pointed node.
Sint32	CRM64Pro::XML::setAttribute (const string &sAttr, const string &sValue)
	Set an attribute inside pointed node with a string value.
Sint32	CRM64Pro::XML::setAttribute (const string &sAttr, const Sint32 &iValue)
	Set an attribute inside pointed node with an integer value.
Sint32	CRM64Pro::XML::setAttribute (const string &sAttr, const double &dValue)
	Set an attribute inside pointed node with an integer value.
Sint32	CRM64Pro::XML::getAttribute (const string &sAttr, string &sValue)
	Get the string value of an attribute inside the pointed node.
Sint32	CRM64Pro::XML::getAttribute (const string &sAttr, Sint32 &iValue)
	Get the integer value of an attribute inside the pointed node.
Sint32	CRM64Pro::XML::getAttribute (const string &sAttr, double &dValue)
	Get the double value of an attribute inside the pointed node.
Sint32	CRM64Pro::XML::removeAttribute (const string &sAttr)
	Remove an attribute and its value inside the pointed node.
Sint32	CRM64Pro::XML::setText (const string &sText)
	Set a text inside the pointed node.
Sint32	CRM64Pro::XML::getText (string &sText)
	Get the text contained in the pointed node.
Sint32	CRM64Pro::XML::removeText ()
	Remove the text inside the pointed node.
Sint32	CRM64Pro::XML::setComment (const string &sComment)
	Set a comment text inside the pointed node.
Sint32	CRM64Pro::XML::getComment (string &sComment)
	Get the comment text contained in the pointed node.
Sint32	CRM64Pro::XML::removeComment ()
	Remove the comment text inside the pointed node.
Sint32	CRM64Pro::XML::saveToFile (const string &sFile)
	Export the XML to an external file.
Sint32	CRM64Pro::XML::save (const string &sFileCDC)
	Save the XML in to a CDC file.
Sint32	CRM64Pro::XML::save (Sint32 idCDC)
	Save the XML in to a CDC file.
Sint32	CRM64Pro::XMLMgr::info (Sint32 idXML=0)
	Request XML Manager information.
Sint32	CRM64Pro::XMLMgr::create (const string &sMainNode, Uint32 iUnused=0)
	Create a new XML.
Sint32	CRM64Pro::XMLMgr::close (Sint32 idXML)
	Close and destroy a XML.
Sint32	CRM64Pro::XMLMgr::getNum ()
	Get number of loaded objects.
Sint32	CRM64Pro::XMLMgr::setName (Sint32 idXML, const string &sName)
	Change the object name.
XML *	CRM64Pro::XMLMgr::get (Sint32 idXML=0)
	Get a pointer to the XML using its handler.
Sint32	CRM64Pro::XMLMgr::loadFromFile (const string &sFile, const string &sName="")
	Load a XML file.
Sint32	CRM64Pro::XMLMgr::loadFromBuffer (const unsigned char *szData, const Sint32 iSize, const string &sName)
	Load a XML from a buffer.
Sint32	CRM64Pro::XMLMgr::load (const string &sFileCDC, const string &sName)
	Load a XML file stored in a CDC file.
Sint32	CRM64Pro::XMLMgr::load (Sint32 idCDC, const string &sName)
	Load a XML file stored in a CDC file.
Sint32	CRM64Pro::XMLMgr::remove (Sint32 idCDC, const string &sName)
	Remove a XML file stored in a CDC file.

Function Documentation

info() [1/2]

Sint32 CRM64Pro::XML::info

(

Sint32

iMode = 0

)

Request XML object information.

For displaying the information, it uses the default log.

Parameters

iMode

unused for the time being.

Returns

0 on success or a negative error code on failure.

getName()

Sint32 CRM64Pro::XML::getName

(

string &

sName

)

Get the name.

Parameters

sName

a string containing the XML object name.

Returns

0 on success or a negative error code on failure.

getID()

Uint32 CRM64Pro::XML::getID

(

)

Get the ID.

Returns

the object ID.

nodePointTo()

Sint32 CRM64Pro::XML::nodePointTo	(	Sint32	iParam,
		char *	szNodes,
			...
	)

Search and point to the given node or subnode at any level.

It only changes the pointer when all node+[subnodes] are valid.

Parameters

iParam	number node+[subnodes] in 'szNodes'.
szNodes	string zero pointer with the node+[subnodes].

Returns

0 on success or a negative error code on failure.

nodeFirst()

Sint32 CRM64Pro::XML::nodeFirst

(

)

Point to the first XML node (the root node).

It only changes the pointer when it finds a valid node.

Returns

0 on success or a negative error code on failure.

nodeNext()

Sint32 CRM64Pro::XML::nodeNext

(

)

Point to the next node (from current pointed node).

It only changes the pointer when it finds a valid node.

Returns

0 on success or a negative error code on failure.

nodePrev()

Sint32 CRM64Pro::XML::nodePrev

(

)

Point to the previous node (from current pointed node).

It only changes the pointer when it finds a valid node.

Returns

0 on success or a negative error code on failure.

nodeParent()

Sint32 CRM64Pro::XML::nodeParent

(

)

Point to the parent node (from current pointed node).

It only changes the pointer when it finds a valid node.

Returns

0 on success or a negative error code on failure.

nodeChild()

Sint32 CRM64Pro::XML::nodeChild

(

)

Point to the first child node (from current pointed node).

It only changes the pointer when it finds a valid node.

Returns

0 on success or a negative error code on failure.

nodeStore()

Sint32 CRM64Pro::XML::nodeStore

(

)

Store node pointer position.

There is only one slot per each XML so it only keeps the position of the last time this method is called.

Returns

0 on success or a negative error code on failure.

nodeRestore()

Sint32 CRM64Pro::XML::nodeRestore

(

)

Restore node pointer position.

There is only one slot per each XML so it restores the position of the last time nodeStore() method was called.

Returns

0 on success or a negative error code on failure.

nodeRemove()

Sint32 CRM64Pro::XML::nodeRemove

(

)

Remove pointed node and all its subnodes and attributes.

Returns

0 on success or a negative error code on failure.

nodeCreate()

Sint32 CRM64Pro::XML::nodeCreate

(

const string &

sNode

)

Create a new node inside the pointed node and point to it.

Parameters

sNode

string containing the node name.

Returns

0 on success or a negative error code on failure.

nodeRename()

Sint32 CRM64Pro::XML::nodeRename

(

const string &

sNode

)

Rename pointed node.

Parameters

sNode

string containing the node name.

Returns

0 on success or a negative error code on failure.

nodeGetName()

Sint32 CRM64Pro::XML::nodeGetName

(

string &

sNode

)

Get the name of pointed node.

Parameters

sNode

a string variable. Will not be modified when there is not a valid pointed node.

Returns

0 on success or a negative error code on failure.

string with the node name or an empty string on failure.

setAttribute() [1/3]

Sint32 CRM64Pro::XML::setAttribute	(	const string &	sAttr,
		const string &	sValue
	)

Set an attribute inside pointed node with a string value.

If the attribute does not exist, it will be created.

Parameters

sAttr	attribute name string.
sValue	string value.

Returns

0 on success or a negative error code on failure.

setAttribute() [2/3]

Sint32 CRM64Pro::XML::setAttribute	(	const string &	sAttr,
		const Sint32 &	iValue
	)

Set an attribute inside pointed node with an integer value.

If the attribute does not exist, it will be created.

Parameters

sAttr	attribute name string.
iValue	integer value.

Returns

0 on success or a negative error code on failure.

setAttribute() [3/3]

Sint32 CRM64Pro::XML::setAttribute	(	const string &	sAttr,
		const double &	dValue
	)

Set an attribute inside pointed node with an integer value.

If the attribute does not exist, it will be created.

Parameters

sAttr	attribute name string.
dValue	integer value.

Returns

0 on success or a negative error code on failure.

getAttribute() [1/3]

Sint32 CRM64Pro::XML::getAttribute	(	const string &	sAttr,
		string &	sValue
	)

Get the string value of an attribute inside the pointed node.

Parameters

sAttr	attribute name string.
sValue	a string variable. Will not be modified when the attribute does not exist.

Returns

0 on success or a negative error code on failure.

getAttribute() [2/3]

Sint32 CRM64Pro::XML::getAttribute	(	const string &	sAttr,
		Sint32 &	iValue
	)

Get the integer value of an attribute inside the pointed node.

Parameters

sAttr	attribute name string.
iValue	an integer variable. Will not be modified when the attribute does not exist.

Returns

0 on success or a negative error code on failure.

getAttribute() [3/3]

Sint32 CRM64Pro::XML::getAttribute	(	const string &	sAttr,
		double &	dValue
	)

Get the double value of an attribute inside the pointed node.

Parameters

sAttr	attribute name string.
dValue	a double variable. Will not be modified when the attribute does not exist.

Returns

0 on success or a negative error code on failure.

removeAttribute()

Sint32 CRM64Pro::XML::removeAttribute

(

const string &

sAttr

)

Remove an attribute and its value inside the pointed node.

Parameters

sAttr

attribute name string.

Returns

0 on success or a negative error code on failure.

setText()

Sint32 CRM64Pro::XML::setText

(

const string &

sText

)

Set a text inside the pointed node.

If there is not any text, it will be created. Otherwise, the text will be appended to the exiting one.

Parameters

sText

text string.

Returns

0 on success or a negative error code on failure.>

getText()

Sint32 CRM64Pro::XML::getText

(

string &

sText

)

Get the text contained in the pointed node.

Parameters

sText

a string variable. Will not be modified when the text does not exist.

Returns

0 on success or a negative error code on failure.

removeText()

Sint32 CRM64Pro::XML::removeText

(

)

Remove the text inside the pointed node.

Returns

string with the pointed node text or an empty string on failure.

setComment()

Sint32 CRM64Pro::XML::setComment

(

const string &

sComment

)

Set a comment text inside the pointed node.

If a comment already exists, it will be pushed down and the new comment will be the first one.

Parameters

sComment

comment text string.

Returns

0 on success or a negative error code on failure.

getComment()

Sint32 CRM64Pro::XML::getComment

(

string &

sComment

)

Get the comment text contained in the pointed node.

Parameters

sComment

a string variable. Will not be modified when the comment does not exist.

Returns

0 on success or a negative error code on failure.

Note

It only gets the first comment text block found.

removeComment()

Sint32 CRM64Pro::XML::removeComment

(

)

Remove the comment text inside the pointed node.

Returns

0 on success or a negative error code on failure.

Note

It only removes the first comment text block found.
In case you want to remove all comments in the pointed node, call this method till you got a negative error code.

saveToFile()

Sint32 CRM64Pro::XML::saveToFile

(

const string &

sFile

)

Export the XML to an external file.

Parameters

sFile

string containing the [directory]+filename+[extension]. Ideally, it should have the .xml extension. If the XML file already exists, it will be overwritten. Directory separators '\' and '/' are supported.

Returns

0 or greater on success or a negative error code on failure.

save() [1/2]

Sint32 CRM64Pro::XML::save

(

const string &

sFileCDC

)

Save the XML in to a CDC file.

If the XML already exists on the CDC, it will be overwritten.

Parameters

sFileCDC

string containing the [directory]+filename+[extension]. Directory separators '\' and '/' are supported.

Returns

greater than 0 on success(the size of this block on the CDC) or a negative error code on failure.

Note

If the CDC file is secured, this call will fail. For these cases, open first the CDC using ArchiveMgr::open() and use XML::save() with the CDC id.

save() [2/2]

Sint32 CRM64Pro::XML::save

(

Sint32

idCDC

)

Save the XML in to a CDC file.

If the XML already exists on the CDC, it will be overwritten.

Parameters

idCDC

CDC id.

Returns

greater than 0 on success(the size of this block on the CDC) or a negative error code on failure.

info() [2/2]

Sint32 CRM64Pro::XMLMgr::info

(

Sint32

iMode = 0

)

Request XML Manager information.

For displaying the information, it uses the default log.

Parameters

iMode

-1 for displaying only Manager information. 0 for displaying Manager and all Objects information. This is the default value. idXML for displaying Manager and given XML id information.

Returns

0 on success or a negative error code on failure.

create()

Sint32 CRM64Pro::XMLMgr::create	(	const string &	sMainNode,
		Uint32	iUnused = 0
	)

Create a new XML.

Parameters

sMainNode	The name to give to the the main node (e.g. 'myRootNode'). It is also used to set the XML object name. The object name must be unique and with a maximum size of 64 characters or will be truncated.
iUnused	unused for the time being.

Returns

greater than 0 on success(the XML id) or a negative error code on failure.

close()

Sint32 CRM64Pro::XMLMgr::close

(

Sint32

idXML

)

Close and destroy a XML.

Parameters

idXML

0 for closing all XML files or the XML id.

Returns

0 on success or a negative error code on failure.

Note

If you forget to close a XML, it will be automatically closed once the GDK is terminated.

getNum()

Sint32 CRM64Pro::XMLMgr::getNum

(

)

Get number of loaded objects.

Returns

the number of XML objects.

setName()

Sint32 CRM64Pro::XMLMgr::setName	(	Sint32	idXML,
		const string &	sName
	)

Change the object name.

Parameters

idXML	XML id.
sName	The name to give to the XML object (e.g. 'myXML'). The object name must be unique and with a maximum size of 64 characters or will be truncated.

Returns

0 on success or a negative error code on failure.

get()

XML * CRM64Pro::XMLMgr::get

(

Sint32

idXML = 0

)

Get a pointer to the XML using its handler.

Parameters

idXML

XML id. By default it returns the first XML.

Returns

nullptr the XML was not found.

A pointer to the XML object.

loadFromFile()

Sint32 CRM64Pro::XMLMgr::loadFromFile	(	const string &	sFile,
		const string &	sName = ""
	)

Load a XML file.

Parameters

sFile	string containing the [directory]+filename+[extension]. Directory separators '\' and '/' are supported.
sName	the XML object name. By default, it is set to empty to use the filename (without extension) for setting the XML object name. The object name must be unique and with a maximum size of 64 characters or will be truncated.

Returns

greater than 0 on success(the XML id) or a negative error code on failure.

loadFromBuffer()

Sint32 CRM64Pro::XMLMgr::loadFromBuffer	(	const unsigned char *	szData,
		const Sint32	iSize,
		const string &	sName
	)

Load a XML from a buffer.

Parameters

szData	pointer to buffer data that contains the XML to be loaded.
iSize	size in bytes of the buffer data.
sName	the XML object name. By default, it is set to empty to use the filename (without extension) for setting the XML object name. The object name must be unique and with a maximum size of 64 characters or will be truncated.

Returns

greater than 0 on success(the XML id) or a negative error code on failure.

load() [1/2]

Sint32 CRM64Pro::XMLMgr::load	(	const string &	sFileCDC,
		const string &	sName
	)

Load a XML file stored in a CDC file.

Parameters

sFileCDC	string containing the [directory]+filename+[extension]. Directory separators '\' and '/' are supported.
sName	string containing the XML object name. The object name must be unique and with a maximum size of 64 characters or will be truncated.

Returns

greater than 0 on success(the XML id) or a negative error code on failure.

Note

If the CDC file is secured, this call will fail.
For these cases, open first the CDC using ArchiveMgr::open() and use XMLMgr::open() with the CDC id.

load() [2/2]

Sint32 CRM64Pro::XMLMgr::load	(	Sint32	idCDC,
		const string &	sName
	)

Load a XML file stored in a CDC file.

Parameters

idCDC	CDC id
sName	string containing the XML object name. The object name must be unique and with a maximum size of 64 characters or will be truncated.

Returns

greater than 0 on success(the XML id) or a negative error code on failure.

remove()

Sint32 CRM64Pro::XMLMgr::remove	(	Sint32	idCDC,
		const string &	sName
	)

Remove a XML file stored in a CDC file.

Parameters

idCDC	CDC id.
sName	string containing the XML object name (maximum size of 64 characters).

Returns

greater than 0 on success or a negative error code on failure.

Note

The XML object must be closed before trying to remove it from the CDC.