XML Streaming

Qt provides two classes for reading and writing XML through a simple streaming API: QXmlStreamReader and QXmlStreamWriter.

A stream reader reports an XML document as a stream of tokens. This differs from SAX as SAX applications provide handlers to receive XML events from the parser whereas the QXmlStreamReader drives the loop, pulling tokens from the reader when they are needed. This pulling approach makes it possible to build recursive descent parsers, allowing XML parsing code to be split into different methods or classes.

QXmlStreamReader is a well-formed XML 1.0 parser that excludes external parsed entities. Hence, data provided by the stream reader adheres to the W3C's criteria for well-formed XML, as long as no error occurs. Otherwise, functions such as atEnd(), error() and hasError() can be used to check and view the errors.

An example of QXmlStreamReader implementation would be the XbelReader in QXmlStream Bookmarks Example, which wraps a QXmlStreamReader. The constructor takes treeWidget as a parameter and the class has Xbel specific functions:

    XbelReader(QTreeWidget *treeWidget);
    ...
    void readXBEL();
    void readTitle(QTreeWidgetItem *item);
    void readSeparator(QTreeWidgetItem *item);
    void readFolder(QTreeWidgetItem *item);
    void readBookmark(QTreeWidgetItem *item);

    QTreeWidgetItem *createChildItem(QTreeWidgetItem *item);

    QXmlStreamReader xml;
    QTreeWidget *treeWidget;
    ...

The read() function accepts a QIODevice and sets it with setDevice(). The raiseError() function is used to display a custom error message, inidicating that the file's version is incorrect.

bool XbelReader::read(QIODevice *device)
{
    xml.setDevice(device);

    if (xml.readNextStartElement()) {
        if (xml.name() == QLatin1String("xbel")
            && xml.attributes().value(versionAttribute()) == QLatin1String("1.0")) {
            readXBEL();
        } else {
            xml.raiseError(QObject::tr("The file is not an XBEL version 1.0 file."));
        }
    }

    return !xml.error();
}

The pendent to QXmlStreamReader is QXmlStreamWriter, which provides an XML writer with a simple streaming API. QXmlStreamWriter operates on a QIODevice and has specialized functions for all XML tokens or events you want to write, such as writeDTD(), writeCharacters(), writeComment() and so on.

To write XML document with QXmlStreamWriter, you start a document with the writeStartDocument() function and end it with writeEndDocument(), which implicitly closes all remaining open tags. Element tags are opened with writeStartDocument() and followed by writeAttribute() or writeAttributes(), element content, and then writeEndDocument(). Also, writeEmptyElement() can be used to write empty elements.

Element content comprises characters, entity references or nested elements. Content can be written with writeCharacters(), a function that also takes care of escaping all forbidden characters and character sequences, writeEntityReference(), or subsequent calls to writeStartElement().

The XbelWriter class from QXmlStream Bookmarks Example wraps a QXmlStreamWriter. Its writeFile() function illustrates the core functions of QXmlStreamWriter mentioned above:

bool XbelWriter::writeFile(QIODevice *device)
{
    xml.setDevice(device);

    xml.writeStartDocument();
    xml.writeDTD(QStringLiteral("<!DOCTYPE xbel>"));
    xml.writeStartElement(QStringLiteral("xbel"));
    xml.writeAttribute(XbelReader::versionAttribute(), QStringLiteral("1.0"));
    for (int i = 0; i < treeWidget->topLevelItemCount(); ++i)
        writeItem(treeWidget->topLevelItem(i));

    xml.writeEndDocument();
    return true;
}