All Frameworks  Class Hierarchy  This Framework  Previous  Next  Indexes

XMLParser Class CATSAXHandlerBase

System.IUnknown
  |
  +---System.IDispatch
    |
    +---System.CATBaseUnknown
      |
      +---CATSAXHandlerBase
 

Usage: you can derive this class.


public class CATSAXHandlerBase

Default base class for handlers.

This class implements the default behaviour for four SAX interfaces: CATISAXEntityResolver, CATISAXDTDHandler, CATISAXDocumentHandler, and CATISAXErrorHandler.

Application writers can extend this class when they need to implement only part of an interface; parser writers can instantiate this class to provide default handlers when the application has not supplied its own.

Note that the use of this class is optional.

See also:
CATISAXEntityResolver, CATISAXDTDHandler, CATISAXDocumentHandler, CATISAXErrorHandler


Constructor and Destructor Index


o CATSAXHandlerBase()
Constructor
o ~CATSAXHandlerBase()
Destructor

Method Index


o Characters(CATUnicodeString&)
Receives notification of character data inside an element.
o EndDocument()
Receives notification of the end of the document.
o EndElement(CATUnicodeString&)
Receives notification of the end of an element.
o Error(CATSAXParseException*)
Receives notification of a recoverable parser error.
o FatalError(CATSAXParseException*)
Reports a fatal XML parsing error.
o IgnorableWhiteSpace(CATUnicodeString&)
Receives notification of ignorable whitespace in element content.
o NotationDecl(CATUnicodeString&,CATUnicodeString&,CATUnicodeString&)
Receives notification of a notation declaration event.
o ProcessingInstruction(CATUnicodeString&,CATUnicodeString&)
Receives notification of a processing instruction.
o ResolveEntity(CATUnicodeString&,CATUnicodeString&,CATISAXInputSource_var&)
Allows the application to resolve external entities.
o SetDocumentLocator(CATISAXLocator_var&)
Receives a locator object for document events.
o StartDocument()
Receives notification of the beginning of the document.
o StartElement(CATUnicodeString&,CATISAXAttributeList_var&)
Receives notification of the start of an element.
o UnparsedEntityDecl(CATUnicodeString&,CATUnicodeString&,CATUnicodeString&,CATUnicodeString&)
Receives notification of an unparsed entity declaration event.
o Warning(CATSAXParseException*)
Receives notification of a parser warning.

Constructor and Destructor


o CATSAXHandlerBase
public CATSAXHandlerBase()
Constructor
o ~CATSAXHandlerBase
public virtual ~CATSAXHandlerBase()
Destructor

Methods


o Characters
public virtual HRESULT Characters( const CATUnicodeString& iCharacters)
Receives notification of character data inside an element.

By default, do nothing. Application writers may override this method to take specific actions for each chunk of character data (such as adding the data to a node or buffer, or printing it to a file).

Parameters:
iCharacters
The characters from the XML document.
Errors Returned:
Error Class Error Id Description
CATSAXException XMLParserERR_2000 The method can raise a CATSAXException
See also:
CATISAXDocumentHandler.Characters
o EndDocument
public virtual HRESULT EndDocument()
Receives notification of the end of the document.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the beginning of a document (such as finalising a tree or closing an output file).

Errors Returned:
Error Class Error Id Description
CATSAXException XMLParserERR_2000 The method can raise a CATSAXException
See also:
CATISAXDocumentHandler.EndDocument
o EndElement
public virtual HRESULT EndElement( const CATUnicodeString& iName)
Receives notification of the end of an element.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the end of each element (such as finalising a tree node or writing output to a file).

Parameters:
iName
The element type name.
Errors Returned:
Error Class Error Id Description
CATSAXException XMLParserERR_2000 The method can raise a CATSAXException
See also:
CATISAXDocumentHandler.EndElement
o Error
public virtual HRESULT Error(CATSAXParseException* iException)
Receives notification of a recoverable parser error.

The default implementation does nothing. Application writers may override this method in a subclass to take specific actions for each error, such as inserting the message in a log file or printing it to the console.

Parameters:
iException
The error information encapsulated in a SAX parse exception.
Errors Returned:
Error Class Error Id Description
CATSAXParseException XMLParserERR_2002 The method can raise a CATSAXException
See also:
CATISAXErrorHandler.Warning, CATSAXParseException
o FatalError
public virtual HRESULT FatalError(CATSAXParseException* iException)
Reports a fatal XML parsing error.

The default implementation raises a SAXParseException. Application writers may override this method in a subclass if they need to take specific actions for each fatal error (such as collecting all of the errors into a single report): in any case, the application must stop all regular processing when this method is invoked, since the document is no longer reliable, and the parser may no longer report parsing events.

Parameters:
iException
The error information encapsulated in a SAX parse exception.
Errors Returned:
Error Class Error Id Description
CATSAXParseException XMLParserERR_2002 The method can raise a CATSAXException
See also:
CATISAXErrorHandler.FatalError, CATSAXParseException
o IgnorableWhiteSpace
public virtual HRESULT IgnorableWhiteSpace( const CATUnicodeString& iCharacters)
Receives notification of ignorable whitespace in element content.

By default, do nothing. Application writers may override this method to take specific actions for each chunk of ignorable whitespace (such as adding data to a node or buffer, or printing it to a file).

Parameters:
iCharacters
The characters from the XML document.
Errors Returned:
Error Class Error Id Description
CATSAXException XMLParserERR_2000 The method can raise a CATSAXException
See also:
CATISAXDocumentHandler.IgnorableWhitespace
o NotationDecl
public virtual HRESULT NotationDecl( const CATUnicodeString& iName,
const CATUnicodeString& iPublicId,
const CATUnicodeString& iSystemId)
Receives notification of a notation declaration event.

It is up to the application to record the notation for later reference, if necessary.

If a system identifier is present, and it is a URL, the SAX parser must resolve it fully before passing it to the application.

Parameters:
iName
The notation name.
iPublicId
The notation's public identifier (can be an empty
CATUnicodeString if no public identifier was given).
iSystemId
The notation's system identifier (can be an empty
CATUnicodeString if no system identifier was given).
Errors Returned:
Error Class Error Id Description
CATSAXException XMLParserERR_2000 The method can raise a CATSAXException
See also:
CATISAXDTDHandler.NotationDecl
o ProcessingInstruction
public virtual HRESULT ProcessingInstruction( const CATUnicodeString& iTarget,
const CATUnicodeString& iData)
Receives notification of a processing instruction.

The CATISAXParser will invoke this method once for each processing instruction found: note that processing instructions may occur before or after the main document element.

A SAX parser should never report an XML declaration (XML 1.0, section 2.8) or a text declaration (XML 1.0, section 4.3.1) using this method.

Parameters:
iTarget
The processing instruction target.
iData
The processing instruction data (can be an empty
CATUnicodeString if no processing instruction data was given).
Errors Returned:
Error Class Error Id Description
CATSAXException XMLParserERR_2000 The method can raise a CATSAXException
See also:
CATISAXDocumentHandler.ProcessingInstruction
o ResolveEntity
public virtual HRESULT ResolveEntity( const CATUnicodeString& iPublicId,
const CATUnicodeString& iSystemId,
CATISAXInputSource_var& oInputSource)
Allows the application to resolve external entities.

The CATISAXParser will call this method before opening any external entity except the top-level document entity (including the external DTD subset, external entities referenced within the DTD, and external entities referenced within the document element): the application may request that the parser resolve the entity itself, that it use an alternative URI, or that it use an entirely different input source.

Application writers can use this method to redirect external system identifiers to secure and/or local URIs, to look up public identifiers in a catalogue, or to read an entity from a database or other input source (including, for example, a dialog box).

If the system identifier is a URL, the SAX parser must resolve it fully before reporting it to the application.

Parameters:
iPublicId
The public identifier of the external entity being referenced (can be an empty
CATUnicodeString if no public identifier was given).
iSystemId
The system identifier of the external entity being referenced.
oInputSource
An InputSource object describing the new input source, or NULL to request that the parser open a regular URI connection to the system identifier.
Errors Returned:
Error Class Error Id Description
CATSAXException XMLParserERR_2000 The method can raise a CATSAXException
CATSAXException XMLParserERR_2001 If an I/O error occurs, possibly the result of creating a new CATISAXInputSource the method can raise this error.
See also:
CATISAXEntityResolver.ResolveEntity
o SetDocumentLocator
public virtual HRESULT SetDocumentLocator( const CATISAXLocator_var& iLocator)
Receives a locator object for document events.

By default, do nothing. Application writers may override this method in a subclass if they wish to store the locator for use with other document events.

Parameters:
iLocator
A locator for all SAX document events.
See also:
CATISAXDocumentHandler.SetDocumentLocator, CATISAXLocator
o StartDocument
public virtual HRESULT StartDocument()
Receives notification of the beginning of the document.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the beginning of a document (such as allocating the root node of a tree or creating an output file).

Errors Returned:
Error Class Error Id Description
CATSAXException XMLParserERR_2000 The method can raise a CATSAXException
See also:
CATISAXDocumentHandler.StartDocument
o StartElement
public virtual HRESULT StartElement( const CATUnicodeString& iName,
const CATISAXAttributeList_var& iAttributes)
Receives notification of the start of an element.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the start of each element (such as allocating a new tree node or writing output to a file).

Parameters:
iName
The element type name.
iAttributes
The specified or defaulted attributes.
Errors Returned:
Error Class Error Id Description
CATSAXException XMLParserERR_2000 The method can raise a CATSAXException
See also:
CATISAXDocumentHandler.StartElement
o UnparsedEntityDecl
public virtual HRESULT UnparsedEntityDecl( const CATUnicodeString& iName,
const CATUnicodeString& iPublicId,
const CATUnicodeString& iSystemId,
const CATUnicodeString& iNotationName)
Receives notification of an unparsed entity declaration event.

Note that the notation name corresponds to a notation reported by the NotationDecl event. It is up to the application to record the entity for later reference, if necessary.

If the system identifier is a URL, the parser must resolve it fully before passing it to the application.

Parameters:
iName
The unparsed entity's name.
iPublicId
The entity's public identifier (can be an empty
CATUnicodeString if no public identifier was given).
iSystemId
The entity's system identifier (it must always have one).
iNotationName
name The name of the associated notation.
Errors Returned:
Error Class Error Id Description
CATSAXException XMLParserERR_2000 The method can raise a CATSAXException
See also:
CATISAXDTDHandler.UnparsedEntityDecl
o Warning
public virtual HRESULT Warning(CATSAXParseException* iException)
Receives notification of a parser warning.

The default implementation does nothing. Application writers may override this method in a subclass to take specific actions for each warning, such as inserting the message in a log file or printing it to the console.

Parameters:
iException
The warning information encapsulated in a SAX parse exception.
Errors Returned:
Error Class Error Id Description
CATSAXParseException XMLParserERR_2002 The method can raise a CATSAXException
See also:
CATISAXErrorHandler.Warning, CATSAXParseException

This object is included in the file: CATSAXHandlerBase.h
If needed, your Imakefile.mk should include the module: CATXMLParserItf

Copyright © 2003, Dassault Systèmes. All rights reserved.