ISAXLexicalHandler::startEntity Method

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method indicates that the reader has opened and started to process an internally or externally defined entity in the content of the document.

Syntax

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

Parameters

• pwchName
  [in] Pointer to the name of the entity. For parameter entities, the name begins with "%".

• cchName
  [in] Length of the entity name.

Return Value

• S_OK
  Returned if no errors occur.

• E_FAIL
  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, as shown in the following code sample.

<!ENTITY CompName "Microsoft® Corporation">

This entity can be referenced as follows:

&CompName; is an industry leader.

This is interpreted as the following string:

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 "https://xml.org/sax/features/lexical-handler/external-general-entities" and "https://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.

Requirements

See Also

Reference

ISAXXMLReader
ISAXLexicalHandler::endEntity Method
ISAXXMLReader::putFeature Method
ISAXLexicalHandler