Indicates that the reader has opened and started to process an internally or externally defined entity in the content of the document.
The reporting of parameter entities, including any external document type definition (DTD) subset, is optional. SAX2 (Simple API for XML) drivers that support a
LexicalHandler may not support reporting of entities. Use the
"http://xml.org/sax/features/lexical-handler/parameter-entities" feature to query or control the reporting of parameter entities.
The reader reports general entities with their regular names, parameter entities with '%' prepended to their names, and any external DTD subset with the pseudo-entity name "[dtd]".
When a reader driver provides these events, all other events must be properly nested within
endEntity events. There is no additional requirement that events from
DTDHandler be properly ordered.
skippedEntity event, which is part of the
ContentHandler interface, reports skipped entities.
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 are silently expanded, with no indication of where the original entity boundaries were.
Furthermore, the boundaries of character references (which are not really entities anyway) are not reported.
Visual Basic Implementation Syntax
Sub startEntity(strName As String)
The name of the entity. If it is a parameter entity, the name begins with '%'. If the parameter is an external DTD subset, it uses "[dtd]".
If failed, the
LexicalHandler raises a trappable error.
HRESULT startEntity( [in] const wchar_t * pwchName, [in] int cchName);
The name of the entity. For parameter entities, the name begins with "%".
The length of the entity name.
The value returned if no errors occur.
The value returned if the parse operation should be aborted.
The reader never reports entity references in attribute values, as well as the start and end of the document entity. In addition, the reader reports the start and end of the external document type definition (DTD) subset using the pseudo-name "[dtd]". All other events must be properly nested within the
endEntity events. Note that skipped entities will be reported through the
Entities are references to other content, which can be a piece of text or a large external file. Declaring an entity is done within a DTD. Entities always have two parts, the declaration and the reference. For example, consider the following entity reference:
<!ENTITY CompName "Microsoft( Corporation">
This entity can be referenced as follows:
&CompName; is an industry leader.
Which is interpreted as:
Microsoft( Corporation is an industry leader.
XML offers two kinds of entities — general entities and parameter entities. General entities, defined in DTDs, substitute the entity value within a document, as shown in the preceding example. Parameter entities link the content of additional DTD files to a DTD, or act as an abbreviation for frequently repeated declarations. To distinguish between these two types of entities, general entities use an ampersand (&) while parameter entities use the percent sign (%).
The reporting of parameter entities (including the DTD subset) is strictly optional. To allow the reader to recognize external entities, you use the
putFeature method of the
ISAXXMLReader interface to set the
"http://xml.org/sax/features/lexical-handler/external-parameter-entities" features. The reader reports the general entities with their regular names, parameter entities have "%" prepended to their names, and the external DTD subset has the pseudo-entity name "[dtd]". When the reader reports these events, all other events must be properly nested within
Implemented in: MSXML 3.0 and later