Poco::XML

class ParserEngine

File Information

Library: XML
Package: XML
Header: Poco/XML/ParserEngine.h

Description

This class provides an object-oriented, stream-based, low-level interface to the XML Parser Toolkit (expat). It is strongly recommended, that you use the SAX parser classes (which are based on this class) instead of this class, since they provide a standardized, higher-level interface to the parser.

Inheritance

Direct Base Classes: Locator

All Base Classes: Locator

Member Summary

Member Functions: addEncoding, convert, getColumnNumber, getContentHandler, getDTDHandler, getDeclHandler, getEnablePartialReads, getEncoding, getEntityResolver, getErrorHandler, getExpandInternalEntities, getExternalGeneralEntities, getExternalParameterEntities, getLexicalHandler, getLineNumber, getNamespaceStrategy, getPublicId, getSystemId, handleCharacterData, handleComment, handleDefault, handleEndCdataSection, handleEndDoctypeDecl, handleEndElement, handleEndNamespaceDecl, handleEntityDecl, handleError, handleExternalEntityRef, handleExternalParsedEntityDecl, handleInternalParsedEntityDecl, handleNotationDecl, handleProcessingInstruction, handleSkippedEntity, handleStartCdataSection, handleStartDoctypeDecl, handleStartElement, handleStartNamespaceDecl, handleUnknownEncoding, handleUnparsedEntityDecl, init, locator, parse, parseByteInputStream, parseCharInputStream, parseExternal, parseExternalByteInputStream, parseExternalCharInputStream, popContext, pushContext, readBytes, readChars, resetContext, setBillionLaughsAttackProtectionActivationThreshold, setBillionLaughsAttackProtectionMaximumAmplification, setContentHandler, setDTDHandler, setDeclHandler, setEnablePartialReads, setEncoding, setEntityResolver, setErrorHandler, setExpandInternalEntities, setExternalGeneralEntities, setExternalParameterEntities, setLexicalHandler, setNamespaceStrategy

Inherited Functions: getColumnNumber, getLineNumber, getPublicId, getSystemId

Constructors

ParserEngine

ParserEngine();

Creates the parser engine.

ParserEngine

ParserEngine(
    const XMLString & encoding
);

Creates the parser engine and passes the encoding to the underlying parser.

Destructor

~ParserEngine virtual

~ParserEngine();

Destroys the parser.

Member Functions

addEncoding

void addEncoding(
    const XMLString & name,
    Poco::TextEncoding * pEncoding
);

Adds an encoding to the parser.

getColumnNumber virtual

int getColumnNumber() const;

Return the column number where the current document event ends.

See also: Poco::XML::Locator::getColumnNumber()

getContentHandler inline

ContentHandler * getContentHandler() const;

Return the current content handler.

getDTDHandler inline

DTDHandler * getDTDHandler() const;

Return the current DTD handler.

getDeclHandler inline

DeclHandler * getDeclHandler() const;

Return the current DTD declarations handler.

getEnablePartialReads inline

bool getEnablePartialReads() const;

Returns true if partial reads are enabled (see setEnablePartialReads()), false otherwise.

getEncoding inline

const XMLString & getEncoding() const;

Returns the encoding used by expat.

getEntityResolver inline

EntityResolver * getEntityResolver() const;

Return the current entity resolver.

getErrorHandler inline

ErrorHandler * getErrorHandler() const;

Return the current error handler.

getExpandInternalEntities inline

bool getExpandInternalEntities() const;

Returns true if internal entities will be expanded automatically, which is the default.

getExternalGeneralEntities inline

bool getExternalGeneralEntities() const;

Returns true if external general entities will be processed; false otherwise.

getExternalParameterEntities inline

bool getExternalParameterEntities() const;

Returns true if external parameter entities will be processed; false otherwise.

getLexicalHandler inline

LexicalHandler * getLexicalHandler() const;

Return the current lexical handler.

getLineNumber virtual

int getLineNumber() const;

Return the line number where the current document event ends.

See also: Poco::XML::Locator::getLineNumber()

getNamespaceStrategy inline

NamespaceStrategy * getNamespaceStrategy() const;

Returns the NamespaceStrategy currently in use.

getPublicId virtual

XMLString getPublicId() const;

Return the public identifier for the current document event.

See also: Poco::XML::Locator::getPublicId()

getSystemId virtual

XMLString getSystemId() const;

Return the system identifier for the current document event.

See also: Poco::XML::Locator::getSystemId()

parse

void parse(
    InputSource * pInputSource
);

Parse an XML document from the given InputSource.

parse

void parse(
    const char * pBuffer,
    std::size_t size
);

Parses an XML document from the given buffer.

setBillionLaughsAttackProtectionActivationThreshold

void setBillionLaughsAttackProtectionActivationThreshold(
    Poco::UInt64 activationThresholdBytes
);

Sets number of output bytes (including amplification from entity expansion and reading DTD files) needed to activate protection against Billion Laughs Attacks.

Defaults to 8 MiB.

Requires an underlying Expat version >= 2.4.0.

setBillionLaughsAttackProtectionMaximumAmplification

void setBillionLaughsAttackProtectionMaximumAmplification(
    float maximumAmplificationFactor
);

Sets the maximum tolerated amplification factor for protection against Billion Laughs Attacks.

The amplification factor is calculated as: 

amplification := (direct + indirect) / direct

while parsing, whereas:

  • direct is the number of bytes read from the primary document in parsing and
  • indirect is the number of bytes added by expanding entities and reading of external DTD files, combined.

maximumAmplificationFactor must be non-NaN and greater than or equal to 1.0.

Requires an underlying Expat version >= 2.4.0.

setContentHandler

void setContentHandler(
    ContentHandler * pContentHandler
);

Allow an application to register a content event handler.

setDTDHandler

void setDTDHandler(
    DTDHandler * pDTDHandler
);

Allow an application to register a DTD event handler.

setDeclHandler

void setDeclHandler(
    DeclHandler * pDeclHandler
);

Allow an application to register a DTD declarations event handler.

setEnablePartialReads

void setEnablePartialReads(
    bool flag = true
);

Enable or disable partial reads from the input source.

This is useful for parsing XML from a socket stream for a protocol like XMPP, where basically single elements are read one at a time from the input source's stream, and following elements depend upon responses sent back to the peer.

Normally, the parser always reads blocks of PARSE_BUFFER_SIZE at a time, and blocks until a complete block has been read (or the end of the stream has been reached). This allows for efficient parsing of "complete" XML documents, but fails in a case such as XMPP, where only XML fragments are sent at a time.

setEncoding

void setEncoding(
    const XMLString & encoding
);

Sets the encoding used by expat. The encoding must be set before parsing begins, otherwise it will be ignored.

setEntityResolver

void setEntityResolver(
    EntityResolver * pResolver
);

Allow an application to register an entity resolver.

setErrorHandler

void setErrorHandler(
    ErrorHandler * pErrorHandler
);

Allow an application to register an error event handler.

setExpandInternalEntities

void setExpandInternalEntities(
    bool flag = true
);

Enables/disables expansion of internal entities (enabled by default). If entity expansion is disabled, internal entities are reported via the default handler. Must be set before parsing begins, otherwise it will be ignored.

setExternalGeneralEntities

void setExternalGeneralEntities(
    bool flag = true
);

Enable or disable processing of external general entities.

setExternalParameterEntities

void setExternalParameterEntities(
    bool flag = true
);

Enable or disable processing of external parameter entities.

setLexicalHandler

void setLexicalHandler(
    LexicalHandler * pLexicalHandler
);

Allow an application to register a lexical event handler.

setNamespaceStrategy

void setNamespaceStrategy(
    NamespaceStrategy * pStrategy
);

Sets the NamespaceStrategy used by the parser. The parser takes ownership of the strategy object and deletes it when it's no longer needed. The default is NoNamespacesStrategy.

convert protected static

static int convert(
    void * data,
    const char * s
);

handleCharacterData protected static

static void handleCharacterData(
    void * userData,
    const XML_Char * s,
    int len
);

handleComment protected static

static void handleComment(
    void * userData,
    const XML_Char * data
);

handleDefault protected static

static void handleDefault(
    void * userData,
    const XML_Char * s,
    int len
);

handleEndCdataSection protected static

static void handleEndCdataSection(
    void * userData
);

handleEndDoctypeDecl protected static

static void handleEndDoctypeDecl(
    void * userData
);

handleEndElement protected static

static void handleEndElement(
    void * userData,
    const XML_Char * name
);

handleEndNamespaceDecl protected static

static void handleEndNamespaceDecl(
    void * userData,
    const XML_Char * prefix
);

handleEntityDecl protected static

static void handleEntityDecl(
    void * userData,
    const XML_Char * entityName,
    int isParamEntity,
    const XML_Char * value,
    int valueLength,
    const XML_Char * base,
    const XML_Char * systemId,
    const XML_Char * publicId,
    const XML_Char * notationName
);

handleError protected

void handleError(
    int errorNo
);

Throws an XMLException with a message corresponding to the given Expat error code.

handleExternalEntityRef protected static

static int handleExternalEntityRef(
    XML_Parser parser,
    const XML_Char * openEntityNames,
    const XML_Char * base,
    const XML_Char * systemId,
    const XML_Char * publicId
);

handleExternalParsedEntityDecl protected static

static void handleExternalParsedEntityDecl(
    void * userData,
    const XML_Char * entityName,
    const XML_Char * base,
    const XML_Char * systemId,
    const XML_Char * publicId
);

handleInternalParsedEntityDecl protected static

static void handleInternalParsedEntityDecl(
    void * userData,
    const XML_Char * entityName,
    const XML_Char * replacementText,
    int replacementTextLength
);

handleNotationDecl protected static

static void handleNotationDecl(
    void * userData,
    const XML_Char * notationName,
    const XML_Char * base,
    const XML_Char * systemId,
    const XML_Char * publicId
);

handleProcessingInstruction protected static

static void handleProcessingInstruction(
    void * userData,
    const XML_Char * target,
    const XML_Char * data
);

handleSkippedEntity protected static

static void handleSkippedEntity(
    void * userData,
    const XML_Char * entityName,
    int isParameterEntity
);

handleStartCdataSection protected static

static void handleStartCdataSection(
    void * userData
);

handleStartDoctypeDecl protected static

static void handleStartDoctypeDecl(
    void * userData,
    const XML_Char * doctypeName,
    const XML_Char * systemId,
    const XML_Char * publicId,
    int hasInternalSubset
);

handleStartElement protected static

static void handleStartElement(
    void * userData,
    const XML_Char * name,
    const XML_Char * * atts
);

handleStartNamespaceDecl protected static

static void handleStartNamespaceDecl(
    void * userData,
    const XML_Char * prefix,
    const XML_Char * uri
);

handleUnknownEncoding protected static

static int handleUnknownEncoding(
    void * encodingHandlerData,
    const XML_Char * name,
    XML_Encoding * info
);

handleUnparsedEntityDecl protected static

static void handleUnparsedEntityDecl(
    void * userData,
    const XML_Char * entityName,
    const XML_Char * base,
    const XML_Char * systemId,
    const XML_Char * publicId,
    const XML_Char * notationName
);

init protected

void init();

initializes expat

locator protected

const Locator & locator() const;

Returns a locator denoting the current parse location.

parseByteInputStream protected

void parseByteInputStream(
    XMLByteInputStream & istr
);

Parses an entity from the given stream.

parseCharInputStream protected

void parseCharInputStream(
    XMLCharInputStream & istr
);

Parses an entity from the given stream.

parseExternal protected

void parseExternal(
    XML_Parser extParser,
    InputSource * pInputSource
);

Parse an XML document from the given InputSource.

parseExternalByteInputStream protected

void parseExternalByteInputStream(
    XML_Parser extParser,
    XMLByteInputStream & istr
);

Parses an external entity from the given stream, with a separate parser.

parseExternalCharInputStream protected

void parseExternalCharInputStream(
    XML_Parser extParser,
    XMLCharInputStream & istr
);

Parses an external entity from the given stream, with a separate parser.

popContext protected

void popContext();

Pops the top-most entry from the context stack.

pushContext protected

void pushContext(
    XML_Parser parser,
    InputSource * pInputSource
);

Pushes a new entry to the context stack.

readBytes protected

std::streamsize readBytes(
    XMLByteInputStream & istr,
    char * pBuffer,
    std::streamsize bufferSize
);

Reads at most bufferSize bytes from the given stream into the given buffer.

readChars protected

std::streamsize readChars(
    XMLCharInputStream & istr,
    XMLChar * pBuffer,
    std::streamsize bufferSize
);

Reads at most bufferSize chars from the given stream into the given buffer.

resetContext protected

void resetContext();

Resets and clears the context stack.

Securely control IoT edge devices from anywhere   Connect a Device