XmlLite Writer Programming Overview
This topic provides an overview of programming with the XmlLite writer. The XmlLite writer provides fast, non-cached, forward-only generation of XML that conforms to the W3C Extensible Markup Language (XML) 1.0 specification and the Namespaces in XML specification.
XmlLite is implemented as a library that you link to and a DLL that implements the XML parser. It is a conventional C++ library—to use it, you include a header that defines the classes. You call methods as appropriate to generate the XML.
Usage Scenarios
The following are some common usage scenarios for IXmlWriter:
-
Serializing an object tree by constructing XML from it. For example, you might construct a PurchaseOrder XML document by walking an object graph (that is, a PurchaseOrder object that includes a LineItems collection).
-
Taking data from multiple sources and creating an XML document from them. For example, you might retrieve data from a database, and then wrap a SOAP envelope around the data.
-
Constructing one XML document using another as a template. For example, you might to read an inventory document and create a new version with prices increased by 10%. Another example would be to read a WordML document that contains templates in the form of {name}, and constructing a dynamically generated word document by replacing the {name} templates.
You Must Use a Class that Implements IStream
The XmlLite writer requires that the programmer pass a stream class to it for writing the XML. When your application calls the CreateXmlWriter method, it passes in an instantiation of a class that implements IStream. You must either use an instantiation of a class that implements the IStream interface, or implement your own class that extends the IStream interface.
Limitations of IXmlWriter
The XmlLite writer helps you to write well-formed XML as specified by the XML 1.0 specification. As an example, it enforces constraints on duplicate attributes and duplicate namespaces (which are prohibited by the W3C XML specification). The writer also helps you create well-formed XML in other ways, such as by automatically writing the closing tags, automatically handling namespace prefixes, writing well-formed comments, and more. However, the writer does not always enforce creation of well-formed XML. As an example, the WriteRaw and WriteRawChars methods allow you to output mal-formed XML.
Namespace Handling
The IXmlWriter maintains a namespace stack corresponding to all the namespaces defined by the current element stack. After you introduce a namespace when writing an element, you can use the same namespace when writing other elements, and the XmlWriter performs the required tasks to write valid XML. For example, if a nested element is in the same namespace as its parent element, XmlWriter does not repeat the namespace declaration.
After a start element has been written and the namespace and the prefix have been implicitly or explicitly defined, the writer does not support redefinition of the same prefix in the context of the current start tag.
In other words, it is an error to write any namespace declarations that conflict with any name (the element name or any attribute name) that has been written in the context of the current start tag.
