---

XML Accessors

DTD-independant XML parser, validation and generation functions. More...

Files
file	wdxml.h
	XML Accessors interface declarations.
Compounds
struct	XMLValidMsg
	Validation error and warning messages. More...
Functions
WDError	XMLInit ()
	Init function. More...
WDError	XMLCleanup ()
	Cleanup function. More...
WDError	XMLParseFile (const char *iFileName, void **oRoot)
	File Parser. More...
WDError	XMLNewDocument (const char *iRootTag, const char *iDTD, void **oRoot)
	Makes a new XML tree. More...
WDError	XMLDeleteTree (void *iRoot)
	Deletes a parsed tree. More...
WDError	XMLValidate (void *iRoot, int *oValid, XMLValidMsg *oMsg)
	Validates a parsed tree. More...
WDError	XMLDumpTree (const char *iFileName, void *iRoot)
	Dumps a tree to a file. More...
WDError	XMLGetTagName (void *iTag, char *oNameBuffer, int iMaxNameSize)
	Gets the name of a tag. More...
WDError	XMLGetNbrChildren (void *iTag, int *oNbr)
	Get the number of children. More...
WDError	XMLGetNthChild (void *iTag, int iN, void **oChild)
	Gets the nth children of a tag. More...
WDError	XMLGetParent (void *iTag, void **oParent)
	Returns the parent tag. More...
WDError	XMLGetNbrAttributes (void *iTag, int *oNbr)
	Gets the number of attributes. More...
WDError	XMLGetNthAttribute (void *iTag, int iN, void **oAttr)
	Gets the nth attribute of a tag. More...
WDError	XMLGetAttributeName (void *iAttr, char *oNameBuffer, int iMaxNameSize)
	Gets the name of an attribute. More...
WDError	XMLSetAttributeValue (void *iTag, const char *iName, const char *iValue)
	Sets the value of some attribute. More...
WDError	XMLGetAttributeValue (void *iTag, const char *iAttr, char *oVal, int iMaxLength)
	Finds an attribute's value. More...
WDError	XMLFindAttribute (void *iTag, const char *iAttr, void **oAttr)
	Finds an attribute. More...
WDError	XMLFindChild (void *iTag, const char *iName, const char *iID, void **oChild)
	Finds a tag from its ID. More...
WDError	XMLInterchangeTags (void *iTag1, void *iTag2)
	Interchanges two tags. More...
WDError	XMLMoveTagBefore (void *iTag, void *iDest)
	Moves a tag before another one. More...
WDError	XMLMoveTagAfter (void *iTag, void *iDest)
	Moves a tag after another one. More...
WDError	XMLGetNextTag (void *iTag, void **iNext)
	Gets the next sibling of a tag. More...
WDError	XMLGetPrevTag (void *iTag, void **iPrev)
	Gets the previous sibling of a tag. More...
WDError	XMLGetFirstChildren (void *iTag, void **iChild)
	Gets the first children. More...
WDError	XMLNewTag (void *iParent, const char *iName, void **oNewTag)
	Creates a new tag. More...
WDError	XMLSetTagName (void *iTag, const char *iName)
	Sets the tag name. More...
WDError	XMLRemoveTag (void *iTag)
	Removes a tag. More...
WDError	XMLNewAttribute (void *iTag, const char *iName, const char *iVal, void **oAttr)
	Creates a new attribute. More...
WDError	XMLRemoveAttribute (void *iAttr)
	Removes an attribute. More...
WDError	XMLFindChildRecur (void *iTag, const char *iID, void **oChild)
	Finds a tag from its ID (recursive). More...
WDError	XMLUnlinkTag (void *iTag)
	Unlinks a tag. More...
WDError	XMLVerifyRefs (void *iTag, const char *iRefFrom, const char *iRefTo, void **oErrorTag)
	Verifies XML references. More...

---

Detailed Description

DTD-independant XML parser, validation and generation functions.

Those functions are used to parse, validate and generate to a file some XML data from disk. The interface is totally independant of the library used to handle the XML; this module is simply a proxy to the chosen XML library.

Warning:

The functions provided in this module use the "opaque" type void* to refer to parsed tags or attributes. NO validation of any kind is made on the contents of the pointers before they are used (though the NULL value is detected). The behavior of those functions are undefined if the pointers point to unexpected contents.

Author:

Benoit Nadeau , Gaspard Petit

---

Function Documentation

WDError XMLCleanup (    )

Cleanup function. Cleans up the parser. DOES NOT delete the parsed tree. Use XMLDeleteTree() to delete the parsed tree. You should be able to call XMLInit() again after calling this function. Warning: Calling this function more than once in a row might produce unexpected results.

WDError XMLDeleteTree (  void *    iRoot )

Deletes a parsed tree. Deletes a tree rooted at iRoot. Parameters: iRoot  The root tag of the tree to delete. Returns: A WDError value.

WDError XMLDumpTree (  const char *    iFileName, void *    iRoot )

Dumps a tree to a file. This function saves a parsed XML tree (with XMLParseFile() ) to a file on a disk, in XML format. The tree does not need to be validated with XMLValidate() . Parameters: iFileName  The path of the file to save to. iRoot  The root tag of the tree to save. Returns: A WDError value.

WDError XMLFindAttribute (  void *    iTag, const char *    iAttr, void **    oAttr )

Finds an attribute. This function finds an attribute with the name iAttr in the tag iTag . The attribute is returned in oAttr . Parameters: iTag  The tag. iAttr  The name, as a C string, of the attribute to find. oAttr  A pointer to an attribute that will be set to the found attribute. Returns: A WDError value.

WDError XMLFindChild (  void *    iTag, const char *    iName, const char *    iID, void **    oChild )

Finds a tag from its ID. Finds a child given the ID and tag name, looking at the children of iTag . The tree must be previously parsed using XMLValidate() : it looks for the attribute identified as "ID" in the DTD document, regarless of the actual name of the attribute. Warning: This function is not recursive, that is it will not look in the children of iTag's direct children. Parameters: iTag  The tag in which to search. iName  The name of the tag to look for in the children of iTag , as a C string. iID  The ID of the tag to find, as a C string. oChild  A pointer where the found tag, if any, will be stored. Returns: A WDError value.

WDError XMLFindChildRecur (  void *    iTag, const char *    iID, void **    oChild )

Finds a tag from its ID (recursive). This function is similar to XMLFindChild() , but is recursive, i.e. searches all the children, direct and indirect, of iTag . Also, it does not require the name of the tag to be something specific. Parameters: iTag  The tag in which to search. iID  The ID of the tag to find, as a C string. oChild  A pointer where the found tag, if any, will be stored. Returns: A WDError value. See also: XMLFindChild()

WDError XMLGetAttributeName (  void *    iAttr, char *    oNameBuffer, int    iMaxNameSize )

Gets the name of an attribute. This function copies the name of the attribute iAttr , as a C string, in the buffer oNameBuffer . Parameters: iAttr  The attribute. oNameBuffer  The buffer in which the name, as a C string, will be stored. iMaxNameSize  The size of the buffer, in bytes, including the NULL character that will be stored. Returns: A WDError value.

WDError XMLGetAttributeValue (  void *    iTag, const char *    iAttr, char *    oVal, int    iMaxLength )

Finds an attribute's value. This function finds the attribute with the name iAttr in tag iTag , if any, and stores its value in oVal . Parameters: iTag  The tag. iAttr  The name, as a C string, of the attribute to find in tag iTag . oVal  The buffer in which the value, as a C string, will be stored. iMaxLength  The size of the buffer, in bytes, including the NULL character that will be stored. Returns: A WDError value.

WDError XMLGetFirstChildren (  void *    iTag, void **    iChild )

Gets the first children. This function gets the first children of the tag iTag . Parameters: iTag  The tag. iChild  A pointer to a tag that will be set to the first children of iTag . Returns: A WDError value.

WDError XMLGetNbrAttributes (  void *    iTag, int *    oNbr )

Gets the number of attributes. This functions returns the number of attributes of a tag. Parameters: iTag  The tag. oNbr  A pointer to an int that will contain the number of attributes iTag has. Returns: A WDError value.

WDError XMLGetNbrChildren (  void *    iTag, int *    oNbr )

Get the number of children. This function returns the number of children a tag has. Parameters: iTag  The tag. oNbr  A pointer to an int that will contain the number of children iTag has. Returns: A WDError value.

WDError XMLGetNextTag (  void *    iTag, void **    iNext )

Gets the next sibling of a tag. This function gets the next sibling of tag iTag . Parameters: iTag  The tag. iNext  A pointer to a tag that will be set to the next sibling of iTag . Returns: A WDError value.

WDError XMLGetNthAttribute (  void *    iTag, int    iN, void **    oAttr )

Gets the nth attribute of a tag. This function returns the nth attribute, the first attribute being attribute 1 , of a tag. Parameters: iTag  The tag. iN  Which attribute to get, from 1 to the number of attribute iTag has (see XMLGetNbrAttributes() ). oAttr  A pointer that will point to the nth attribute of the tag iTag . Returns: A WDError value.

WDError XMLGetNthChild (  void *    iTag, int    iN, void **    oChild )

Gets the nth children of a tag. This function returns the nth children, the first children being children 1 , of a tag. Parameters: iTag  The tag. iN  Which children to get, from 1 to the number of children iTag has (see XMLGetNbrChildren() ). oChild  A pointer that will point to the nth children of the tag iTag . Returns: A WDError value.

WDError XMLGetParent (  void *    iTag, void **    oParent )

Returns the parent tag. This function returns the parent tag of iTag in oParent. Parameters: iTag  The tag. oParent  A pointer to a tag that will be set to the parent tag of iTag . Returns: A WDError value.

WDError XMLGetPrevTag (  void *    iTag, void **    iPrev )

Gets the previous sibling of a tag. This function gets the previous sibling of tag iTag . Parameters: iTag  The tag. iPrev  A pointer to a tag that will be set to the previous sibling of iTag . Returns: A WDError value.

WDError XMLGetTagName (  void *    iTag, char *    oNameBuffer, int    iMaxNameSize )

Gets the name of a tag. This function copies the name of the tag iTag , as a C string, in the buffer oNameBuffer . Parameters: iTag  The tag. oNameBuffer  The buffer in which the name, as a C string, will be stored. iMaxNameSize  The size of the buffer, in bytes, including the NULL character that will be stored. Returns: A WDError value.

WDError XMLInit (    )

Init function. Initializes the XML parser/validator/generator. Call this when the program opens. Warning: Calling this more than once before calling XMLCleanup() might produce unexpected results. Returns: A WDError value.

WDError XMLInterchangeTags (  void *    iTag1, void *    iTag2 )

Interchanges two tags. Interchanges the tags iTag1 and iTag2 . Warning: iTag1 and iTag2 must be siblings, i.e. have the same direct parent tag. Note: This function is unlikely to be used in the White Dwarf Map Editor, and is kept only for future development of "ANet - the Anonymous Distributed Networking Protocol" by Benoit Nadeau (http://anet.sf.net/). Parameters: iTag1  The first tag to interchange. iTag2  The secong tag to interchange. Returns: A WDError value.

WDError XMLMoveTagAfter (  void *    iTag, void *    iDest )

Moves a tag after another one. Moves the tag iTag after tag iDest . Warning: iTag and iDest must be siblings, i.e. have the same direct parent tag. Parameters: iTag  The tag to move after iDest . iDest  The destination tag. Returns: A WDError value.

WDError XMLMoveTagBefore (  void *    iTag, void *    iDest )

Moves a tag before another one. Moves the tag iTag before tag iDest . Warning: iTag and iDest must be siblings, i.e. have the same direct parent tag. Parameters: iTag  The tag to move before iDest . iDest  The destination tag. Returns: A WDError value.

WDError XMLNewAttribute (  void *    iTag, const char *    iName, const char *    iVal, void **    oAttr )

Creates a new attribute. This function creates a new attribute for tag iTag with name iName and value iVal . The new attribute is returned in oAttr . Parameters: iTag  The tag that will contain the new attribute. iName  The name, as a C string, of the new attribute. iVal  The value, as a C string, of the new attribute. oAttr  A pointer to an attribute that will be set to the newly created attribute. Can be NULL , in which case the value is not set. Returns: A WDError value.

WDError XMLNewDocument (  const char *    iRootTag, const char *    iDTD, void **    oRoot )

Makes a new XML tree. This function creates a new XML tree with a root tag named iRootTag . If iDTD is not NULL, the "SYSTEM" dtd document will be referenced by the tree. The root tag is returned in oRoot . Parameters: iRootTag  The name, as a C string, of the root tag. iDTD  The name of the DTD file, as a C string, that will be used by the new tree. Can be NULL . oRoot  A pointer to a tag that will be set to the root of the new XML tree. Returns: A WDError value.

WDError XMLNewTag (  void *    iParent, const char *    iName, void **    oNewTag )

Creates a new tag. This function creates a new tag with name iName rooted at iParent . The new tag is returned in oNewTag . Parameters: iParent  The tag at which the new tag will be rooted. iName  The name, as a C string, of the new tag. oNewTag  A pointer to a tag that will be set to the newly created tag. Can be NULL , in which case the value is not set. Returns: A WDError value.

WDError XMLParseFile (  const char *    iFileName, void **    oRoot )

File Parser. Parses a file from disk to memory. No validation is made. Parameters: iFileName  The path to the file to parse. oRoot  A pointer to where the root tag of the parsed tree will be stored. Returns: A WDError value.

WDError XMLRemoveAttribute (  void *    iAttr )

Removes an attribute. This function removes the attribute iAttr from its tag. Parameters: iAttr  The attribute to remove. Returns: A WDError value.

WDError XMLRemoveTag (  void *    iTag )

Removes a tag. This function removes the tag iTag from its tree. Parameters: iTag  The tag to remove. Returns: A WDError value.

WDError XMLSetAttributeValue (  void *    iTag, const char *    iName, const char *    iValue )

Sets the value of some attribute. This function sets the value of attribute iName of the tag iTag to the string iValue. Parameters: iTag  The tag. iName  The name, as a C string, of the attribute in iTag to change its value. iValue  The new value. Returns: A WDError value.

WDError XMLSetTagName (  void *    iTag, const char *    iName )

Sets the tag name. Changes the name of the tag iTag to iName. Parameters: iTag  The tag. iName  The new name. Returns: A WDError value.

WDError XMLUnlinkTag (  void *    iTag )

Unlinks a tag. Removes the tag \iTag from its document context. This removes the tag from the list of its parent's children and removes any information about its sibling and parent from the tag. To properly delete the tag, use XMLRemoveTag() . Parameters: iTag  The tag to unlink. Returns: A WDError value. See also: XMLRemoveTag()

WDError XMLValidate (  void *    iRoot, int *    oValid, XMLValidMsg *    oMsg )

Validates a parsed tree. This function validates a XML tree, rooted at iRoot , that was previously parsed with XMLParseFile() . Parameters: iRoot  The root tag of the tree to validate. oValid  Pointer to an int that will be set to 1 if the tree is valid, 0 otherwise. oMsg  A pointer to a XMLValidMsg structure to be filled with the validator's warning and error messages. Can be NULL . Returns: A WDError value.

WDError XMLVerifyRefs (  void *    iTag, const char *    iRefFrom, const char *    iRefTo, void **    oErrorTag )

Verifies XML references. This function verifies that all the XML "IDREF" attributes from tags named iRefFrom refer properly to an "ID" attribute of some tag with name iRefTo . If an error is found, the first tag with an error found is placed in oErrorTag . This function recursively verifies all the tags. Parameters: iTag  The root tag from which verification is made. iRefFrom  The name of the tags to verify. iRefTo  The name of the tag they should refer to. oErrorTag  A pointer to a tag that will be set to the erronous tag is an error is found. Can be NULL . Returns: A WDError value.

---