En esta página

QXmlStreamReader Class

La clase QXmlStreamReader ofrece un analizador rápido para leer documentos XML 1.0 bien formados a través de una sencilla API de flujo de datos. Más información...

Encabezado: #include <QXmlStreamReader>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core

Nota: Todas las funciones de esta clase son reentrantes.

Tipos públicos

enum Error { NoError, CustomError, NotWellFormedError, PrematureEndOfDocumentError, UnexpectedElementError }
enum ReadElementTextBehaviour { ErrorOnUnexpectedElement, IncludeChildElements, SkipChildElements }
enum TokenType { NoToken, Invalid, StartDocument, EndDocument, StartElement, …, ProcessingInstruction }

Propiedades

Funciones públicas

QXmlStreamReader()
QXmlStreamReader(QAnyStringView data)
QXmlStreamReader(QIODevice *device)
QXmlStreamReader(const QByteArray &data)
~QXmlStreamReader()
void addData(QAnyStringView data)
void addData(const QByteArray &data)
void addExtraNamespaceDeclaration(const QXmlStreamNamespaceDeclaration &extraNamespaceDeclaration)
void addExtraNamespaceDeclarations(const QXmlStreamNamespaceDeclarations &extraNamespaceDeclarations)
bool atEnd() const
QXmlStreamAttributes attributes() const
qint64 characterOffset() const
void clear()
qint64 columnNumber() const
QIODevice *device() const
QStringView documentEncoding() const
QStringView documentVersion() const
QStringView dtdName() const
QStringView dtdPublicId() const
QStringView dtdSystemId() const
QXmlStreamEntityDeclarations entityDeclarations() const
int entityExpansionLimit() const
QXmlStreamEntityResolver *entityResolver() const
QXmlStreamReader::Error error() const
QString errorString() const
bool hasError() const
(since 6.6) bool hasStandaloneDeclaration() const
bool isCDATA() const
bool isCharacters() const
bool isComment() const
bool isDTD() const
bool isEndDocument() const
bool isEndElement() const
bool isEntityReference() const
bool isProcessingInstruction() const
bool isStandaloneDocument() const
bool isStartDocument() const
bool isStartElement() const
bool isWhitespace() const
qint64 lineNumber() const
QStringView name() const
QXmlStreamNamespaceDeclarations namespaceDeclarations() const
bool namespaceProcessing() const
QStringView namespaceUri() const
QXmlStreamNotationDeclarations notationDeclarations() const
QStringView prefix() const
QStringView processingInstructionData() const
QStringView processingInstructionTarget() const
QStringView qualifiedName() const
void raiseError(const QString &message = QString())
QString readElementText(QXmlStreamReader::ReadElementTextBehaviour behaviour = ErrorOnUnexpectedElement)
QXmlStreamReader::TokenType readNext()
bool readNextStartElement()
(since 6.10) QString readRawInnerData()
void setDevice(QIODevice *device)
void setEntityExpansionLimit(int limit)
void setEntityResolver(QXmlStreamEntityResolver *resolver)
void setNamespaceProcessing(bool)
void skipCurrentElement()
QStringView text() const
QString tokenString() const
QXmlStreamReader::TokenType tokenType() const

Descripción detallada

QXmlStreamReader proporciona una sencilla API de flujo para analizar documentos XML 1.0 bien formados. Es una alternativa a la carga previa del XML completo en un árbol DOM (véase QDomDocument). QXmlStreamReader lee datos bien desde un objeto ` QIODevice ` (véase setDevice()), bien desde un objeto ` QByteArray ` sin procesar (véase addData()).

Nota: QXmlStreamReader solo admite la versión 1.0 de XML. Los documentos que declaren cualquier otra versión, como «1.1», provocarán un error de análisis.

Qt proporciona QXmlStreamWriter para escribir XML.

El concepto básico de un lector de flujo consiste en presentar un documento XML como un flujo de tokens, de forma similar a SAX. La principal diferencia entre QXmlStreamReader y SAX radica en cómo se presentan estos tokens XML. Con SAX, la aplicación debe proporcionar controladores (funciones de devolución de llamada) que reciban los denominados eventos XML del analizador cuando este lo considere oportuno. Con QXmlStreamReader, el propio código de la aplicación controla el bucle y extrae los tokens del lector, uno tras otro, a medida que los necesita. Esto se hace llamando a ` readNext()`, donde el lector lee desde el flujo de entrada hasta completar el siguiente token, momento en el que devuelve ` tokenType()`. A continuación, se puede utilizar un conjunto de funciones prácticas, como ` isStartElement()` y ` text()`, para examinar el token y obtener información sobre lo que se ha leído. La gran ventaja de este enfoque de lectura progresiva es la posibilidad de crear con él analizadores sintácticos de descenso recursivo, lo que significa que puedes dividir fácilmente tu código de análisis de XML en diferentes métodos o clases. Esto facilita el seguimiento del estado de la propia aplicación al analizar XML.

Un bucle típico con QXmlStreamReader tiene este aspecto:

QXmlStreamReader xml;
//...
while (!xml.atEnd()) {
    xml.readNext();
    //... do processing
}
if (xml.hasError()) {
    //... do error handling
}

QXmlStreamReader es un analizador XML 1.0 sin validación y de lectura única para documentos bien formados. No procesa entidades analizadas externas ni realiza validación DTD. Siempre que no se produzca ningún error, la aplicación puede confiar en las siguientes garantías:

  • El contenido XML cumple los criterios del W3C para un XML 1.0 bien formado
  • Las referencias a entidades internas se sustituyen por el texto de sustitución correcto.
  • Los atributos se normalizan o se añaden de acuerdo con el subconjunto interno « DTD ».
  • Los tokens se proporcionan en el orden correcto para un documento bien formado.
  • Un token « StartDocument » (si está presente) aparece antes que todos los demás elementos, salvo los comentarios y las instrucciones de procesamiento.
  • Aparece como máximo un elemento DOCTYPE (un token de tipo « DTD »), y, en tal caso, aparece antes que cualquier otro contenido (excepto « StartDocument », los comentarios y las instrucciones de procesamiento).

En concreto, una vez que se detecta cualquier token de tipo StartElement, EndElement, Characters, EntityReference o EndDocument, no se detectarán tokens de tipo StartDocument o DTD. Si aparece uno en el flujo de entrada fuera de orden, se genera un error.

Nota: Los tipos de token Comment y ProcessingInstruction pueden aparecer en cualquier parte del flujo.

Si se produce un error durante el análisis, atEnd() y hasError() devuelven true, y error() devuelve el error que se ha producido. Las funciones errorString(), lineNumber(), columnNumber() y characterOffset() sirven para crear un mensaje de error o advertencia adecuado. Para simplificar el código de la aplicación, QXmlStreamReader incluye un mecanismo raiseError() que permite generar errores personalizados que activan el mismo manejo de errores descrito anteriormente.

El ejemplo «QXmlStream Bookmarks» ilustra cómo utilizar la técnica de descenso recursivo para leer un archivo de marcadores XML (XBEL) con un lector de flujos.

Espacios de nombres

QXmlStream reconoce y resuelve los espacios de nombres XML. Por ejemplo, en el caso de un elemento ` StartElement`, ` namespaceUri()` devuelve el espacio de nombres en el que se encuentra el elemento, y ` name()` devuelve el nombre local del elemento. La combinación de ` namespaceUri ` y el nombre identifica de forma única a un elemento. Si no se ha declarado un prefijo de espacio de nombres en las entidades XML analizadas por el lector, ` namespaceUri ` estará vacío.

Si analizas datos XML que no utilizan espacios de nombres según la especificación XML o que no utilizan espacios de nombres en absoluto, puedes utilizar en su lugar el qualifiedName() del elemento. Un nombre calificado es el prefix() del elemento, seguido de dos puntos y, a continuación, el name() local del elemento, exactamente tal y como aparece el elemento en los datos XML sin procesar. Dado que la correspondencia entre namespaceUri y el prefijo no es ni única ni universal, se debe evitar el uso de qualifiedName() para datos XML que cumplan con los espacios de nombres.

Para analizar documentos independientes que sí utilizan prefijos de espacio de nombres no declarados, puede desactivar por completo el procesamiento de espacios de nombres mediante la propiedad namespaceProcessing.

Análisis incremental

QXmlStreamReader es un analizador incremental. Puede gestionar los casos en los que el documento no se puede analizar de una sola vez porque llega por partes (por ejemplo, desde varios archivos o a través de una conexión de red). Cuando el lector se queda sin datos antes de que se haya analizado el documento completo, informa de un error de « PrematureEndOfDocumentError ». Cuando llegan más datos, ya sea debido a una llamada a ` addData()` o porque hay más datos disponibles a través de la red ` device()`, el lector se recupera del error « PrematureEndOfDocumentError » y continúa analizando los nuevos datos con la siguiente llamada a ` readNext()`.

Por ejemplo, si tu aplicación lee datos de la red utilizando un ` network access manager`, enviarías una llamada ` network request ` al gestor y recibirías a cambio un ` network reply `. Dado que un « QNetworkReply » es un « QIODevice », se conecta su señal « readyRead()» a una ranura personalizada, por ejemplo, « slotReadyRead() » en el fragmento de código que se muestra en la explicación de « QNetworkAccessManager ». En esta ranura, se leen todos los datos disponibles con « readAll()» y se pasan al lector de flujos XML mediante « addData()». A continuación, se llama a la función de análisis personalizada que lee los eventos XML del lector.

Rendimiento y consumo de memoria

QXmlStreamReader está diseñado para ser eficiente en el uso de la memoria, ya que no almacena todo el árbol del documento XML en memoria, sino solo el token actual en el momento en que se reporta. Además, QXmlStreamReader evita las numerosas y pequeñas asignaciones de cadenas que normalmente se requieren para mapear un documento XML a una API práctica y al estilo de Qt. Lo hace devolviendo todos los datos de cadena como QStringView en lugar de objetos reales de tipo QString. Al llamar a toString() sobre cualquiera de esos objetos, se devuelve un objeto real equivalente de tipo QString.

Documentación sobre los tipos de miembros

enum QXmlStreamReader::Error

Esta enumeración especifica diferentes casos de error

ConstanteValorDescripción
QXmlStreamReader::NoError0No se ha producido ningún error.
QXmlStreamReader::CustomError2Se ha generado un error personalizado con ` raiseError()`
QXmlStreamReader::NotWellFormedError3El analizador ha generado internamente un error debido a que el XML leído no estaba bien formado.
QXmlStreamReader::PrematureEndOfDocumentError4El flujo de entrada finalizó antes de que se analizara un documento XML bien formado. Es posible recuperarse de este error si llega más XML al flujo, ya sea llamando a ` addData()` o esperando a que llegue en ` device()`.
QXmlStreamReader::UnexpectedElementError1El analizador se ha encontrado con un elemento o un token diferente a los esperados.

enum QXmlStreamReader::ReadElementTextBehaviour

Esta enumeración especifica los diferentes comportamientos de la función ` readElementText()`.

ConstanteValorDescripción
QXmlStreamReader::ErrorOnUnexpectedElement0Genera un error ` UnexpectedElementError ` y devuelve lo que se ha leído hasta ese momento cuando se encuentra un elemento secundario.
QXmlStreamReader::IncludeChildElements1Incluye de forma recursiva el texto de los elementos secundarios.
QXmlStreamReader::SkipChildElements2Omite los elementos hijos.

enum QXmlStreamReader::TokenType

Esta enumeración especifica el tipo de token que el lector acaba de leer.

ConstanteValorDescripción
QXmlStreamReader::NoToken0El lector aún no ha leído nada.
QXmlStreamReader::Invalid1Se ha producido un error, notificado en ` error()` y ` errorString()`.
QXmlStreamReader::StartDocument2El lector informa del número de versión XML en documentVersion(), y de la codificación tal y como se especifica en el documento XML en documentEncoding(). Si el documento se declara «autónomo», isStandaloneDocument() devuelve true; en caso contrario, devuelve false.
QXmlStreamReader::EndDocument3El lector notifica el final del documento.
QXmlStreamReader::StartElement4El lector señala el inicio de un elemento con namespaceUri() y name(). Los elementos vacíos también se señalan como StartElement, seguidos directamente de EndElement. Se puede llamar a la función de conveniencia readElementText() para concatenar todo el contenido hasta el EndElement correspondiente. Los atributos se señalan en attributes(), y las declaraciones de espacio de nombres en namespaceDeclarations().
QXmlStreamReader::EndElement5El lector señala el final de un elemento con namespaceUri() y name().
QXmlStreamReader::Characters6El lector indica los caracteres mediante text(). Si todos los caracteres son espacios en blanco, isWhitespace() devuelve true. Si los caracteres proceden de una sección CDATA, isCDATA() devuelve true.
QXmlStreamReader::Comment7El lector informa de un comentario en text().
QXmlStreamReader::DTD8El lector informa de una DTD en text(), de declaraciones de notación en notationDeclarations() y de declaraciones de entidades en entityDeclarations(). Los detalles de la declaración de la DTD se indican en dtdName(), dtdPublicId() y dtdSystemId().
QXmlStreamReader::EntityReference9El lector señala una referencia de entidad que no se ha podido resolver. El nombre de la referencia se indica en name(), y el texto de sustitución en text().
QXmlStreamReader::ProcessingInstruction10El lector notifica una instrucción de procesamiento en processingInstructionTarget() y processingInstructionData().

Documentación de propiedades

namespaceProcessing : bool

Esta propiedad contiene el indicador de procesamiento de espacios de nombres del lector de flujos.

Esta propiedad controla si el lector de flujos procesa o no los espacios de nombres. Si está habilitada, el lector procesa los espacios de nombres; en caso contrario, no lo hace.

De forma predeterminada, el procesamiento de espacios de nombres está habilitado.

Funciones de acceso:

bool namespaceProcessing() const
void setNamespaceProcessing(bool)

Documentación de funciones de miembro

QXmlStreamReader::QXmlStreamReader()

Crea un lector de flujo.

Véase también setDevice() y addData().

[explicit] QXmlStreamReader::QXmlStreamReader(QAnyStringView data)

Crea un nuevo lector de flujo que lee desde data.

Nota: En las versiones de Qt anteriores a la 6.5, este constructor estaba sobrecargado para QString y const char*.

Véase también addData(), clear() y setDevice().

[explicit] QXmlStreamReader::QXmlStreamReader(QIODevice *device)

Crea un nuevo lector de flujo que lee desde device.

Véase también setDevice() y clear().

[explicit] QXmlStreamReader::QXmlStreamReader(const QByteArray &data)

Crea un nuevo lector de flujo que lee desde data.

Esta es una función sobrecargada.

Véase también addData(), clear() y setDevice().

[noexcept] QXmlStreamReader::~QXmlStreamReader()

Desconcierta al lector.

void QXmlStreamReader::addData(QAnyStringView data)

Añade más data para que el lector lo lea. Esta función no hace nada si el lector tiene un device().

Nota: En las versiones de Qt anteriores a la 6.5, esta función estaba sobrecargada para QString y const char*.

Véase también readNext() y clear().

void QXmlStreamReader::addData(const QByteArray &data)

Añade más data para que el lector pueda leerlo. Esta función no hace nada si el lector tiene un device().

Se trata de una función sobrecargada.

Véanse también readNext() y clear().

void QXmlStreamReader::addExtraNamespaceDeclaration(const QXmlStreamNamespaceDeclaration &extraNamespaceDeclaration)

Añade un ` extraNamespaceDeclaration`. La declaración será válida para los elementos hijos del elemento actual o —en caso de que la función se llame antes de que se haya leído ningún elemento— para todo el documento XML.

Véase también namespaceDeclarations(), addExtraNamespaceDeclarations() y setNamespaceProcessing().

void QXmlStreamReader::addExtraNamespaceDeclarations(const QXmlStreamNamespaceDeclarations &extraNamespaceDeclarations)

Añade un vector de declaraciones especificadas en extraNamespaceDeclarations.

Véase también namespaceDeclarations() y addExtraNamespaceDeclaration().

bool QXmlStreamReader::atEnd() const

Devuelve ` true ` si el lector ha llegado al final del documento XML, o si se ha producido un ` error()` y se ha interrumpido la lectura. En caso contrario, devuelve ` false`.

Cuando atEnd() y hasError() devuelven true y error() devuelve PrematureEndOfDocumentError, significa que el XML ha sido válido hasta ese momento, pero que aún no se ha analizado un documento XML completo. El siguiente fragmento de XML se puede añadir con ` addData()` si el XML se está leyendo desde un ` QByteArray`, o bien esperando a que lleguen más datos si el XML se está leyendo desde un ` QIODevice`. En cualquier caso, `atEnd()` devolverá «false» una vez que haya más datos disponibles.

Véanse también hasError(), error(), device() y QIODevice::atEnd().

QXmlStreamAttributes QXmlStreamReader::attributes() const

Devuelve los atributos de un ` StartElement`.

qint64 QXmlStreamReader::characterOffset() const

Devuelve el índice de carácter actual, empezando por 0.

Véase también lineNumber() y columnNumber().

void QXmlStreamReader::clear()

Elimina cualquier device() o datos del lector y restablece su estado interno al estado inicial.

Véase también addData().

qint64 QXmlStreamReader::columnNumber() const

Devuelve el número de columna actual, empezando por 0.

Véase también lineNumber() y characterOffset().

QIODevice *QXmlStreamReader::device() const

Devuelve el dispositivo actual asociado a QXmlStreamReader, o nullptr si no se ha asignado ningún dispositivo.

Véase también setDevice().

QStringView QXmlStreamReader::documentEncoding() const

Si el parámetro « tokenType()» es « StartDocument », esta función devuelve la cadena de codificación tal y como se especifica en la declaración XML. En caso contrario, devuelve una cadena vacía.

QStringView QXmlStreamReader::documentVersion() const

Si el parámetro ` tokenType()` es ` StartDocument`, esta función devuelve la cadena de versión tal y como se especifica en la declaración XML. En caso contrario, devuelve una cadena vacía.

QStringView QXmlStreamReader::dtdName() const

Si el objeto « tokenType()» es « DTD », esta función devuelve el nombre de la DTD. En caso contrario, devuelve una cadena vacía.

QStringView QXmlStreamReader::dtdPublicId() const

Si la función « tokenType()» es « DTD », esta función devuelve el identificador público de la DTD. En caso contrario, devuelve una cadena vacía.

QStringView QXmlStreamReader::dtdSystemId() const

Si el parámetro « tokenType()» es « DTD », esta función devuelve el identificador de sistema de la DTD. En caso contrario, devuelve una cadena vacía.

QXmlStreamEntityDeclarations QXmlStreamReader::entityDeclarations() const

Si el ` tokenType()` es ` DTD`, esta función devuelve las declaraciones de entidades (externas) sin analizar de la DTD. En caso contrario, se devuelve un vector vacío.

La clase ` QXmlStreamEntityDeclarations ` se define como un ` QList ` de ` QXmlStreamEntityDeclaration`.

int QXmlStreamReader::entityExpansionLimit() const

Devuelve el número máximo de caracteres hasta el que puede expandirse una sola entidad. Si una entidad se expande más allá del límite establecido, el documento no se considera bien formado.

Véase también setEntityExpansionLimit.

QXmlStreamEntityResolver *QXmlStreamReader::entityResolver() const

Devuelve el resolutor de entidades o, en caso de que no exista, un objeto ` nullptr `.

Véase también setEntityResolver().

QXmlStreamReader::Error QXmlStreamReader::error() const

Devuelve el tipo del error actual o « NoError » si no se ha producido ningún error.

Véase también errorString() y raiseError().

QString QXmlStreamReader::errorString() const

Devuelve el mensaje de error que se estableció con raiseError().

Véanse también error(), lineNumber(), columnNumber() y characterOffset().

bool QXmlStreamReader::hasError() const

Devuelve « true » si se ha producido un error; en caso contrario, devuelve « false ».

Véanse también errorString() y error().

[since 6.6] bool QXmlStreamReader::hasStandaloneDeclaration() const

Devuelve « true » si este documento tiene una declaración explícita de «standalone» (puede ser «yes» o «no»); en caso contrario, devuelve « false »;

Si no se ha analizado ninguna declaración XML, esta función devuelve « false ».

Esta función se introdujo en Qt 6.6.

Véase también isStandaloneDocument().

bool QXmlStreamReader::isCDATA() const

Devuelve « true » si el lector detecta caracteres procedentes de una sección CDATA; en caso contrario, devuelve « false ».

Véase también isCharacters() y text().

bool QXmlStreamReader::isCharacters() const

Devuelve ` true ` si ` tokenType()` es igual a ` Characters`; en caso contrario, devuelve ` false`.

Véase también isWhitespace() y isCDATA().

bool QXmlStreamReader::isComment() const

Devuelve ` true ` si ` tokenType()` es igual a ` Comment`; en caso contrario, devuelve ` false`.

bool QXmlStreamReader::isDTD() const

Devuelve ` true ` si ` tokenType()` es igual a ` DTD`; en caso contrario, devuelve ` false`.

bool QXmlStreamReader::isEndDocument() const

Devuelve ` true ` si ` tokenType()` es igual a ` EndDocument`; en caso contrario, devuelve ` false`.

bool QXmlStreamReader::isEndElement() const

Devuelve « true » si « tokenType()» es igual a « EndElement »; en caso contrario, devuelve « false ».

bool QXmlStreamReader::isEntityReference() const

Devuelve ` true ` si ` tokenType()` es igual a ` EntityReference`; en caso contrario, devuelve ` false`.

bool QXmlStreamReader::isProcessingInstruction() const

Devuelve ` true ` si ` tokenType()` es igual a ` ProcessingInstruction`; en caso contrario, devuelve ` false`.

bool QXmlStreamReader::isStandaloneDocument() const

Devuelve « true » si este documento se ha declarado como independiente en la declaración XML; en caso contrario, devuelve « false ».

Si no se ha analizado ninguna declaración XML, esta función devuelve false.

Véase también hasStandaloneDeclaration().

bool QXmlStreamReader::isStartDocument() const

Devuelve ` true ` si ` tokenType()` es igual a ` StartDocument`; en caso contrario, devuelve ` false`.

bool QXmlStreamReader::isStartElement() const

Devuelve « true » si « tokenType()» es igual a « StartElement »; en caso contrario, devuelve « false ».

bool QXmlStreamReader::isWhitespace() const

Devuelve « true » si el lector detecta caracteres que solo consisten en espacios en blanco; en caso contrario, devuelve « false ».

Véase también isCharacters() y text().

qint64 QXmlStreamReader::lineNumber() const

Devuelve el número de línea actual, empezando por 1.

Véase también columnNumber() y characterOffset().

QStringView QXmlStreamReader::name() const

Devuelve el nombre local de un objeto ` StartElement`, ` EndElement` o ` EntityReference`.

Véase también namespaceUri() y qualifiedName().

QXmlStreamNamespaceDeclarations QXmlStreamReader::namespaceDeclarations() const

Si el ` tokenType()` es ` StartElement`, esta función devuelve las declaraciones de espacio de nombres del elemento. En caso contrario, devuelve un vector vacío.

La clase ` QXmlStreamNamespaceDeclarations ` se define como un ` QList ` de ` QXmlStreamNamespaceDeclaration`.

Véase también addExtraNamespaceDeclaration() y addExtraNamespaceDeclarations().

QStringView QXmlStreamReader::namespaceUri() const

Devuelve el namespaceUri de un StartElement o un EndElement.

Véase también name() y qualifiedName().

QXmlStreamNotationDeclarations QXmlStreamReader::notationDeclarations() const

Si el ` tokenType()` es ` DTD`, esta función devuelve las declaraciones de notación de la DTD. En caso contrario, devuelve un vector vacío.

La clase ` QXmlStreamNotationDeclarations ` se define como un ` QList ` de ` QXmlStreamNotationDeclaration`.

QStringView QXmlStreamReader::prefix() const

Devuelve el prefijo de una dirección StartElement o EndElement.

Véase también name() y qualifiedName().

QStringView QXmlStreamReader::processingInstructionData() const

Devuelve los datos de un objeto ` ProcessingInstruction`.

QStringView QXmlStreamReader::processingInstructionTarget() const

Devuelve el destino de un ` ProcessingInstruction`.

QStringView QXmlStreamReader::qualifiedName() const

Devuelve el nombre calificado de un StartElement o EndElement;

Un nombre calificado es el nombre sin formato de un elemento en los datos XML. Se compone del prefijo del espacio de nombres, seguido de dos puntos y, a continuación, del nombre local del elemento. Dado que el prefijo del espacio de nombres no es único (el mismo prefijo puede apuntar a diferentes espacios de nombres y diferentes prefijos pueden apuntar al mismo espacio de nombres), no se debe utilizar qualifiedName(), sino la función resuelta namespaceUri() y el nombre local del atributo name().

Véanse también name(), prefix() y namespaceUri().

void QXmlStreamReader::raiseError(const QString &message = QString())

Genera un error personalizado con un mensaje de error opcional message.

Véase también ` error()` y ` errorString()`.

QString QXmlStreamReader::readElementText(QXmlStreamReader::ReadElementTextBehaviour behaviour = ErrorOnUnexpectedElement)

Función de conveniencia que se debe llamar en caso de que se haya leído un StartElement. Lee hasta el EndElement correspondiente y devuelve todo el texto que hay entre ambos. Si no se produce ningún error, el token actual (véase tokenType()) tras llamar a esta función es EndElement.

La función concatena text() cuando lee los tokens Characters o EntityReference, pero omite ProcessingInstruction y Comment. Si el token actual no es StartElement, se devuelve una cadena vacía.

La excepción ` behaviour ` define lo que ocurre en caso de que se lea cualquier otra cosa antes de llegar a ` EndElement`. La función puede incluir el texto de los elementos hijos (útil, por ejemplo, para HTML), ignorar los elementos hijos o lanzar una excepción ` UnexpectedElementError ` y devolver lo que se ha leído hasta ese momento (por defecto).

QXmlStreamReader::TokenType QXmlStreamReader::readNext()

Lee el siguiente token y devuelve su tipo.

Con una excepción, una vez que readNext() devuelve un error de « error()», no es posible seguir leyendo el flujo XML. En ese caso, atEnd() devuelve « true », hasError() devuelve « true » y esta función devuelve « QXmlStreamReader::Invalid ».

La excepción se produce cuando ` error()` devuelve ` PrematureEndOfDocumentError`. Este error se notifica cuando se alcanza el final de un fragmento de XML que, por lo demás, está bien formado, pero dicho fragmento no representa un documento XML completo. En ese caso, el análisis sintáctico puede reanudarse llamando a addData() para añadir el siguiente fragmento de XML, cuando el flujo se lee desde un QByteArray, o esperando a que lleguen más datos cuando el flujo se lee desde un device().

Véase también tokenType() y tokenString().

bool QXmlStreamReader::readNextStartElement()

Lee hasta el siguiente elemento inicial dentro del elemento actual. Devuelve « true » cuando se alcanza un elemento inicial. Cuando se alcanza el elemento final, o cuando se produce un error, se devuelve «false».

El elemento actual es aquel que coincide con el elemento de inicio analizado más recientemente y para el que aún no se ha alcanzado un elemento de fin coincidente. Cuando el analizador ha llegado al elemento de fin, el elemento actual pasa a ser el elemento padre.

Se trata de una función práctica para cuando solo te interesa analizar elementos XML. El ejemplo «QXmlStream Bookmarks» hace un uso extensivo de esta función.

Véase también readNext().

[since 6.10] QString QXmlStreamReader::readRawInnerData()

Lee y devuelve el contenido XML interno sin procesar del elemento actual. Esta función resulta útil para recuperar todo el contenido incrustado en un elemento, incluidas las etiquetas anidadas, el texto, los comentarios, las instrucciones de procesamiento, las secciones CDATA y otros elementos de marcado, conservando la estructura XML original.

El elemento actual es aquel que coincide con el elemento inicial analizado más recientemente y para el que aún no se ha alcanzado el elemento final correspondiente. Cuando el analizador ha llegado al elemento final, el elemento actual pasa a ser el elemento padre.

Nota: Las referenciasa entidades definidas en la DTD se resuelven durante el análisis y se devuelven como texto sin formato, ya que las declaraciones de la DTD se procesan por separado y no forman parte del contenido del elemento. Solo las cinco entidades XML predefinidas (&lt;, &gt;, &amp;, &apos;, &quot;) se vuelven a escapar en la salida.

Esta función se introdujo en Qt 6.10.

void QXmlStreamReader::setDevice(QIODevice *device)

Establece el dispositivo actual en « device ». Al establecer el dispositivo, la secuencia se restablece a su estado inicial.

Véase también device() y clear().

void QXmlStreamReader::setEntityExpansionLimit(int limit)

Establece el número máximo de caracteres hasta el que se permite que se expanda una entidad individual, según limit. Si una entidad individual se expande más allá del límite establecido, el documento no se considera bien formado.

El límite existe para evitar ataques de denegación de servicio (DoS) al cargar documentos XML desconocidos, en los que la expansión recursiva de entidades podría, de otro modo, agotar toda la memoria disponible.

El valor predeterminado de esta propiedad es 4096 caracteres.

El mínimo es uno (1), para admitir las entidades XML integradas (&lt;, etc.).

Véase también entityExpansionLimit.

void QXmlStreamReader::setEntityResolver(QXmlStreamEntityResolver *resolver)

Convierte ` resolver ` en el nuevo ` entityResolver()`.

El lector de flujo no asume la propiedad del resolutor. Es responsabilidad de quien realiza la llamada asegurarse de que el resolutor sea válido durante todo el tiempo de vida del objeto lector de flujo, o hasta que se establezca otro resolutor o nullptr.

Véase también entityResolver().

void QXmlStreamReader::skipCurrentElement()

Lee hasta el final del elemento actual, omitiendo cualquier nodo hijo. Esta función resulta útil para omitir elementos desconocidos.

El elemento actual es aquel que coincide con el elemento inicial analizado más recientemente y del que aún no se ha alcanzado el elemento final correspondiente. Cuando el analizador ha llegado al elemento final, el elemento actual pasa a ser el elemento padre.

QStringView QXmlStreamReader::text() const

Devuelve el texto de Characters, Comment, DTD o EntityReference.

QString QXmlStreamReader::tokenString() const

Devuelve el token actual del lector como cadena.

Véase también tokenType().

QXmlStreamReader::TokenType QXmlStreamReader::tokenType() const

Devuelve el tipo del token actual.

El token actual también se puede consultar mediante las funciones de conveniencia isStartDocument(), isEndDocument(), isStartElement(), isEndElement(), isCharacters(), isComment(), isDTD(), isEntityReference() y isProcessingInstruction().

Véase también tokenString().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.