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 startEntity/endEntity events. There is no additional requirement that events from DeclHandler or DTDHandler be properly ordered.

Note   The 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.

Implementation Syntax

Sub startEntity(strName As String)

Parameters

strName

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]".

Return Values

If failed, the LexicalHandler raises a trappable error.

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 startEntity/endEntity events. Note that skipped entities will be reported through the skippedEntity event.

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-general-entities" and "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 startEntity and endEntity events.

Syntax

HRESULT startEntity(
   [in] const wchar_t * pwchName, 
   [in] int cchName); 

Parameters

pwchName [in]

The name of the entity. For parameter entities, the name begins with "%".

cchName [in]

The length of the entity name.

Return Values

S_OK

The value returned if no errors occur.

E_FAIL

The value returned if the parse operation should be aborted.