# Poco::XML

# class ParserEngine

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

~ParserEngine();

Destroys the parser.

## Member Functions

### addEncoding

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

Adds an encoding to the parser.

### getColumnNumber

int getColumnNumber() const;

Return the column number where the current document event ends.

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

### getContentHandler

ContentHandler * getContentHandler() const;

Return the current content handler.

### getDTDHandler

DTDHandler * getDTDHandler() const;

Return the current DTD handler.

### getDeclHandler

DeclHandler * getDeclHandler() const;

Return the current DTD declarations handler.

### getEnablePartialReads

bool getEnablePartialReads() const;

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

### getEncoding

const XMLString & getEncoding() const;

Returns the encoding used by expat.

### getEntityResolver

EntityResolver * getEntityResolver() const;

Return the current entity resolver.

### getErrorHandler

ErrorHandler * getErrorHandler() const;

Return the current error handler.

### getExpandInternalEntities

bool getExpandInternalEntities() const;

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

### getExternalGeneralEntities

bool getExternalGeneralEntities() const;

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

### getExternalParameterEntities

bool getExternalParameterEntities() const;

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

### getLexicalHandler

LexicalHandler * getLexicalHandler() const;

Return the current lexical handler.

### getLineNumber

int getLineNumber() const;

Return the line number where the current document event ends.

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

### getNamespaceStrategy

NamespaceStrategy * getNamespaceStrategy() const;

Returns the NamespaceStrategy currently in use.

### getPublicId

XMLString getPublicId() const;

Return the public identifier for the current document event.

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

### getSystemId

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

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

### handleCharacterData

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

### handleComment

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

### handleDefault

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

### handleEndCdataSection

static void handleEndCdataSection(
void * userData
);

### handleEndDoctypeDecl

static void handleEndDoctypeDecl(
void * userData
);

### handleEndElement

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

### handleEndNamespaceDecl

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

### handleEntityDecl

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

void handleError(
int errorNo
);

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

### handleExternalEntityRef

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

### handleExternalParsedEntityDecl

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

### handleInternalParsedEntityDecl

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

### handleNotationDecl

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

### handleProcessingInstruction

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

### handleSkippedEntity

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

### handleStartCdataSection

static void handleStartCdataSection(
void * userData
);

### handleStartDoctypeDecl

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

### handleStartElement

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

### handleStartNamespaceDecl

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

### handleUnknownEncoding

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

### handleUnparsedEntityDecl

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

void init();

initializes expat

### locator

const Locator & locator() const;

Returns a locator denoting the current parse location.

### parseByteInputStream

void parseByteInputStream(
XMLByteInputStream & istr
);

Parses an entity from the given stream.

### parseCharInputStream

void parseCharInputStream(
XMLCharInputStream & istr
);

Parses an entity from the given stream.

### parseExternal

void parseExternal(
XML_Parser extParser,
InputSource * pInputSource
);

Parse an XML document from the given InputSource.

### parseExternalByteInputStream

void parseExternalByteInputStream(
XML_Parser extParser,
XMLByteInputStream & istr
);

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

### parseExternalCharInputStream

void parseExternalCharInputStream(
XML_Parser extParser,
XMLCharInputStream & istr
);

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

### popContext

void popContext();

Pops the top-most entry from the context stack.

### pushContext

void pushContext(
XML_Parser parser,
InputSource * pInputSource
);

Pushes a new entry to the context stack.

### readBytes

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

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

### readChars

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

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

### resetContext

void resetContext();

Resets and clears the context stack.