ISAXLexicalHandler::startEntity Method (Windows CE 5.0)
This method indicates that the reader has opened and started to process an internally or externally defined entity in the content of the document.
HRESULT startEntity(const wchar_t* pwchName,intcchName);
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 Values
- 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 "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.
Requirements
OS Versions: Windows CE .NET 4.0 and later.
Header: Msxml2.h, Msxml2.idl.
Link Library: Uuid.lib.
See Also
ISAXXMLReader Interface | endEntity Method | putFeature Method | ISAXLexicalHandler:IUnknown Interface
Send Feedback on this topic to the authors