startEntity Method
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 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.
Visual Basic 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.
C/C++ 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.
Remarks
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.
Versioning
Implemented in: MSXML 3.0 and later