Namespace Sax
Class CXmlReader

class CXmlReader: virtual public CInterface {
public:
    static const WCHAR m_szNamespaces[];
    static const WCHAR m_szNamespacePrefixes[];
    static const WCHAR m_szValidation[];
    static const WCHAR m_szExternalGeneralEntities[];
    static const WCHAR m_szExternalParameterEntities[];
public:
    CXmlReader();
    virtual ~CXmlReader();
public:
    virtual void SetFeature(
        const WCHAR *pszName, bool bValue) = 0;
    virtual bool GetFeature(const WCHAR *pszName) = 0;
    virtual void SetProperty(
        const WCHAR *pszName, 
        CInterface *pValue) = 0;
    virtual CInterface *GetProperty(const WCHAR *pszName) = 0;
    virtual void SetEntityResolver(CEntityResolver *pResolver) = 0;
    virtual CEntityResolver *GetEntityResolver() = 0;
    virtual void SetDtdHandler(CDtdHandler *pHandler) = 0;
    virtual CDtdHandler *GetDtdHandler() = 0;
    virtual void SetContentHandler(CContentHandler *pHandler) = 0;
    virtual CContentHandler *GetContentHandler() = 0;
    virtual void SetErrorHandler(CErrorHandler *pHandler) = 0;
    virtual CErrorHandler *GetErrorHandler() = 0;
    virtual void Parse(CInputSource *pInput) = 0;
    virtual void Parse(const WCHAR *pszSystemId) = 0;
    virtual bool SetNamespaces(bool bNamespaces) = 0;
    virtual bool GetNamespaces() = 0;
    virtual void SetInputSource(CInputSource *pInputSource) = 0;
    virtual CInputSource *GetInputSource() = 0;
    virtual void Start() = 0;
    };
typedef XInterface<CXmlReader> XXmlReader;

The abstract interface for reading XML documents using callbacks.

This interface allows an application to set and query features and properties in the reader, to register event handlers for document processing, and to initiate a document parse.

All SAX interfaces are assumed to be synchronous: the Parse methods must not return until parsing is complete, and readers must wait for an event-handler callback to return before reporting the next event.

Since:

1.00.00

Version:

1.50.00

Author:

C++ interfaces by Alexey Gokhberg; based on the original SAX2 specification by David Megginson

See Also:

CDtdHandler, CEntityResolver, CContentHandler, CErrorHandler, CInputSource

CXmlReader

CXmlReader();

Constructs the XML reader.

~CXmlReader

virtual ~CXmlReader();

Destroys the XML reader.

SetFeature

virtual void SetFeature(
    const WCHAR *pszName, bool bValue) = 0;

Sets the state of a feature.

The feature name is any fully-qualified URI. It is possible for an XML reader to recognize a feature name but to be unable to set its value; this is especially true in the case of an adapter for a non-SAX reader, which has no way of affecting whether the underlying reader is validating, for example.

All XML Readers are required to support setting http://xml.org/sax/features/namespaces to true and http://xml.org/sax/features/namespace-prefixes to false .

Some feature values may be immutable or mutable only in specific contexts, such as before, during, or after a parse.

Parameters:

pszName - the feature name, which is a fully-qualified URI

bValue - the requested state of the feature ( true or false )

GetFeature

virtual bool GetFeature(const WCHAR *pszName) = 0;

Looks up the value of a feature.

The feature name is any fully-qualified URI. It is possible for an XML reader to recognize a feature name but to be unable to return its value; this is especially true in the case of an adapter for a non-SAX reader, which has no way of knowing whether the underlying reader is performing validation or expanding external entities.

All XML Readers are required to recognize the http://xml.org/sax/features/namespaces and the http://xml.org/sax/features/namespace-prefixes feature names.

Some feature values may be available only in specific contexts, such as before, during, or after a parse.

Implementors are free (and encouraged) to invent their own features, using names built on their own URIs.

Parameters:

pszName - the feature name, which is a fully-qualified URI

Returns:

the current state of the feature ( true or false )

SetProperty

virtual void SetProperty(
    const WCHAR *pszName, 
    CInterface *pValue) = 0;

Sets the value of a property.

The property name is any fully-qualified URI. It is possible for an XML reader to recognize a property name but to be unable to set its value; this is especially true in the case of an adapter for a non-SAX reader.

XML Readers are not required to recognize setting any specific property names, though a core set is provided with SAX2.

Some property values may be immutable or mutable only in specific contexts, such as before, during, or after a parse.

This method is also the standard mechanism for setting extended handlers.

Parameters:

pszName - the property name, which is a fully-qualified URI

pValue - the requested value for the property, which is an interface pointer

GetProperty

virtual CInterface *GetProperty(const WCHAR *pszName) = 0;

Looks up the value of a property.

The property name is any fully-qualified URI. It is possible for an XML reader to recognize a property name but to be unable to return its state; this is especially true in the case of an adapter for a non-SAX reader.

XML Readers are not required to recognize any specific property names, though an initial core set is documented for SAX2.

Some property values may be available only in specific contexts, such as before, during, or after a parse.

Implementors are free (and encouraged) to invent their own properties, using names built on their own URIs.

Parameters:

pszName - the property name, which is a fully-qualified URI

Returns:

the current value of the property, which is an interface pointer

SetEntityResolver

virtual void SetEntityResolver(CEntityResolver *pResolver) = 0;

Allows an application to register an entity resolver.

If the application does not register an entity resolver, the XML reader will perform its own default resolution.

Applications may register a new or different resolver in the middle of a parse, and the SAX reader must begin using the new resolver immediately.

Parameters:

pResolver - the entity resolver

GetEntityResolver

virtual CEntityResolver *GetEntityResolver() = 0;

Gets the current entity resolver.

Returns:

the current entity resolver, or NULL if none has been registered

SetDtdHandler

virtual void SetDtdHandler(CDtdHandler *pHandler) = 0;

Allows an application to register a DTD event handler.

If the application does not register a DTD handler, all DTD events reported by the SAX reader will be silently ignored.

Applications may register a new or different handler in the middle of a parse, and the SAX reader must begin using the new handler immediately.

Parameters:

pHandler - the DTD handler

GetDtdHandler

virtual CDtdHandler *GetDtdHandler() = 0;

Gets the current DTD handler.

Returns:

the current DTD handler, or NULL if none has been registered

SetContentHandler

virtual void SetContentHandler(CContentHandler *pHandler) = 0;

Allows an application to register a content event handler.

If the application does not register a content handler, all content events reported by the SAX reader will be silently ignored.

Applications may register a new or different handler in the middle of a parse, and the SAX reader must begin using the new handler immediately.

Parameters:

pHandler - the content handler

GetContentHandler

virtual CContentHandler *GetContentHandler() = 0;

Gets the current content handler.

Returns:

the current content handler, or NULL if none has been registered

SetErrorHandler

virtual void SetErrorHandler(CErrorHandler *pHandler) = 0;

Allows an application to register an error event handler.

If the application does not register an error handler, all error events reported by the SAX reader will be silently ignored; however, normal processing may not continue. It is highly recommended that all SAX applications implement an error handler to avoid unexpected bugs.

Applications may register a new or different handler in the middle of a parse, and the SAX reader must begin using the new handler immediately.

Parameters:

pHandler - the error handler

GetErrorHandler

virtual CErrorHandler *GetErrorHandler() = 0;

Gets the current error handler.

Returns:

the current error handler, or NULL if none has been registered

Parse

virtual void Parse(CInputSource *pInput) = 0;

Parses an XML document.

The application can use this method to instruct the XML reader to begin parsing an XML document from any valid input source (a character stream, a byte stream, or a URI).

Applications may not invoke this method while a parse is in progress (they should create a new XMLReader instead for each nested XML document). Once a parse is complete, an application may reuse the same XML reader object, possibly with a different input source.

During the parse, the XML reader will provide information about the XML document through the registered event handlers.

This method is synchronous: it will not return until parsing has ended. If a client application wants to terminate parsing early, it should throw an exception.

Parameters:

pInput - the input source for the top-level of the XML document

Parse

virtual void Parse(const WCHAR *pszSystemId) = 0;

Parses an XML document from a system identifier (URI).

This method is a shortcut for the common case of reading a document from a system identifier.

If the system identifier is a URL, it must be fully resolved by the application before it is passed to the reader.

Parameters:

pszSystemId - the system identifier (URI)

SetNamespaces

virtual void SetNamespaces(bool bNamespaces) = 0;

Specifies whether content events generated by the reader provide namespace information.

Parameters:

bNamespaces - true if content events generated by this reader must provide namespace information; false otherwise

GetNamespaces

virtual bool GetNamespaces() = 0;

Tests whether content events generated by the reader provide namespace information.

Returns:

true if content events generated by this reader provide namespace information; false otherwise

SetInputSource

virtual void SetInputSource(CInputSource *pInputSource) = 0;

Sets the input source.

This method is useful when the parsing is started using the Start method.

Parameters:

pInputSource - the input source

GetInputSource

virtual CInputSource *GetInputSource() = 0;

Gets the current input source.

Returns:

the current input source, or NULL if none has been registered

Start

virtual void Start() = 0;

Starts the SAX reader.

When started, the SAX reader will provide information about the XML document through the registered content handler.

This method is synchronous: it will not return until reading has ended. If a client application wants to terminate the reader early, it should throw an exception.

m_szNamespaces

static const WCHAR m_szNamespaces[];

The convenience identifier for the "http://xml.org/sax/features/namespaces" feature name.

This feature controls namespace processing.

m_szNamespacePrefixes

static const WCHAR m_szNamespacePrefixes[];

The convenience identifier for the "http://xml.org/sax/features/namespace-prefixes" feature name.

This feature controls reporting the original prefixed names and attributes used for namespace declarations.

m_szValidation

static const WCHAR m_szValidation[];

The convenience identifier for the "http://xml.org/sax/features/validation" feature name.

This feature controls reporting validation errors (implies external-general-entities and external-parameter-entities ).

m_szExternalGeneralEntities

static const WCHAR m_szExternalGeneralEntities[];

The convenience identifier for the "http://xml.org/sax/features/external-general-entities" feature name.

This feature controls inclusion of external general (text) entities.

m_szExternalParameterEntities

static const WCHAR m_szExternalParameterEntities[];

The convenience identifier for the "http://xml.org/sax/features/external-parameter-entities" feature name.

This feature controls inclusion of external parameter entities, including the external DTD subset.