Class Parser

The SAX parser class.

Inheritance

object

DefaultHandler

Parser

Implements

IEntityResolver

IDTDHandler

IContentHandler

IErrorHandler

IScanHandler

IXMLReader

ILexicalHandler

Inherited Members

DefaultHandler.ResolveEntity(string, string)

DefaultHandler.NotationDecl(string, string, string)

DefaultHandler.UnparsedEntityDecl(string, string, string, string)

DefaultHandler.SetDocumentLocator(ILocator)

DefaultHandler.StartDocument()

DefaultHandler.EndDocument()

DefaultHandler.StartPrefixMapping(string, string)

DefaultHandler.EndPrefixMapping(string)

DefaultHandler.StartElement(string, string, string, IAttributes)

DefaultHandler.EndElement(string, string, string)

DefaultHandler.Characters(char[], int, int)

DefaultHandler.IgnorableWhitespace(char[], int, int)

DefaultHandler.ProcessingInstruction(string, string)

DefaultHandler.SkippedEntity(string)

DefaultHandler.Warning(SAXParseException)

DefaultHandler.Error(SAXParseException)

DefaultHandler.FatalError(SAXParseException)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: TagSoup

Assembly: Lucene.Net.Benchmark.dll

Syntax

public class Parser : DefaultHandler, IEntityResolver, IDTDHandler, IContentHandler, IErrorHandler, IScanHandler, IXMLReader, ILexicalHandler

Constructors

Parser()

Creates a new instance of Parser

Declaration

public Parser()

Fields

AUTO_DETECTOR_PROPERTY

Specifies the AutoDetector (for encoding detection) this Parser uses.

Declaration

public const string AUTO_DETECTOR_PROPERTY = "http://www.ccil.org/~cowan/tagsoup/properties/auto-detector"

Field Value

Type	Description
string

BOGONS_EMPTY_FEATURE

A value of true indicates that the parser will give unknown elements a content model of EMPTY; a value of false, a content model of ANY.

Declaration

public const string BOGONS_EMPTY_FEATURE = "http://www.ccil.org/~cowan/tagsoup/features/bogons-empty"

Field Value

Type	Description
string

CDATA_ELEMENTS_FEATURE

A value of "true" indicates that the parser will treat CDATA elements specially. Normally true, since the input is by default HTML.

Declaration

public const string CDATA_ELEMENTS_FEATURE = "http://www.ccil.org/~cowan/tagsoup/features/cdata-elements"

Field Value

Type	Description
string

DEFAULT_ATTRIBUTES_FEATURE

A value of true indicates that the parser will return default attribute values for missing attributes that have default values.

Declaration

public const string DEFAULT_ATTRIBUTES_FEATURE = "http://www.ccil.org/~cowan/tagsoup/features/default-attributes"

Field Value

Type	Description
string

EXTERNAL_GENERAL_ENTITIES_FEATURE

Reports whether this parser processes external general entities (it doe

Declaration

public const string EXTERNAL_GENERAL_ENTITIES_FEATURE = "http://xml.org/sax/features/external-general-entities"

Field Value

Type	Description
string

EXTERNAL_PARAMETER_ENTITIES_FEATURE

Reports whether this parser processes external parameter entities (it doesn't).

Declaration

public const string EXTERNAL_PARAMETER_ENTITIES_FEATURE = "http://xml.org/sax/features/external-parameter-entities"

Field Value

Type	Description
string

IGNORABLE_WHITESPACE_FEATURE

A value of "true" indicates that the parser will transmit whitespace in element-only content via the SAX ignorableWhitespace callback. Normally this is not done, because HTML is an SGML application and SGML suppresses such whitespace.

Declaration

public const string IGNORABLE_WHITESPACE_FEATURE = "http://www.ccil.org/~cowan/tagsoup/features/ignorable-whitespace"

Field Value

Type	Description
string

IGNORE_BOGONS_FEATURE

A value of true indicates that the parser will ignore unknown elements.

Declaration

public const string IGNORE_BOGONS_FEATURE = "http://www.ccil.org/~cowan/tagsoup/features/ignore-bogons"

Field Value

Type	Description
string

IS_STANDALONE_FEATURE

May be examined only during a parse, after the startDocument() callback has been completed; read-only. The value is true if the document specified standalone="yes" in its XML declaration, and otherwise is false. (It's always false.)

Declaration

public const string IS_STANDALONE_FEATURE = "http://xml.org/sax/features/is-standalone"

Field Value

Type	Description
string

LEXICAL_HANDLER_PARAMETER_ENTITIES_FEATURE

A value of "true" indicates that the LexicalHandler will report the beginning and end of parameter entities (it won't).

Declaration

public const string LEXICAL_HANDLER_PARAMETER_ENTITIES_FEATURE = "http://xml.org/sax/features/lexical-handler/parameter-entities"

Field Value

Type	Description
string

LEXICAL_HANDLER_PROPERTY

Used to see some syntax events that are essential in some applications: comments, CDATA delimiters, selected general entity inclusions, and the start and end of the DTD (and declaration of document element name). The Object must implement ILexicalHandler

Declaration

public const string LEXICAL_HANDLER_PROPERTY = "http://xml.org/sax/properties/lexical-handler"

Field Value

Type	Description
string

NAMESPACES_FEATURE

A value of "true" indicates namespace URIs and unprefixed local names for element and attribute names will be available.

Declaration

public const string NAMESPACES_FEATURE = "http://xml.org/sax/features/namespaces"

Field Value

Type	Description
string

NAMESPACE_PREFIXES_FEATURE

A value of "true" indicates that XML qualified names (with prefixes) and attributes (including xmlns* attributes) will be available. We don't support this value.

Declaration

public const string NAMESPACE_PREFIXES_FEATURE = "http://xml.org/sax/features/namespace-prefixes"

Field Value

Type	Description
string

RESOLVE_DTD_URIS_FEATURE

A value of "true" indicates that system IDs in declarations will be absolutized (relative to their base URIs) before reporting. (This returns true but doesn't actually do anything.)

Declaration

public const string RESOLVE_DTD_URIS_FEATURE = "http://xml.org/sax/features/resolve-dtd-uris"

Field Value

Type	Description
string

RESTART_ELEMENTS_FEATURE

A value of true indicates that the parser will attempt to restart the restartable elements.

Declaration

public const string RESTART_ELEMENTS_FEATURE = "http://www.ccil.org/~cowan/tagsoup/features/restart-elements"

Field Value

Type	Description
string

ROOT_BOGONS_FEATURE

A value of true indicates that the parser will allow unknown elements to be the root element.

Declaration

public const string ROOT_BOGONS_FEATURE = "http://www.ccil.org/~cowan/tagsoup/features/root-bogons"

Field Value

Type	Description
string

SCANNER_PROPERTY

Specifies the Scanner object this Parser uses.

Declaration

public const string SCANNER_PROPERTY = "http://www.ccil.org/~cowan/tagsoup/properties/scanner"

Field Value

Type	Description
string

SCHEMA_PROPERTY

Specifies the Schema object this Parser uses.

Declaration

public const string SCHEMA_PROPERTY = "http://www.ccil.org/~cowan/tagsoup/properties/schema"

Field Value

Type	Description
string

STRING_INTERNING_FEATURE

Has a value of "true" if all XML names (for elements, prefixes, attributes, entities, notations, and local names), as well as Namespace URIs, will have been interned using Intern(string). This supports fast testing of equality/inequality against string constants, rather than forcing slower calls to Equals(object). (We always intern.)

Declaration

public const string STRING_INTERNING_FEATURE = "http://xml.org/sax/features/string-interning"

Field Value

Type	Description
string

TRANSLATE_COLONS_FEATURE

A value of true indicates that the parser will translate colons into underscores in names.

Declaration

public const string TRANSLATE_COLONS_FEATURE = "http://www.ccil.org/~cowan/tagsoup/features/translate-colons"

Field Value

Type	Description
string

UNICODE_NORMALIZATION_CHECKING_FEATURE

Controls whether the parser reports Unicode normalization errors as described in section 2.13 and Appendix B of the XML 1.1 Recommendation. (We don't normalize.)

Declaration

public const string UNICODE_NORMALIZATION_CHECKING_FEATURE = "http://xml.org/sax/features/unicode-normalization-checking"

Field Value

Type	Description
string

USE_ATTRIBUTES2_FEATURE

Returns "true" if the Attributes objects passed by this parser in StartElement(string, string, string, IAttributes) implement the IAttributes2 interface. (They don't.)

Declaration

public const string USE_ATTRIBUTES2_FEATURE = "http://xml.org/sax/features/use-attributes2"

Field Value

Type	Description
string

USE_ENTITY_RESOLVER2_FEATURE

Returns "true" if, when setEntityResolver is given an object implementing the IEntityResolver2 interface, those new methods will be used. (They won't be.)

Declaration

public const string USE_ENTITY_RESOLVER2_FEATURE = "http://xml.org/sax/features/use-entity-resolver2"

Field Value

Type	Description
string

USE_LOCATOR2_FEATURE

Returns "true" if the Locator objects passed by this parser parser in SetDocumentLocator(ILocator) implement the ILocator2 interface. (They don't.)

Declaration

public const string USE_LOCATOR2_FEATURE = "http://xml.org/sax/features/use-locator2"

Field Value

Type	Description
string

VALIDATION_FEATURE

Controls whether the parser is reporting all validity errors (We don't report any validity errors.)

Declaration

public const string VALIDATION_FEATURE = "http://xml.org/sax/features/validation"

Field Value

Type	Description
string

XML11_FEATURE

Returns true if the parser supports both XML 1.1 and XML 1.0. (Always false.)

Declaration

public const string XML11_FEATURE = "http://xml.org/sax/features/xml-1.1"

Field Value

Type	Description
string

XMLNS_URIS_FEATURE

Controls whether, when the namespace-prefixes feature is set, the parser treats namespace declaration attributes as being in the http://www.w3.org/2000/xmlns/ namespace. (It doesn't.)

Declaration

public const string XMLNS_URIS_FEATURE = "http://xml.org/sax/features/xmlns-uris"

Field Value

Type	Description
string

Properties

ContentHandler

Gets or Sets a content event handler.

Declaration

public virtual IContentHandler ContentHandler { get; set; }

Property Value

Type	Description
IContentHandler

Remarks

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

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

DTDHandler

Gets or Sets a DTD event handler.

Declaration

public virtual IDTDHandler DTDHandler { get; set; }

Property Value

Type	Description
IDTDHandler

Remarks

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

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

EntityResolver

Gets or Sets an entity resolver.

Declaration

public virtual IEntityResolver EntityResolver { get; set; }

Property Value

Type	Description
IEntityResolver

Remarks

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

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

ErrorHandler

Gets or Sets an error event handler.

Declaration

public virtual IErrorHandler ErrorHandler { get; set; }

Property Value

Type	Description
IErrorHandler

Remarks

If the application does not register an error handler, all error events reported by the SAX parser 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 parser must begin using the new handler immediately.

Methods

Adup(char[], int, int)

Reports an attribute name without a value.

Declaration

public virtual void Adup(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

Aname(char[], int, int)

Reports an attribute name; a value will follow.

Declaration

public virtual void Aname(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

Aval(char[], int, int)

Reports an attribute value.

Declaration

public virtual void Aval(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

CDSect(char[], int, int)

Reports the content of a CDATA section (not a CDATA element)

Declaration

public virtual void CDSect(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

Cmnt(char[], int, int)

Reports a comment.

Declaration

public virtual void Cmnt(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

Comment(char[], int, int)

Report an XML comment anywhere in the document.

This callback will be used for comments inside or outside the document element, including comments in the external DTD subset(if read). Comments in the DTD must be properly nested inside start/endDTD and start/endEntity events(if used).

Declaration

public virtual void Comment(char[] ch, int start, int length)

Parameters

Type	Name	Description
char[]	ch	An array holding the characters in the comment.
int	start	The starting position in the array.
int	length	The number of characters to use from the array.

Exceptions

Type	Condition
SAXException	The application may raise an exception.

Decl(char[], int, int)

Parsing the complete XML Document Type Definition is way too complex, but for many simple cases we can extract something useful from it. doctypedecl ::= '<!DOCTYPE' S Name (S ExternalID)? S? ('[' intSubset ']' S?)? '>' DeclSep ::= PEReference | S intSubset ::= (markupdecl | DeclSep)* markupdecl ::= elementdecl | AttlistDecl | EntityDecl | NotationDecl | PI | Comment ExternalID ::= 'SYSTEM' S SystemLiteral | 'PUBLIC' S PubidLiteral S SystemLiteral

Declaration

public virtual void Decl(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

EOF(char[], int, int)

Reports EOF.

Declaration

public virtual void EOF(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

ETag(char[], int, int)

Reports an end-tag.

Declaration

public virtual void ETag(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

ETagBasic(char[], int, int)

The SAX parser class.

Declaration

public virtual void ETagBasic(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

ETagCdata(char[], int, int)

The SAX parser class.

Declaration

public virtual bool ETagCdata(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

Returns

Type	Description
bool

EndCDATA()

Report the end of a CDATA section.

Declaration

public virtual void EndCDATA()

Exceptions

Type	Condition
SAXException	The application may raise an exception.

See Also

StartCDATA()

EndDTD()

Report the end of DTD declarations.

This method is intended to report the end of the DOCTYPE declaration; if the document has no DOCTYPE declaration, this method will not be invoked.

Declaration

public virtual void EndDTD()

Exceptions

Type	Condition
SAXException	The application may raise an exception.

See Also

StartDTD(string, string, string)

EndEntity(string)

Report the end of an entity.

Declaration

public virtual void EndEntity(string name)

Parameters

Type	Name	Description
string	name	The name of the entity that is ending.

Exceptions

Type	Condition
SAXException	The application may raise an exception.

See Also

StartEntity(string)

Entity(char[], int, int)

Reports an entity reference or character reference.

Declaration

public virtual void Entity(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

GI(char[], int, int)

Reports the general identifier (element type name) of a start-tag.

Declaration

public virtual void GI(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

GetEntity()

Returns the value of the last entity or character reference reported.

Declaration

public virtual int GetEntity()

Returns

Type	Description
int	The value of the last entity or character reference reported.

GetFeature(string)

Look up the value of a feature flag.

Declaration

public virtual bool GetFeature(string name)

Parameters

Type	Name	Description
string	name	The feature name, which is a fully-qualified URI.

Returns

Type	Description
bool	The current value of the feature (true or false).

Remarks

The feature name is any fully-qualified URI. It is possible for an XMLReader to recognize a feature name but temporarily be unable to return its value. Some feature values may be available only in specific contexts, such as before, during, or after a parse. Also, some feature values may not be programmatically accessible. (In the case of an adapter for SAX1 {@link Parser}, there is no implementation-independent way to expose whether the underlying parser is performing validation, expanding external entities, and so forth.)

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

Typical usage is something like this:

XMLReader r = new MySAXDriver();
                        // try to activate validation
try {
   r.SetFeature("http://xml.org/sax/features/validation", true);
} catch (SAXException e) {
   Console.Error.WriteLine("Cannot activate validation."); 
}
                        // register event handlers
r.ContentHandler = new MyContentHandler();
r.ErrorHandler = new MyErrorHandler();
                        // parse the first document
try {
   r.Parse("http://www.foo.com/mydoc.xml");
} catch (IOException e) {
   Console.Error.WriteLine("I/O exception reading XML document");
} catch (SAXException e) {
   Console.Error.WriteLine("XML exception reading document.");
}

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

Exceptions

Type	Condition
SAXNotRecognizedException	If the feature value can't be assigned or retrieved.
SAXNotSupportedException	When the IXMLReader recognizes the feature name but cannot determine its value at this time.

See Also

SetFeature(string, bool)

GetProperty(string)

Look up the value of a property.

Declaration

public virtual object GetProperty(string name)

Parameters

Type	Name	Description
string	name	The property name, which is a fully-qualified URI.

Returns

Type	Description
object	The current value of the property.

Remarks

The property name is any fully-qualified URI. It is possible for an XMLReader to recognize a property name but temporarily be unable to return its value. Some property values may be available only in specific contexts, such as before, during, or after a parse.

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

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

Exceptions

Type	Condition
SAXNotRecognizedException	If the property value can't be assigned or retrieved.
SAXNotSupportedException	When the IXMLReader recognizes the property name but cannot determine its value at this time.

See Also

SetProperty(string, object)

PCDATA(char[], int, int)

Reports character content.

Declaration

public virtual void PCDATA(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

PI(char[], int, int)

Reports the data part of a processing instruction.

Declaration

public virtual void PI(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

PITarget(char[], int, int)

Reports the target part of a processing instruction.

Declaration

public virtual void PITarget(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

Parse(InputSource)

Parse an XML document.

Declaration

public virtual void Parse(InputSource input)

Parameters

Type	Name	Description
InputSource	input	The input source for the top-level of the XML document.

Remarks

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 XMLReader object, possibly with a different input source. Configuration of the IXMLReader object (such as handler bindings and values established for feature flags and properties) is unchanged by completion of a parse, unless the definition of that aspect of the configuration explicitly specifies other behavior. (For example, feature flags or properties exposing characteristics of the document being parsed.)

During the parse, the XMLReader 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.

Exceptions

Type	Condition
SAXException	Any SAX exception, possibly wrapping another exception.
IOException	An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

See Also

InputSource

Parse(string)

EntityResolver

DTDHandler

ContentHandler

ErrorHandler

Parse(string)

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

Declaration

public virtual void Parse(string systemId)

Parameters

Type	Name	Description
string	systemId	The system identifier (URI).

Remarks

This method is a shortcut for the common case of reading a document from a system identifier. It is the exact equivalent of the following:

Parse(new InputSource(systemId));

If the system identifier is a URL, it must be fully resolved

by the application before it is passed to the parser.

Exceptions

Type	Condition
SAXException	Any SAX exception, possibly wrapping another exception.
IOException	An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

STagC(char[], int, int)

Reports the close of a start-tag.

Declaration

public virtual void STagC(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

STagE(char[], int, int)

Reports the close of an empty-tag.

Declaration

public virtual void STagE(char[] buffer, int startIndex, int length)

Parameters

Type	Name	Description
char[]	buffer
int	startIndex
int	length

SetFeature(string, bool)

Set the value of a feature flag.

The feature name is any fully-qualified URI. It is possible for an XMLReader to expose a feature value but to be unable to change the current value. Some feature values may be immutable or mutable only in specific contexts, such as before, during, or after a parse.

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

Declaration

public virtual void SetFeature(string name, bool value)

Parameters

Type	Name	Description
string	name	The feature name, which is a fully-qualified URI.
bool	value	The requested value of the feature (true or false).

Exceptions

Type	Condition
SAXNotRecognizedException	If the feature value can't be assigned or retrieved.
SAXNotSupportedException	When the IXMLReader recognizes the feature name but cannot set the requested value.

See Also

GetFeature(string)

SetProperty(string, object)

Set the value of a property.

Declaration

public virtual void SetProperty(string name, object value)

Parameters

Type	Name	Description
string	name	The property name, which is a fully-qualified URI.
object	value	The requested value for the property.

Remarks

The property name is any fully-qualified URI. It is possible for an IXMLReader to recognize a property name but to be unable to change the current value. Some property values may be immutable or mutable only in specific contexts, such as before, during, or after a parse.

IXMLReaders are not required to recognize setting any specific property names, though a core set is defined by SAX2.

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

Exceptions

Type	Condition
SAXNotRecognizedException	If the property value can't be assigned or retrieved.
SAXNotSupportedException	When the IXMLReader recognizes the property name but cannot set the requested value.

StartCDATA()

Report the start of a CDATA section.

Declaration

public virtual void StartCDATA()

Remarks

The contents of the CDATA section will be reported through the regular Characters(char[], int, int) event; this event is intended only to report the boundary.

Exceptions

Type	Condition
SAXException	The application may raise an exception.

See Also

EndEntity(string)

StartDTD(string, string, string)

Report the start of DTD declarations, if any.

Declaration

public virtual void StartDTD(string name, string publicId, string systemId)

Parameters

Type	Name	Description
string	name	The document type name.
string	publicId	The declared public identifier for the external DTD subset, or null if none was declared.
string	systemId	The declared system identifier for the external DTD subset, or null if none was declared. (Note that this is not resolved against the document base URI.)

Remarks

This method is intended to report the beginning of the DOCTYPE declaration; if the document has no DOCTYPE declaration, this method will not be invoked.

All declarations reported through IDTDHandler or IDeclHandler events must appear between the startDTD and EndDTD() events. Declarations are assumed to belong to the internal DTD subset unless they appear between StartEntity(string) and EndEntity(string) events. Comments and processing instructions from the DTD should also be reported between the StartDTD(string, string, string) and EndDTD() events, in their original order of(logical) occurrence; they are not required to appear in their correct locations relative to IDTDHandler or IDeclHandler events, however.

Note that the start / endDTD events will appear within the start / endDocument events from IContentHandler and before the first StartElement(string, string, string, IAttributes) event.

Exceptions

Type	Condition
SAXException	The application may raise an exception.

StartEntity(string)

Report the beginning of some internal and external XML entities.

Declaration

public virtual void StartEntity(string name)

Parameters

Type	Name	Description
string	name	The name of the entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be "[dtd]".

Remarks

The reporting of parameter entities (including the external DTD subset) is optional, and SAX2 drivers that report LexicalHandler events may not implement it; you can use the http://xml.org/sax/features/lexical-handler/parameter-entities feature to query or control the reporting of parameter entities.

General entities are reported with their regular names, parameter entities have '%' prepended to their names, and the external DTD subset has the pseudo-entity name "[dtd]".

When a SAX2 driver is providing these events, all other events must be properly nested within start/end entity events. There is no additional requirement that events from IDeclHandler or IDTDHandler be properly ordered.

Note that skipped entities will be reported through the SkippedEntity(string) event, which is part of the ContentHandler interface.

Because of the streaming event model that SAX uses, some entity boundaries cannot be reported under any circumstances:

• general entities within attribute values
• parameter entities within declarations

These will be silently expanded, with no indication of where the original entity boundaries were.

Note also that the boundaries of character references (which are not really entities anyway) are not reported.

All start/endEntity events must be properly nested.

Exceptions

Type	Condition
SAXException	The application may raise an exception.

See Also

EndEntity(string)

InternalEntityDecl(string, string)

ExternalEntityDecl(string, string, string)

Implements

IEntityResolver

IDTDHandler

IContentHandler

IErrorHandler

IScanHandler

IXMLReader

ILexicalHandler