Class Documentation

Name:XML
Version:1.0
ID:ID_XML
Status:In Development
Category:Data
Include:pandora/data/xml.h
Date:January 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2001-2004. All rights reserved.



Description

The XML class provides the necessary functionality to create and maintain XML data files. It is capable of interpreting and validating XML files with or without correct structure and can perform various data manipulations while doing so. The XML class is also designed to minimise the amount of resources used in storing XML information and exhibits excellent performance in its processing.

Data can be loaded into an XML object either by specifying a file Location or by giving it an XML Statement. If you have multiple XML statements to process, you can reset the Location or Statement fields after initialisation and the XML object will rebuild itself. This saves you from having to allocate multiple XML objects for batch processing.

Once an XML object has interpreted a statement, you can read the information by scanning the array stored in the Tags field. This array contains an XMLTag structure for each tag found in the original XML statement. For more information on how to scan this information, refer to the Tags field.

Actions

The XML class supports the following actions:

Clear  Clears all of the data held in an XML object.
DataChannel  XML data can be added to an XML object through this action.
GetUnlistedField  Retrieves data from an xml object.
Reset  Clears the information held in an XML object.
SaveToObject  Saves XML data to a data storage object.

Methods

The XML class implements the following methods:

GetXMLContent  Extracts the content embedded inside an XML tag.
GetXMLString  Retrieves data from an XML object in standard XML string format.
RemoveXMLTag  Removes tag(s) from the XML structure.
SetXMLAttribute  Adds and updates XML attributes.
SortXML  Sorts XML tags to your specifications.

Structure

The XML object consists of the following public fields:

CurrentTag  Determines the index of the main tag to use when building XML strings.
Flags  Optional flags.
Location  Set this field if the XML statement originates from a file source.
Statement  XML data is processed through this field.
TagCount  Reflects the total number of tags in the XML array.
Tags  Points to an array of tags loaded into an XML object.
Method:GetXMLContent()
Short:Extracts the content embedded inside an XML tag.
Arguments:
LONG Index  The index of the tag that contains the content that you want to extract.
STRING Buffer  Pointer to a buffer that will receive the string data.
LONG Length  The length of the Buffer in bytes.

The GetXMLContent method is used to extract the string content from an XML tag. It will extract content that is immediately embedded within the XML tag and will not perform deep analysis of the tag structure. Take the following structure for example:

  <body>
    Hello
    <bold>my</bold%gt;
    friend!
  $lt;/body%gt;

This will produce the result "Hello friend!" and miss everything encapsulated within the bold tag.

Result
ERR_Okay  The content string was successfully extracted.
ERR_Args  Invalid arguments were specified.
ERR_BufferOverflow  The buffer was not large enough to hold the content (the resulting string will be valid but truncated).

Method:GetXMLString()
Synonym:GetString
Short:Retrieves data from an XML object in standard XML string format.
Arguments:
LONG Index  The index number of the tag that you want to pull data from (set to zero for all XML data).
LONG Flags  Special flags that affect the construction of the XML string.
STRING Result  The resulting string is returned in this parameter.

Use the GetXMLString method when you want to build XML strings from data that has been loaded into an XML object. You can build information from the entire XML object or from a specific area of the XML tree by setting the Index parameter. Currently supported flags are:

FlagDescription
INCLUDESIBLINGSNormally when building XML strings, only the tag itself and its children will be written to the XML statement. If you want to include other tags sitting at the same level in the XML hierarchy, set this flag.
LOWERCASESet this flag if you want the XML statement to be written entirely in lower-case.
UPPERCASESet this flag if you want the XML statement to be written entirely in upper-case.

The XML string that is built by this method will be stored in the Result parameter. You are required to free this memory block when you are finished with it.

Result
ERR_Okay  The XML string was retrieved.
ERR_Args  Invalid arguments were specified.
ERR_NoData  No information has been loaded into the XML object.
ERR_AllocMemory  Failed to allocate an XML string for the result.

Method:RemoveXMLTag()
Synonym:RemoveTag
Short:Removes tag(s) from the XML structure.
Arguments:
LONG Index  The index of the tag that you want to remove.
LONG Total  The total number of neighbouring tags that should also be deleted. A value of one or less will remove just the indicated tag and its children.

The RemoveTag method is used to remove one or more tags from an XML structure. Any child tags that are discovered will automatically be removed as a consequence of using this method, in order to maintain a valid XML structure.

This method is capable of deleting multiple tags if you set the Total parameter to a value greater than 1. If you do this, each consecutive tag following the first will also be removed from the XML structure. This is useful for mass delete operations.

After using this method, you must assume that all tag addresses have been changed due to the rearrangement of the XML structure. Thus if you have obtained pointers to various parts of the XML structure then you should proceed to consider them invalid and re-establish them.


Method:SetXMLAttribute()
Synonym:SetAttribute
Short:Adds and updates XML attributes.
Arguments:
LONG Index  Reference to the XML tag that you want to update.
LONG Attrib  The index number of the attribute that is to be updated (set to -1 if this is a new attribute).
STRING Name  String containing the new name for the attribute. If NULL, the name will not be changed.
STRING Value  String containing the new value for the attribute.

This method is used to update and add attributes to existing XML tags. You need to supply the address of the tag that the attribute is for and the Index number of the attribute that you are going to update. If you are adding a new attribute to the tag, you must use an Index of -1.

The data for the attribute is defined in the Name and Value parameters. You can set a Value of NULL if no value is to be associated with the attribute. If both Name and Value are NULL, an error will be returned.

Please note that the attribute at index 0 declares the name of the tag and should not normally be accompanied with a value declaration. However, if the tag represents content within its parent, then the Name must be set to NULL and the Value string will determine the content.

WARNING: The address of the original tag will be invalidated as a result of calling this method. You will need to regain the tag address if you are using tag address pointers after calling this routine.

Result
ERR_Okay  The attribute was set.
ERR_Args  The required arguments were not specified.
ERR_OutOfRange  The Index or Attrib value is out of range.

Method:SortXML()
Short:Sorts XML tags to your specifications.
Arguments:
LONG Index  Sort everything under the specified tag, or -1 to sort the entire top level.
*XMLSort List  Pointer to an array of sorting information.

The SortXML method is used to sort a block of XML tags to your specifications. You are required to pass a pointer to the tag that contains each tag item that you want to sort. If the tags lie at the root level, specify NULL in the Root argument. You need to provide an array that specifies sort instructions in the List argument. The array must be terminated with a series of NULL fields. The array structure is as follows:

   struct XMLSort {
      STRING TagName;
      STRING Attribute;
      STRING Flags;
   }

The TagName determines the tag that should be used for sorting each node (which means that you can sort on information held in child tags). You may set this to "Default" if the sort information is to be gathered from the root tags as the sort algorithm scours the chain.

The Attribute field defines what attribute contains the sort data in each XML tag. This should be set to NULL if you want to sort on the content that is found in the XML tag.

The Flags field supports the following options: XSF_DESC forces a descending sort; XSF_CHECKSORT tells the algorithm to check for a 'sort' attribute in each analysed tag and if found, the algorithm should use that as the sort data instead of that indicated in the Attribute field. If the XSF_REPORTSORTED flag is used in the first array entry, the function will report a code of ERR_NothingDone in the event that a rearrangement of the list was not necessary.

Result
ERR_Okay  The XML object was successfully sorted.
ERR_Args  Invalid arguments were specified.
ERR_AllocMemory  A memory allocation error occurred.
ERR_NothingDone  The XML array was already sorted to your specifications. Dependent on XSF_REPORTSORTED.

Field:CurrentTag
Short:Determines the index of the main tag to use when building XML strings.
Type:LONG
Status:Read/Write

When using any XML function that creates an XML string (e.g. SaveToObject), the XML object will include the entire XML tree by default. If you would like to change this behaviour so that only a certain section of the tree is included in the build, set the CurrentTag to the index of the tag that you would like to start building from. You can learn the index number of an XMLTag by reading its Index field. An index of zero will cover the entire XML hierarchy.

The CurrentTag field currently affects the SaveToObject action and the Statement field.


Field:Flags
Short:Optional flags.
Type:LONG
Prefix:XMF
Status:Read/Write

Special flags that apply to the XML class are as follows:

FlagDescription
INCLUDECOMMENTS  Normally comments will be stripped from XML statements during processing, but you may keep comment information by setting this flag.
LOWERCASEThis flag forces all attributes in each XML tag into lowercase characters.
STRIPCONTENTSetting this flag will strip all content from an XML statement during processing.
UPPERCASEThis flag forces all attributes in each XML tag into uppercase characters.
WELLFORMEDBy default, the XML class will accept badly structured XML data. By setting this flag, all processed XML statements must be well formed (tags must balance) or a BadData error will be returned during processing.

Field:Location
Synonyms:Src
Short:Set this field if the XML statement originates from a file source.
Type:STRING
Status:Read/Write

If an XML statement is located in a text file, you may specify a pointer to that file by setting this field. If you set this field after initialisation then the XML object will automatically load the file and process it for you (this will clear out the previous set of XML data).


Field:Statement
Short:XML data is processed through this field.
Type:STRING
Status:Get/Set

To send a string to an XML object, set the Statement field with a pointer to the XML formatted data. If you set this field after initialisation then the XML object will respond by clearing out any existing data and processing the new information that you have passed to it.

Be warned that setting this field with an invalid statement will result in an empty XML object.

If you read the Statement field, a memory block will be returned that contains a string based version of the XML object's data. By default all tags will be included in the statement, but you can start from a specific tag by setting the CurrentTag field. You will need to free the memory block returned by this field when you are done with it.


Field:TagCount
Short:Reflects the total number of tags in the XML array.
Type:LONG
Status:Read

This field can be read to learn the amount of tags in an XML Tags array. Zero is returned if there are no tags in the XML object.


Field:Tags
Short:Points to an array of tags loaded into an XML object.
Type:struct XMLTag **
Status:Read

After initialising data to an XML object, you can read the processed information through the Tags field. The Tags field is a null terminated array of all the XML tags that were retrieved from the original XML data. The XML tags are represented in an XMLTag structure, which is arranged as follows:

   struct XMLTag {
      LONG Index;                       Position within the XML array.
      struct XMLTag *Child;             Reference to further child tags.
      struct XMLTag *Prev;              Reference to the previous tag.
      struct XMLTag *Next;              Reference to the next tag.
      struct XMLAttribute *Attributes;  Attributes linked to the tag.
      WORD TotalAttributes;             The total number of tag attributes.
      WORD Size;                        Size of the structure in bytes.
   };

   struct XMLAttribute {
      STRING Name;
      STRING Value;
   };

Each XMLTag will also have at least one attribute set in the Attributes array (the first attribute reflects the tag name) and the exact number of attributes is indicated by the TotalAttributes field.

There are two methods that you can use for reading the XML tags; the first is to scan through the array using a for loop (this gives a 'flat' view of the data). The second is to read the first tag in the array and use the Next, Prev and Child fields to recurse through the XML tags. Please note that while scanning through the data you may encounter XML tags that have a Name setting of NULL in the first attribute. These tags represent XML content, which you will find in the Value string of the attribute structure.