--- a/Symbian3/SDK/Source/GUID-5ACFA8E4-3C4B-5851-A43E-9FA72D0B8403.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-5ACFA8E4-3C4B-5851-A43E-9FA72D0B8403.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,241 +1,241 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
-<!-- This component and the accompanying materials are made available under the terms of the License
-"Eclipse Public License v1.0" which accompanies this distribution,
-and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
-<!-- Initial Contributors:
- Nokia Corporation - initial contribution.
-Contributors:
--->
-<!DOCTYPE concept
- PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="GUID-5ACFA8E4-3C4B-5851-A43E-9FA72D0B8403" xml:lang="en"><title>XML
-DOM Engine Overview</title><shortdesc>The XML DOM Engine implements the standard DOM API (tree-based
-XML parsing and editing), including XPath and serialization extensions. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
-<section><title>Purpose</title> <p>The XML DOM Engine provides APIs to achieve
-the following: </p> <ul>
-<li id="GUID-D9B629FA-A426-5B43-ABAD-B49404822464"><p>Parse XML content: create
-a DOM tree from XML streams or files </p> </li>
-<li id="GUID-EBEBE1E6-1AEF-5181-A7C4-D4E3E3152FE4"><p>Create an empty DOM
-tree </p> </li>
-<li id="GUID-C8B88AF6-A2F0-5AE1-B207-8D56988DC5F9"><p>Modify a DOM tree by
-adding or removing nodes and changing their properties (attributes?) </p> </li>
-<li id="GUID-70322A4D-BDD9-5A93-8D38-107E46F4C952"><p>Save a DOM tree to a
-buffer or a file (in regular XML, XOP or compressed format) </p> </li>
-<li id="GUID-1A8514F7-534B-5C2A-9EF5-6F444B2FEE9F"><p>Explore a DOM tree with
-XPath expressions </p> </li>
-</ul> </section>
-<section><title>Required background</title> <p>The XML DOM engine is based
-on the <xref href="GUID-33D50AB9-AFA8-521F-8A85-031C24EA7D25.dita">libxml2</xref> component.
-It provides a Level-3-like implementation of the <xref href="http://www.w3.org/DOM/" scope="external">DOM</xref> standard from W3C, along with <xref href="http://www.w3.org/TR/xpath" scope="external">XPath</xref> and serialisation extensions. </p> </section>
-<section><title>Key concepts and terms</title> <p>The following concepts are
-related to generic XML understanding: </p><p><b>XPath Extension Functions</b></p><p>XML
-Path Language (or XPath) is a W3C standard designed to address parts of an
-XML document. A subset of XPath is also used for matching: that is, checking
-that a node matches a pattern. Extension Functions are not part of the W3C
-standard: you can implement them to add functionalities to XPath. </p><p><b>Serialise</b></p><p>Serialising
-means converting binary data to a persistent format that can be stored (to
-a buffer or a file) or transmitted over a data link. The reverse operation
-is called deserialising. </p><p>The <b>RChunk</b> and <b>RHeap</b> classes
-are standard Symbian platform classes. For more information,
-see <xref href="GUID-6D8460DF-8B0F-5249-B236-92ABE0E67A14.dita">Memory allocation
-concepts</xref>. </p> </section>
-<section><title>Architecture</title> <p>The XML DOM Engine component relies
-on the libxml2 component for most of its operations. For more information,
-see <xref href="GUID-33D50AB9-AFA8-521F-8A85-031C24EA7D25.dita">libxml2 Overview</xref>. </p> <p>It
-also relies on the libxml2 SAX parser plugin of the <xref href="GUID-F79E4F18-19E2-577E-8409-8B82BD48AC66.dita">XML
-Framework</xref> and on the multi-part parser of the <xref href="GUID-C8BD333E-8384-534B-822B-F61B2F7C8B9F.dita">BAFL</xref> component
-for deserialisation. </p> <p>The following package diagram summarises the
-dependencies of the XML DOM Engine and shows the three functionality groups
-that are described in the following section. </p> <fig id="GUID-EEFA9390-CA66-56DD-96B4-9DF7C35AB36D">
-<title> Package diagram for the XML DOM Engine component
- </title>
-<image href="GUID-AE69AA42-E633-5B7A-BAA1-6896950E0E19_d0e429835_href.png" placement="inline"/>
-</fig> </section>
-<section><title>Description</title> <p>The XML DOM Engine is an object-oriented
-provider of the DOM services included in the standard libxml2 library: tree-based
-parsing with validation and random access to the XML elements. If you need
-event-based parsing, use the <xref href="GUID-F79E4F18-19E2-577E-8409-8B82BD48AC66.dita">XML
-Framework</xref> instead. </p> <p><b>DOM Parsing</b> </p> <p>Parsing an XML
-document creates two parallel trees: the regular DOM tree containing generic
-Node objects and an <xref href="GUID-87294A6B-4607-3D4A-9D1E-B87B16A06209.dita"><apiname>RXmlEngDocument</apiname></xref> object which contains
-type-specific nodes. Use these type-specific nodes to avoid type-checking
-and casting the Nodes as well as to improve performance. Some of these node
-types are shown in the following diagram. </p> <fig id="GUID-32F52AA5-2670-5C4C-B9EE-508BDB3B9E78">
-<title> Extract of the class diagram for the XML DOM Engine
-parser </title>
-<image href="GUID-9BF177DF-9E59-5C30-95BA-70A8250579E0_d0e429866_href.png" placement="inline"/>
-</fig> <p><b>Serialisation</b> </p> <p>Serialisation transforms the DOM tree
-(including binary data) into one of the following formats: </p> <ul>
-<li id="GUID-C7E6E69A-9373-5A8E-A0A4-FABA95738ACC"><p>Default (standard XML) </p> </li>
-<li id="GUID-46B3A636-54BE-556A-B5D5-277378BD4BAB"><p>XOP (XML-binary Optimized
-Packaging) </p> </li>
-<li id="GUID-6DA98291-237E-5CD0-87ED-D6DBE56A9846"><p>XOP Infoset (original
-Infoset with any optimized content replaced by <codeph>xop:Include</codeph> items) </p> </li>
-<li id="GUID-235F5E65-C2A3-55FE-8537-B2F986367FFD"><p>gzip (compressed XML) </p> </li>
-</ul> <p>The result can be returned as a file, a buffer or both. </p> <p><b>XPath
-Extension Function</b> </p> <p>XPath can be extended at run-time by registering
-a new extension function. To call the new function, include it in an XPath
-expression evaluated by the XML DOM Engine. </p> <p>The XPath Extension Function
-API provides two interfaces: <xref href="GUID-BCEBA44D-3C1A-38D2-BFDB-6CA14DF40CE9.dita"><apiname>MXPathExtensionFunction</apiname></xref> for
-the XPath function and <xref href="GUID-33B9C910-FCFC-36A5-B4CC-AA54DF4043E0.dita"><apiname>MXmlEngXpathEvaluationContext</apiname></xref> for
-its configuration. The static <xref href="GUID-79B8C611-4646-330F-98EA-C387BDB430E2.dita"><apiname>TXmlEngXPathConfiguration</apiname></xref> class
-performs the registration of the extension function within the XML DOM Engine. </p> </section>
-<section><title>APIs</title> <p><b>DOM Parser API</b> </p> <p>The most relevant
-classes for parsing and editing a DOM tree are listed in the following table.
-See <xref href="GUID-326D4D50-5AD9-5CA2-8422-AA45AE0712D6.dita">Implementation
-of W3C Types</xref> for correspondance between this API and the W3C standard. </p> <table id="GUID-B401C7C0-E8C1-5576-BF6A-DF722024F896">
-<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
-<thead>
-<row>
-<entry>DOM Parser API</entry>
-<entry>Description</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry><p> <xref href="GUID-A59972BD-707E-32B6-AF28-D2B8C6EA17F8.dita"><apiname>RXMLEngDOMImplementation</apiname></xref> </p> </entry>
-<entry><p>This class is the entry-point for the DOM Engine. It provides methods
-for creating a new document or an instance of the DOM parser. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-701146BE-35E9-380F-AA58-25E4660C50EB.dita"><apiname>RXMLEngDomParser</apiname></xref> </p> </entry>
-<entry><p>This class provides methods for parsing an XML document and building
-a DOM tree. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-BCF2D3E3-3A31-3D79-B355-04984EFF0551.dita"><apiname>RXMLEngDocument</apiname></xref> </p> </entry>
-<entry><p>This class represents a DOM tree. It stores the document properties
-and provides methods for modifying the tree, such as adding or deleting nodes. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-56A1BCDD-A471-310B-8F9D-85AF2FAB2B37.dita"><apiname>TXMLEngNode</apiname></xref> </p> </entry>
-<entry><p>This class represents a DOM node. It stores the node type and properties,
-and provides the DOM methods related to it. </p> <p>Specialisations of this
-class are detailed in <xref href="GUID-1CB7491C-1207-5C2E-979F-8ABEB95EE9D9.dita">XML
-DOM Engine Node Reference</xref>. </p> </entry>
-</row>
-</tbody>
-</tgroup>
-</table> <p>The DOM API relies on Descriptor objects for string manipulation,
-and on <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref> handles for filesystem input and output. To
-store <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref> in a DOM tree, use the <xref href="GUID-FC3D2792-A98A-37FF-A59C-28DF0555FDCD.dita"><apiname>TXmlEngFileContainer</apiname></xref> class.
-To store <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk</apiname></xref> in a DOM tree, use the <xref href="GUID-5D101B85-E1D0-3C78-8C97-3FB8CE459EC6.dita"><apiname>TXmlEngChunkContainer</apiname></xref> class. </p> <p><b>Serialisation
-API</b> </p> <p>The most relevant classes for DOM serialisation and deserialisation
-are listed in the following table. Other classes can be found in the reference
-documentation. </p> <table id="GUID-0FBACCD6-BC4D-5CAF-88E7-61DE329EADB4">
-<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
-<thead>
-<row>
-<entry>Serialisation API</entry>
-<entry>Description</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry><p> <xref href="GUID-ADFEF636-484D-35BF-B6C5-B9F47317ACD9.dita"><apiname>CXmlEngSerializer</apiname></xref> </p> </entry>
-<entry><p>This class provides methods to save a DOM tree to a file or a buffer. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-791D9C19-3942-3107-8C91-F56528CF2590.dita"><apiname>CXmlEngDeserializer</apiname></xref> </p> </entry>
-<entry><p>This class provides methods to read serialised XOP or GZIP and create
-DOM or SAX representations of it. </p> </entry>
-</row>
-</tbody>
-</tgroup>
-</table> <p><b>XPath APIs</b> </p> <p>The DOM Parsing classes related to XPath
-are listed in the following table. Other classes can be found in the reference
-documentation. </p> <table id="GUID-0E32710B-BEA3-5D01-B48F-BC753AA13625">
-<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
-<thead>
-<row>
-<entry>XPath API</entry>
-<entry>Description</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry><p> <xref href="GUID-036E87E6-F6FB-371B-8CAB-FBD8C2635FDA.dita"><apiname>RXmlEngXPathExpression</apiname></xref> </p> </entry>
-<entry><p>This class represents an XPath expression. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-D76EC81E-B92E-304A-8651-068459763BBA.dita"><apiname>TXmlEmgXPathEvaluator</apiname></xref> </p> </entry>
-<entry><p>This class evaluates an XPath expression and returns the result
-in an <xref href="GUID-C84A1329-F403-370F-9740-6A8D38D72F22.dita"><apiname>RXmlEngXPathResult</apiname></xref> instance. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-1053AD9F-99BD-34D8-A77B-9B4F66FD7CCF.dita"><apiname>XmlEngXPathConfiguration</apiname></xref> </p> </entry>
-<entry><p>This class contains static methods for XPath configuration and registration
-of extension functions. </p> </entry>
-</row>
-</tbody>
-</tgroup>
-</table> <p>The most relevant classes of the Extension Function API for XPath
-are listed in the following table. Other classes can be found in the reference
-documentation. </p> <table id="GUID-6200B207-23F8-522A-885E-8DFA82CECE0F">
-<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
-<thead>
-<row>
-<entry> XPath Extension Function API</entry>
-<entry>Description</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry><p> <xref href="GUID-6158C316-5D11-33D9-9599-4C3E98DF1748.dita"><apiname>MXmlEngXPathExtensionFunction</apiname></xref> </p> </entry>
-<entry><p>This interface must be implemented by your extension function. </p> </entry>
-</row>
-<row>
-<entry><p> <xref href="GUID-33B9C910-FCFC-36A5-B4CC-AA54DF4043E0.dita"><apiname>MXmlEngXpathEvaluationContext</apiname></xref> </p> </entry>
-<entry><p>This interface must be implemented by your evaluation function,
-which processes the arguments of the extension function and stores the result
-of the evalutation. </p> </entry>
-</row>
-</tbody>
-</tgroup>
-</table> </section>
-<section><title>Typical uses</title> <p>The XML DOM Engine is used by client
-applications to process XML documents: </p> <ul>
-<li id="GUID-4D5B1DAB-FEFD-5D66-8917-761042DC362A"><p>The most common clients
-are web browsers and associated software, which parse and validate XML streams
-or files. </p> </li>
-<li id="GUID-4DFB1B4A-1F07-53E6-B043-D10D5C09679F"><p>Applications can also
-use the XML DOM Engine to organize and store their data, or to transfer their
-XML objects over a network connection. </p> </li>
-<li id="GUID-98C0B034-7B47-5D00-8148-CEA28A53E9B0"><p>Middleware providers
-can extend XPath with new functions with the XPath Extension Function API. </p> </li>
-</ul> <p>To port an existing application that uses the standard libxml2 library,
-use the <codeph>libxml2</codeph> component and call the C++ wrappers of the
-standard library. </p> <p>Here are some of the common tasks that applications
-perform through the XML DOM Engine: </p> <ul>
-<li id="GUID-2F9859FD-1B09-58FB-849D-323B01D9F63D"><p>Read an XML file by
-one of the following means: </p> <ul>
-<li id="GUID-AC959FCA-A1F5-5691-8B4A-FFD8E385C25B"><p>Use the <xref href="GUID-B575F3B3-85B0-3709-932A-99C0388D8B6E.dita"><apiname>RXMLEngDOMParser</apiname></xref> class
-to parse a regular XML file and get a DOM tree, as explained in the <xref href="GUID-C5C30218-311C-58D9-A990-3F95642F7517.dita">XML DOM Parsing Tutorial</xref>. </p> </li>
-<li id="GUID-EC051C8A-47D1-5DE3-9093-C67FA6F75896"><p>Use the <xref href="GUID-72FD946E-36E1-3229-BF78-0E03D84BCB95.dita"><apiname>CXMLEngineSaxPlugin</apiname></xref> class
-to parse a regular XML file and get SAX events, as explained in the <xref href="GUID-AF937B6E-7BC0-5B7D-818E-93F7CAFD8808.dita#GUID-AF937B6E-7BC0-5B7D-818E-93F7CAFD8808/GUID-948C5BEE-0E05-525A-B601-909A1818FDA0">XML
-SAX Parsing Tutorial</xref>. </p> </li>
-<li id="GUID-149E3236-EAB3-5990-8E5C-40B36BB89ACB"><p>Use the <codeph>DeserializeL()</codeph>
-method of the <xref href="GUID-B58E0BF8-099A-3E61-BA8C-E777CA9E9F38.dita"><apiname>TXmlEngDeserializer</apiname></xref> class to deserialise
-a compressed XML file and get SAX events. </codeph></p> </li>
-<li id="GUID-3165531B-E5EC-5965-ACA9-4B660C40C6D8"><p>Use the <codeph>UseDOMImplementation()</codeph> and <codeph>DeserializeL()</codeph> methods
-of the <xref href="GUID-B58E0BF8-099A-3E61-BA8C-E777CA9E9F38.dita"><apiname>TXmlEngDeserializer</apiname></xref> class to deserialise a compressed
-XML file and get a DOM tree. </p> </li>
-</ul> </li>
-<li id="GUID-A2269AAD-B0F9-50D2-8A96-5AEC601C84AA"><p>Save an XML object to
-a file by using the <xref href="GUID-CD621FD4-8ADE-3211-96E9-FC6EFC9AEE2C.dita"><apiname>TXmlEngSerializer</apiname></xref> class, as explained
-in the <xref href="GUID-E20C2C98-A294-551B-99CF-BE1DAA6F597E.dita">XML Serialisation
-Tutorial</xref>. </p> </li>
-<li id="GUID-2999261C-7049-50A6-A1DF-79CD57A039C4"><p>Search through an XML
-document with XPath, as explained in the <xref href="GUID-92C2317A-57B8-558E-984B-B10FD0404981.dita">XPath
-Tutorial</xref>. </p> </li>
-<li id="GUID-D527989F-D3D8-50B5-9191-FBD59FCAC335"><p>Add extension functions
-to XPath, as explained in the <xref href="GUID-49A7E8FD-72DA-5D56-86BE-74AA9AAF7C02.dita">XPath
-Extension Tutorial</xref>. </p> </li>
-</ul> </section>
-</conbody><related-links>
-<link href="GUID-F79E4F18-19E2-577E-8409-8B82BD48AC66.dita"><linktext>XML Framework</linktext>
-</link>
-<link href="GUID-33D50AB9-AFA8-521F-8A85-031C24EA7D25.dita"><linktext>libxml2</linktext>
-</link>
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License
+"Eclipse Public License v1.0" which accompanies this distribution,
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+ Nokia Corporation - initial contribution.
+Contributors:
+-->
+<!DOCTYPE concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-5ACFA8E4-3C4B-5851-A43E-9FA72D0B8403" xml:lang="en"><title>XML
+DOM Engine Overview</title><shortdesc>The XML DOM Engine implements the standard DOM API (tree-based
+XML parsing and editing), including XPath and serialization extensions. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section><title>Purpose</title> <p>The XML DOM Engine provides APIs to achieve
+the following: </p> <ul>
+<li id="GUID-D9B629FA-A426-5B43-ABAD-B49404822464"><p>Parse XML content: create
+a DOM tree from XML streams or files </p> </li>
+<li id="GUID-EBEBE1E6-1AEF-5181-A7C4-D4E3E3152FE4"><p>Create an empty DOM
+tree </p> </li>
+<li id="GUID-C8B88AF6-A2F0-5AE1-B207-8D56988DC5F9"><p>Modify a DOM tree by
+adding or removing nodes and changing their properties (attributes?) </p> </li>
+<li id="GUID-70322A4D-BDD9-5A93-8D38-107E46F4C952"><p>Save a DOM tree to a
+buffer or a file (in regular XML, XOP or compressed format) </p> </li>
+<li id="GUID-1A8514F7-534B-5C2A-9EF5-6F444B2FEE9F"><p>Explore a DOM tree with
+XPath expressions </p> </li>
+</ul> </section>
+<section><title>Required background</title> <p>The XML DOM engine is based
+on the <xref href="GUID-33D50AB9-AFA8-521F-8A85-031C24EA7D25.dita">libxml2</xref> component.
+It provides a Level-3-like implementation of the <xref href="http://www.w3.org/DOM/" scope="external">DOM</xref> standard from W3C, along with <xref href="http://www.w3.org/TR/xpath" scope="external">XPath</xref> and serialisation extensions. </p> </section>
+<section><title>Key concepts and terms</title> <p>The following concepts are
+related to generic XML understanding: </p><p><b>XPath Extension Functions</b></p><p>XML
+Path Language (or XPath) is a W3C standard designed to address parts of an
+XML document. A subset of XPath is also used for matching: that is, checking
+that a node matches a pattern. Extension Functions are not part of the W3C
+standard: you can implement them to add functionalities to XPath. </p><p><b>Serialise</b></p><p>Serialising
+means converting binary data to a persistent format that can be stored (to
+a buffer or a file) or transmitted over a data link. The reverse operation
+is called deserialising. </p><p>The <b>RChunk</b> and <b>RHeap</b> classes
+are standard Symbian platform classes. For more information,
+see <xref href="GUID-6D8460DF-8B0F-5249-B236-92ABE0E67A14.dita">Memory allocation
+concepts</xref>. </p> </section>
+<section><title>Architecture</title> <p>The XML DOM Engine component relies
+on the libxml2 component for most of its operations. For more information,
+see <xref href="GUID-33D50AB9-AFA8-521F-8A85-031C24EA7D25.dita">libxml2 Overview</xref>. </p> <p>It
+also relies on the libxml2 SAX parser plugin of the <xref href="GUID-F79E4F18-19E2-577E-8409-8B82BD48AC66.dita">XML
+Framework</xref> and on the multi-part parser of the <xref href="GUID-C8BD333E-8384-534B-822B-F61B2F7C8B9F.dita">BAFL</xref> component
+for deserialisation. </p> <p>The following package diagram summarises the
+dependencies of the XML DOM Engine and shows the three functionality groups
+that are described in the following section. </p> <fig id="GUID-EEFA9390-CA66-56DD-96B4-9DF7C35AB36D">
+<title> Package diagram for the XML DOM Engine component
+ </title>
+<image href="GUID-AE69AA42-E633-5B7A-BAA1-6896950E0E19_d0e429673_href.png" placement="inline"/>
+</fig> </section>
+<section><title>Description</title> <p>The XML DOM Engine is an object-oriented
+provider of the DOM services included in the standard libxml2 library: tree-based
+parsing with validation and random access to the XML elements. If you need
+event-based parsing, use the <xref href="GUID-F79E4F18-19E2-577E-8409-8B82BD48AC66.dita">XML
+Framework</xref> instead. </p> <p><b>DOM Parsing</b> </p> <p>Parsing an XML
+document creates two parallel trees: the regular DOM tree containing generic
+Node objects and an <xref href="GUID-87294A6B-4607-3D4A-9D1E-B87B16A06209.dita"><apiname>RXmlEngDocument</apiname></xref> object which contains
+type-specific nodes. Use these type-specific nodes to avoid type-checking
+and casting the Nodes as well as to improve performance. Some of these node
+types are shown in the following diagram. </p> <fig id="GUID-32F52AA5-2670-5C4C-B9EE-508BDB3B9E78">
+<title> Extract of the class diagram for the XML DOM Engine
+parser </title>
+<image href="GUID-9BF177DF-9E59-5C30-95BA-70A8250579E0_d0e429704_href.png" placement="inline"/>
+</fig> <p><b>Serialisation</b> </p> <p>Serialisation transforms the DOM tree
+(including binary data) into one of the following formats: </p> <ul>
+<li id="GUID-C7E6E69A-9373-5A8E-A0A4-FABA95738ACC"><p>Default (standard XML) </p> </li>
+<li id="GUID-46B3A636-54BE-556A-B5D5-277378BD4BAB"><p>XOP (XML-binary Optimized
+Packaging) </p> </li>
+<li id="GUID-6DA98291-237E-5CD0-87ED-D6DBE56A9846"><p>XOP Infoset (original
+Infoset with any optimized content replaced by <codeph>xop:Include</codeph> items) </p> </li>
+<li id="GUID-235F5E65-C2A3-55FE-8537-B2F986367FFD"><p>gzip (compressed XML) </p> </li>
+</ul> <p>The result can be returned as a file, a buffer or both. </p> <p><b>XPath
+Extension Function</b> </p> <p>XPath can be extended at run-time by registering
+a new extension function. To call the new function, include it in an XPath
+expression evaluated by the XML DOM Engine. </p> <p>The XPath Extension Function
+API provides two interfaces: <xref href="GUID-BCEBA44D-3C1A-38D2-BFDB-6CA14DF40CE9.dita"><apiname>MXPathExtensionFunction</apiname></xref> for
+the XPath function and <xref href="GUID-33B9C910-FCFC-36A5-B4CC-AA54DF4043E0.dita"><apiname>MXmlEngXpathEvaluationContext</apiname></xref> for
+its configuration. The static <xref href="GUID-79B8C611-4646-330F-98EA-C387BDB430E2.dita"><apiname>TXmlEngXPathConfiguration</apiname></xref> class
+performs the registration of the extension function within the XML DOM Engine. </p> </section>
+<section><title>APIs</title> <p><b>DOM Parser API</b> </p> <p>The most relevant
+classes for parsing and editing a DOM tree are listed in the following table.
+See <xref href="GUID-326D4D50-5AD9-5CA2-8422-AA45AE0712D6.dita">Implementation
+of W3C Types</xref> for correspondance between this API and the W3C standard. </p> <table id="GUID-B401C7C0-E8C1-5576-BF6A-DF722024F896">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<thead>
+<row>
+<entry>DOM Parser API</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <xref href="GUID-A59972BD-707E-32B6-AF28-D2B8C6EA17F8.dita"><apiname>RXMLEngDOMImplementation</apiname></xref> </p> </entry>
+<entry><p>This class is the entry-point for the DOM Engine. It provides methods
+for creating a new document or an instance of the DOM parser. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-701146BE-35E9-380F-AA58-25E4660C50EB.dita"><apiname>RXMLEngDomParser</apiname></xref> </p> </entry>
+<entry><p>This class provides methods for parsing an XML document and building
+a DOM tree. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-BCF2D3E3-3A31-3D79-B355-04984EFF0551.dita"><apiname>RXMLEngDocument</apiname></xref> </p> </entry>
+<entry><p>This class represents a DOM tree. It stores the document properties
+and provides methods for modifying the tree, such as adding or deleting nodes. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-56A1BCDD-A471-310B-8F9D-85AF2FAB2B37.dita"><apiname>TXMLEngNode</apiname></xref> </p> </entry>
+<entry><p>This class represents a DOM node. It stores the node type and properties,
+and provides the DOM methods related to it. </p> <p>Specialisations of this
+class are detailed in <xref href="GUID-1CB7491C-1207-5C2E-979F-8ABEB95EE9D9.dita">XML
+DOM Engine Node Reference</xref>. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p>The DOM API relies on Descriptor objects for string manipulation,
+and on <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref> handles for filesystem input and output. To
+store <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref> in a DOM tree, use the <xref href="GUID-FC3D2792-A98A-37FF-A59C-28DF0555FDCD.dita"><apiname>TXmlEngFileContainer</apiname></xref> class.
+To store <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk</apiname></xref> in a DOM tree, use the <xref href="GUID-5D101B85-E1D0-3C78-8C97-3FB8CE459EC6.dita"><apiname>TXmlEngChunkContainer</apiname></xref> class. </p> <p><b>Serialisation
+API</b> </p> <p>The most relevant classes for DOM serialisation and deserialisation
+are listed in the following table. Other classes can be found in the reference
+documentation. </p> <table id="GUID-0FBACCD6-BC4D-5CAF-88E7-61DE329EADB4">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<thead>
+<row>
+<entry>Serialisation API</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <xref href="GUID-ADFEF636-484D-35BF-B6C5-B9F47317ACD9.dita"><apiname>CXmlEngSerializer</apiname></xref> </p> </entry>
+<entry><p>This class provides methods to save a DOM tree to a file or a buffer. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-791D9C19-3942-3107-8C91-F56528CF2590.dita"><apiname>CXmlEngDeserializer</apiname></xref> </p> </entry>
+<entry><p>This class provides methods to read serialised XOP or GZIP and create
+DOM or SAX representations of it. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p><b>XPath APIs</b> </p> <p>The DOM Parsing classes related to XPath
+are listed in the following table. Other classes can be found in the reference
+documentation. </p> <table id="GUID-0E32710B-BEA3-5D01-B48F-BC753AA13625">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<thead>
+<row>
+<entry>XPath API</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <xref href="GUID-036E87E6-F6FB-371B-8CAB-FBD8C2635FDA.dita"><apiname>RXmlEngXPathExpression</apiname></xref> </p> </entry>
+<entry><p>This class represents an XPath expression. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-D76EC81E-B92E-304A-8651-068459763BBA.dita"><apiname>TXmlEmgXPathEvaluator</apiname></xref> </p> </entry>
+<entry><p>This class evaluates an XPath expression and returns the result
+in an <xref href="GUID-C84A1329-F403-370F-9740-6A8D38D72F22.dita"><apiname>RXmlEngXPathResult</apiname></xref> instance. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-1053AD9F-99BD-34D8-A77B-9B4F66FD7CCF.dita"><apiname>XmlEngXPathConfiguration</apiname></xref> </p> </entry>
+<entry><p>This class contains static methods for XPath configuration and registration
+of extension functions. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p>The most relevant classes of the Extension Function API for XPath
+are listed in the following table. Other classes can be found in the reference
+documentation. </p> <table id="GUID-6200B207-23F8-522A-885E-8DFA82CECE0F">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<thead>
+<row>
+<entry> XPath Extension Function API</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <xref href="GUID-6158C316-5D11-33D9-9599-4C3E98DF1748.dita"><apiname>MXmlEngXPathExtensionFunction</apiname></xref> </p> </entry>
+<entry><p>This interface must be implemented by your extension function. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-33B9C910-FCFC-36A5-B4CC-AA54DF4043E0.dita"><apiname>MXmlEngXpathEvaluationContext</apiname></xref> </p> </entry>
+<entry><p>This interface must be implemented by your evaluation function,
+which processes the arguments of the extension function and stores the result
+of the evalutation. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> </section>
+<section><title>Typical uses</title> <p>The XML DOM Engine is used by client
+applications to process XML documents: </p> <ul>
+<li id="GUID-4D5B1DAB-FEFD-5D66-8917-761042DC362A"><p>The most common clients
+are web browsers and associated software, which parse and validate XML streams
+or files. </p> </li>
+<li id="GUID-4DFB1B4A-1F07-53E6-B043-D10D5C09679F"><p>Applications can also
+use the XML DOM Engine to organize and store their data, or to transfer their
+XML objects over a network connection. </p> </li>
+<li id="GUID-98C0B034-7B47-5D00-8148-CEA28A53E9B0"><p>Middleware providers
+can extend XPath with new functions with the XPath Extension Function API. </p> </li>
+</ul> <p>To port an existing application that uses the standard libxml2 library,
+use the <codeph>libxml2</codeph> component and call the C++ wrappers of the
+standard library. </p> <p>Here are some of the common tasks that applications
+perform through the XML DOM Engine: </p> <ul>
+<li id="GUID-2F9859FD-1B09-58FB-849D-323B01D9F63D"><p>Read an XML file by
+one of the following means: </p> <ul>
+<li id="GUID-AC959FCA-A1F5-5691-8B4A-FFD8E385C25B"><p>Use the <xref href="GUID-B575F3B3-85B0-3709-932A-99C0388D8B6E.dita"><apiname>RXMLEngDOMParser</apiname></xref> class
+to parse a regular XML file and get a DOM tree, as explained in the <xref href="GUID-C5C30218-311C-58D9-A990-3F95642F7517.dita">XML DOM Parsing Tutorial</xref>. </p> </li>
+<li id="GUID-EC051C8A-47D1-5DE3-9093-C67FA6F75896"><p>Use the <xref href="GUID-72FD946E-36E1-3229-BF78-0E03D84BCB95.dita"><apiname>CXMLEngineSaxPlugin</apiname></xref> class
+to parse a regular XML file and get SAX events, as explained in the <xref href="GUID-AF937B6E-7BC0-5B7D-818E-93F7CAFD8808.dita#GUID-AF937B6E-7BC0-5B7D-818E-93F7CAFD8808/GUID-948C5BEE-0E05-525A-B601-909A1818FDA0">XML
+SAX Parsing Tutorial</xref>. </p> </li>
+<li id="GUID-149E3236-EAB3-5990-8E5C-40B36BB89ACB"><p>Use the <codeph>DeserializeL()</codeph>
+method of the <xref href="GUID-B58E0BF8-099A-3E61-BA8C-E777CA9E9F38.dita"><apiname>TXmlEngDeserializer</apiname></xref> class to deserialise
+a compressed XML file and get SAX events. </codeph></p> </li>
+<li id="GUID-3165531B-E5EC-5965-ACA9-4B660C40C6D8"><p>Use the <codeph>UseDOMImplementation()</codeph> and <codeph>DeserializeL()</codeph> methods
+of the <xref href="GUID-B58E0BF8-099A-3E61-BA8C-E777CA9E9F38.dita"><apiname>TXmlEngDeserializer</apiname></xref> class to deserialise a compressed
+XML file and get a DOM tree. </p> </li>
+</ul> </li>
+<li id="GUID-A2269AAD-B0F9-50D2-8A96-5AEC601C84AA"><p>Save an XML object to
+a file by using the <xref href="GUID-CD621FD4-8ADE-3211-96E9-FC6EFC9AEE2C.dita"><apiname>TXmlEngSerializer</apiname></xref> class, as explained
+in the <xref href="GUID-E20C2C98-A294-551B-99CF-BE1DAA6F597E.dita">XML Serialisation
+Tutorial</xref>. </p> </li>
+<li id="GUID-2999261C-7049-50A6-A1DF-79CD57A039C4"><p>Search through an XML
+document with XPath, as explained in the <xref href="GUID-92C2317A-57B8-558E-984B-B10FD0404981.dita">XPath
+Tutorial</xref>. </p> </li>
+<li id="GUID-D527989F-D3D8-50B5-9191-FBD59FCAC335"><p>Add extension functions
+to XPath, as explained in the <xref href="GUID-49A7E8FD-72DA-5D56-86BE-74AA9AAF7C02.dita">XPath
+Extension Tutorial</xref>. </p> </li>
+</ul> </section>
+</conbody><related-links>
+<link href="GUID-F79E4F18-19E2-577E-8409-8B82BD48AC66.dita"><linktext>XML Framework</linktext>
+</link>
+<link href="GUID-33D50AB9-AFA8-521F-8A85-031C24EA7D25.dita"><linktext>libxml2</linktext>
+</link>
</related-links></concept>
\ No newline at end of file