QXmlSimpleReader Class Reference

The QXmlSimpleReader class provides an implementation of a simple XML parser. More...

#include <qxml.h>

Inheritance diagram for QXmlSimpleReader:

Public Functions
QXmlContentHandler *	contentHandler () const
	Reimplemented Function More...
QXmlDeclHandler *	declHandler () const
	Reimplemented Function More...
QXmlDTDHandler *	DTDHandler () const
	Reimplemented Function More...
QXmlEntityResolver *	entityResolver () const
	Reimplemented Function More...
QXmlErrorHandler *	errorHandler () const
	Reimplemented Function More...
bool	feature (const QString &name, bool *ok=0) const
	Reimplemented Function More...
bool	hasFeature (const QString &name) const
	Reimplemented Function More...
bool	hasProperty (const QString &name) const
	Reimplemented Function More...
QXmlLexicalHandler *	lexicalHandler () const
	Reimplemented Function More...
bool	parse (const QXmlInputSource &input)
	Reimplemented Function More...
bool	parse (const QXmlInputSource *input)
	Reads an XML document from input and parses it in one pass (non-incrementally). More...
virtual bool	parse (const QXmlInputSource *input, bool incremental)
	Reads an XML document from input and parses it. More...
virtual bool	parseContinue ()
	Continues incremental parsing, taking input from the QXmlInputSource that was specified with the most recent call to parse(). More...
void *	property (const QString &name, bool *ok=0) const
	Reimplemented Function More...
	QXmlSimpleReader ()
	Constructs a simple XML reader. More...
void	setContentHandler (QXmlContentHandler *handler)
	Reimplemented Function More...
void	setDeclHandler (QXmlDeclHandler *handler)
	Reimplemented Function More...
void	setDTDHandler (QXmlDTDHandler *handler)
	Reimplemented Function More...
void	setEntityResolver (QXmlEntityResolver *handler)
	Reimplemented Function More...
void	setErrorHandler (QXmlErrorHandler *handler)
	Reimplemented Function More...
void	setFeature (const QString &name, bool value)
	Turns on the feature name if enable is true; otherwise turns it off. More...
void	setLexicalHandler (QXmlLexicalHandler *handler)
	Reimplemented Function More...
void	setProperty (const QString &name, void *value)
	Reimplemented Function More...
virtual	~QXmlSimpleReader ()
	Destroys the simple XML reader. More...
Public Functions inherited from QXmlReader
virtual	~QXmlReader ()
	Destroys the reader. More...

Properties
QScopedPointer< QXmlSimpleReaderPrivate >	d_ptr

Friends
class	QXmlSimpleReaderLocator

Detailed Description

The QXmlSimpleReader class provides an implementation of a simple XML parser.

Note

This class or function is not reentrant.

Attention

Module: QtXml

This XML reader is suitable for a wide range of applications. It is able to parse well-formed XML and can report the namespaces of elements to a content handler; however, it does not parse any external entities. For historical reasons, Attribute Value Normalization and End-of-Line Handling as described in the XML 1.0 specification is not performed.

The easiest pattern of use for this class is to create a reader instance, define an input source, specify the handlers to be used by the reader, and parse the data.

For example, we could use a QFile to supply the input. Here, we create a reader, and define an input source to be used by the reader:

        return 1;
    }

    QFile *file = new QFile(argv[1]);

A handler lets us perform actions when the reader encounters certain types of content, or if errors in the input are found. The reader must be told which handler to use for each type of event. For many common applications, we can create a custom handler by subclassing QXmlDefaultHandler, and use this to handle both error and content events:

    QXmlSimpleReader xmlReader;
    QXmlInputSource *source = new QXmlInputSource(file);

If you don't set at least the content and error handlers, the parser will fall back on its default behavior—and will do nothing.

The most convenient way to handle the input is to read it in a single pass using the parse() function with an argument that specifies the input source:

    bool ok = xmlReader.parse(source);

    if (!ok)
        std::cout << "Parsing failed." << std::endl;

If you can't parse the entire input in one go (for example, it is huge, or is being delivered over a network connection), data can be fed to the parser in pieces. This is achieved by telling parse() to work incrementally, and making subsequent calls to the parseContinue() function, until all the data has been processed.

A common way to perform incremental parsing is to connect the readyRead() signal of a network reply a slot, and handle the incoming data there. See QNetworkAccessManager.

Aspects of the parsing behavior can be adapted using setFeature() and setProperty().

xmlReader.setFeature("http://xml.org/sax/features/namespace-prefixes", true);

QXmlSimpleReader is not reentrant. If you want to use the class in threaded code, lock the code using QXmlSimpleReader with a locking mechanism, such as a QMutex.

Definition at line 241 of file qxml.h.

Constructors and Destructors

QXmlSimpleReader()

QXmlSimpleReader::QXmlSimpleReader

(

)

Constructs a simple XML reader.

Definition at line 3446 of file qxml.cpp.

    : d_ptr(new QXmlSimpleReaderPrivate(this))
{
}

~QXmlSimpleReader()

QXmlSimpleReader::~QXmlSimpleReader ( )

virtual

Destroys the simple XML reader.

Definition at line 3454 of file qxml.cpp.

{
}

Functions

contentHandler()

QXmlContentHandler * QXmlSimpleReader::contentHandler ( ) const

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3620 of file qxml.cpp.

{
    const QXmlSimpleReaderPrivate *d = d_func();
    return d->contentHnd;
}

declHandler()

QXmlDeclHandler * QXmlSimpleReader::declHandler ( ) const

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3674 of file qxml.cpp.

{
    const QXmlSimpleReaderPrivate *d = d_func();
    return d->declHnd;
}

DTDHandler()

QXmlDTDHandler * QXmlSimpleReader::DTDHandler ( ) const

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3602 of file qxml.cpp.

{
    const QXmlSimpleReaderPrivate *d = d_func();
    return d->dtdHnd;
}

entityResolver()

QXmlEntityResolver * QXmlSimpleReader::entityResolver ( ) const

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3584 of file qxml.cpp.

{
    const QXmlSimpleReaderPrivate *d = d_func();
    return d->entityRes;
}

errorHandler()

QXmlErrorHandler * QXmlSimpleReader::errorHandler ( ) const

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3638 of file qxml.cpp.

{
    const QXmlSimpleReaderPrivate *d = d_func();
    return d->errorHnd;
}

feature()

bool QXmlSimpleReader::feature ( const QString &  name, bool *  ok = 0  ) const

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3461 of file qxml.cpp.

{
    const QXmlSimpleReaderPrivate *d = d_func();

    // Qt5 ###: Change these strings to qt.nokia.com
    if (ok != 0)
        *ok = true;
    if (name == QLatin1String("http://xml.org/sax/features/namespaces")) {
        return d->useNamespaces;
    } else if (name == QLatin1String("http://xml.org/sax/features/namespace-prefixes")) {
        return d->useNamespacePrefixes;
    } else if (name == QLatin1String("http://trolltech.com/xml/features/report-whitespace-only-CharData")) { // Shouldn't change in Qt 4
        return d->reportWhitespaceCharData;
    } else if (name == QLatin1String("http://trolltech.com/xml/features/report-start-end-entity")) { // Shouldn't change in Qt 4
        return d->reportEntities;
    } else {
        qWarning("Unknown feature %s", name.toLatin1().data());
        if (ok != 0)
            *ok = false;
    }
    return false;
}

hasFeature()

bool QXmlSimpleReader::hasFeature ( const QString &  name ) const

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3536 of file qxml.cpp.

{
    // Qt5 ###: Change these strings to qt.nokia.com
    if (name == QLatin1String("http://xml.org/sax/features/namespaces")
        || name == QLatin1String("http://xml.org/sax/features/namespace-prefixes")
        || name == QLatin1String("http://trolltech.com/xml/features/report-whitespace-only-CharData") // Shouldn't change in Qt 4
        || name == QLatin1String("http://trolltech.com/xml/features/report-start-end-entity")) { // Shouldn't change in Qt 4
        return true;
    } else {
        return false;
    }
}

hasProperty()

bool QXmlSimpleReader::hasProperty ( const QString &  name ) const

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3567 of file qxml.cpp.

{
    return false;
}

lexicalHandler()

QXmlLexicalHandler * QXmlSimpleReader::lexicalHandler ( ) const

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3656 of file qxml.cpp.

{
    const QXmlSimpleReaderPrivate *d = d_func();
    return d->lexicalHnd;
}

parse() [1/3]

bool QXmlSimpleReader::parse ( const QXmlInputSource &  input )

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3685 of file qxml.cpp.

Referenced by parse().

{
    return parse(&input, false);
}

parse() [2/3]

bool QXmlSimpleReader::parse ( const QXmlInputSource *  input )

virtual

Reads an XML document from input and parses it in one pass (non-incrementally).

Returns true if the parsing was successful; otherwise returns false.

Implements QXmlReader.

Definition at line 3694 of file qxml.cpp.

{
    return parse(input, false);
}

parse() [3/3]

bool QXmlSimpleReader::parse ( const QXmlInputSource *  input, bool  incremental  )

virtual

Reads an XML document from input and parses it.

Returns true if the parsing is completed successfully; otherwise returns false, indicating that an error occurred.

If incremental is false, this function will return false if the XML file is not read completely. The parsing cannot be continued in this case.

If incremental is true, the parser does not return false if it reaches the end of the input before reaching the end of the XML file. Instead, it stores the state of the parser so that parsing can be continued later when more data is available. In such a case, you can use the function parseContinue() to continue with parsing. This class stores a pointer to the input source input and the parseContinue() function tries to read from that input source. Therefore, you should not delete the input source input until you no longer need to call parseContinue().

If this function is called with incremental set to true while an incremental parse is in progress, a new parsing session will be started, and the previous session will be lost.

See also

parseContinue(), QTcpSocket

Definition at line 3724 of file qxml.cpp.

{
    Q_D(QXmlSimpleReader);

    d->literalEntitySizes.clear();
    d->referencesToOtherEntities.clear();
    d->expandedSizes.clear();

    if (incremental) {
        d->initIncrementalParsing();
    } else {
        delete d->parseStack;
        d->parseStack = 0;
    }
    d->init(input);

    // call the handler
    if (d->contentHnd) {
        d->contentHnd->setDocumentLocator(d->locator.data());
        if (!d->contentHnd->startDocument()) {
            d->reportParseError(d->contentHnd->errorString());
            d->tags.clear();
            return false;
        }
    }
    qt_xml_skipped_entity_in_content = false;
    return d->parseBeginOrContinue(0, incremental);
}

parseContinue()

bool QXmlSimpleReader::parseContinue ( )

virtual

Continues incremental parsing, taking input from the QXmlInputSource that was specified with the most recent call to parse().

To use this function, you must have called parse() with the incremental argument set to true.

Returns false if a parsing error occurs; otherwise returns true, even if the end of the XML file has not been reached. You can continue parsing at a later stage by calling this function again when there is more data available to parse.

Calling this function when there is no data available in the input source indicates to the reader that the end of the XML file has been reached. If the input supplied up to this point was not well-formed then a parsing error occurs, and false is returned. If the input supplied was well-formed, true is returned. It is important to end the input in this way because it allows you to reuse the reader to parse other XML files.

Calling this function after the end of file has been reached, but without available data will cause false to be returned whether the previous input was well-formed or not.

See also

parse(), QXmlInputSource::data(), QXmlInputSource::next()

Definition at line 3778 of file qxml.cpp.

{
    Q_D(QXmlSimpleReader);
    if (d->parseStack == 0 || d->parseStack->isEmpty())
        return false;
    d->initData();
    int state = d->parseStack->pop().state;
    return d->parseBeginOrContinue(state, true);
}

property()

void * QXmlSimpleReader::property ( const QString &  name, bool *  ok = 0  ) const

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3551 of file qxml.cpp.

{
    if (ok != 0)
        *ok = false;
    return 0;
}

setContentHandler()

void QXmlSimpleReader::setContentHandler ( QXmlContentHandler *  handler )

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3611 of file qxml.cpp.

{
    Q_D(QXmlSimpleReader);
    d->contentHnd = handler;
}

setDeclHandler()

void QXmlSimpleReader::setDeclHandler ( QXmlDeclHandler *  handler )

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3665 of file qxml.cpp.

{
    Q_D(QXmlSimpleReader);
    d->declHnd = handler;
}

setDTDHandler()

void QXmlSimpleReader::setDTDHandler ( QXmlDTDHandler *  handler )

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3593 of file qxml.cpp.

{
    Q_D(QXmlSimpleReader);
    d->dtdHnd = handler;
}

setEntityResolver()

void QXmlSimpleReader::setEntityResolver ( QXmlEntityResolver *  handler )

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3575 of file qxml.cpp.

{
    Q_D(QXmlSimpleReader);
    d->entityRes = handler;
}

setErrorHandler()

void QXmlSimpleReader::setErrorHandler ( QXmlErrorHandler *  handler )

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3629 of file qxml.cpp.

{
    Q_D(QXmlSimpleReader);
    d->errorHnd = handler;
}

setFeature()

void QXmlSimpleReader::setFeature ( const QString &  name, bool  enable  )

virtual

Turns on the feature name if enable is true; otherwise turns it off.

The name parameter must be one of the following strings:

Feature	Default	Notes
http://xml.org/sax/features/namespaces	true	If enabled, namespaces are reported to the content handler.
http://xml.org/sax/features/namespace-prefixes	false	If enabled, the original prefixed names and attributes used for namespace declarations are reported.
http://trolltech.com/xml/features/report-whitespace-only-CharData	true	If enabled, CharData that consist of only whitespace characters are reported using QXmlContentHandler::characters(). If disabled, whitespace is silently discarded.
http://trolltech.com/xml/features/report-start-end-entity	false	If enabled, the parser reports QXmlContentHandler::startEntity() and QXmlContentHandler::endEntity() events, so character data might be reported in chunks. If disabled, the parser does not report these events, but silently substitutes the entities, and reports the character data in one chunk.

See also

feature(), hasFeature(), {SAX2 Features}

Implements QXmlReader.

Definition at line 3517 of file qxml.cpp.

{
    Q_D(QXmlSimpleReader);
    // Qt5 ###: Change these strings to qt.nokia.com
    if (name == QLatin1String("http://xml.org/sax/features/namespaces")) {
        d->useNamespaces = enable;
    } else if (name == QLatin1String("http://xml.org/sax/features/namespace-prefixes")) {
        d->useNamespacePrefixes = enable;
    } else if (name == QLatin1String("http://trolltech.com/xml/features/report-whitespace-only-CharData")) { // Shouldn't change in Qt 4
        d->reportWhitespaceCharData = enable;
    } else if (name == QLatin1String("http://trolltech.com/xml/features/report-start-end-entity")) { // Shouldn't change in Qt 4
        d->reportEntities = enable;
    } else {
        qWarning("Unknown feature %s", name.toLatin1().data());
    }
}

setLexicalHandler()

void QXmlSimpleReader::setLexicalHandler ( QXmlLexicalHandler *  handler )

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3647 of file qxml.cpp.

{
    Q_D(QXmlSimpleReader);
    d->lexicalHnd = handler;
}

setProperty()

void QXmlSimpleReader::setProperty ( const QString &  name, void *  value  )

virtual

Reimplemented Function

Implements QXmlReader.

Definition at line 3560 of file qxml.cpp.

{
}

Friends and Related Functions

QXmlSimpleReaderLocator

friend class QXmlSimpleReaderLocator

friend

Definition at line 278 of file qxml.h.

Properties

d_ptr

QScopedPointer<QXmlSimpleReaderPrivate> QXmlSimpleReader::d_ptr

private

Definition at line 276 of file qxml.h.

Referenced by QXmlSimpleReaderLocator::columnNumber(), and QXmlSimpleReaderLocator::lineNumber().

---

The documentation for this class was generated from the following files:

• /src/xml/sax/qxml.h
• /src/xml/sax/qxml.cpp