XML

Description

XML Manager and XML objects providing a full parsing system [25.11.0].

Overview

The XML module provides a complete XML parsing system through the XML Manager and XML objects. Objects can be loaded from external XML files or created programmatically on the fly.

Key features

• File loading: Parse and load XML documents from external files
• Dynamic creation: Build XML structures programmatically at runtime
• Stateful navigation: Each object maintains an internal state with current node pointer and navigation context
• Standard manager: Unique object management using name as the key

Internal state

Each XML object maintains an internal state containing important variables such as the current node pointer. This state is modified during navigation and query operations.

Single-threaded	Safe to use without restrictions
Multi-threaded	Concurrent access to the same object may cause unexpected results due to shared internal state

Concurrency workaround

For read-only concurrent access from multiple threads, duplicate the object:

1. Load the XML object
2. Change its name
3. Load the same XML file again with the original name

This creates two independent objects with separate internal states, allowing safe read-only concurrency.

Manager type

This is a standard manager: objects are not shared and must be unique using its name as the key. You cannot create an object with the same name as another one already created.

Best practices

• Be mindful of the internal state when accessing the same object from different functions
• Avoid concurrent access to the same XML object from multiple threads
• Use the duplication workaround when read-only multi-threaded access is required
• Ensure each object has a unique name before creation or loading
• Access the manager exclusively through Main::IXMLMgr()

Note

The XML Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::IXMLMgr() method.
The XML Manager is automatically released when Main::Terminate() is called. At this time, any resource still loaded will be released, avoiding 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 float &fValue)
	Set an attribute inside pointed node with a float 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, float &fValue)
	Get the float 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 into a CDC file.
Sint32	CRM64Pro::XML::save (Sint32 idCDC)
	Save the XML in to a CDC file.
Sint32	CRM64Pro::XMLMgr::info (Sint32 iMode=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 () const
	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.

Writes information to 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

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

Updates the pointer only when a valid node is found.

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

Updates the pointer only when a valid node is found.

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

Updates the pointer only when a valid node is found.

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

Updates the pointer only when a valid node is found.

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

Updates the pointer only when a valid node is found.

Returns

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

nodeStore()

Sint32 CRM64Pro::XML::nodeStore

(

)

Store node pointer position.

Each XML has a single slot, so it keeps only the most recently stored position.

Returns

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

nodeRestore()

Sint32 CRM64Pro::XML::nodeRestore

(

)

Restore node pointer position.

Each XML has a single slot, so it restores the position saved by the last nodeStore() call.

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 float &	fValue )

Set an attribute inside pointed node with a float value.

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

Parameters

sAttr	attribute name string.
fValue	float 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. Not modified if 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. Not modified if 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,
		float &	fValue )

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

Parameters

sAttr	attribute name string.
fValue	a float variable. Not modified if 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. Not modified if no text exists.

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. Not modified if no comment exists.

Returns

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

Note

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

Only removes the first comment text block found. Call repeatedly until a negative error code to remove all comments.

saveToFile()

Sint32 CRM64Pro::XML::saveToFile

(

const string &

sFile

)

Export the XML to an external file.

Parameters

sFile

string containing [directory]+filename+[extension]. Ideally should have the .xml extension. If the file 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 into a CDC file.

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

Parameters

sFileCDC

string containing [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. Open the CDC first using ArchiveMgr::open() and use XML::save() with the CDC id instead.

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.

Writes information to the default log.

Parameters

iMode

-1 for displaying only Manager information. 0 (default) for displaying Manager and all Objects information. A positive XML id for displaying Manager and that specific XML 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 for the main node (e.g. 'myRootNode'). Also used as the XML object name. Must be unique, max 64 characters (truncated if longer).
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

(

)

const

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 for the XML object (e.g. 'myXML'). Must be unique, max 64 characters (truncated if longer).

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 [directory]+filename+[extension]. Directory separators '\' and '/' are supported.
sName	the XML object name. If empty (default), uses the filename without extension. Must be unique, max 64 characters (truncated if longer).

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 containing the XML to be loaded.
iSize	size in bytes of the buffer data.
sName	the XML object name. Must be unique, max 64 characters (truncated if longer).

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 [directory]+filename+[extension]. Directory separators '\' and '/' are supported.
sName	string containing the XML object name. Must be unique, max 64 characters (truncated if longer).

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. Open the CDC first using ArchiveMgr::open() and use XMLMgr::load() with the CDC id instead.

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. Must be unique, max 64 characters (truncated if longer).

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.