entities: interface for the XML entities handling

## entities

entities - interface for the XML entities handling

this module provides some of the entity API needed for the parser and applications.

Author(s): Daniel Veillard

## Synopsis

    typedef enum xmlEntityType;
    typedef struct _xmlHashTable xmlEntitiesTable;
    typedef xmlEntitiesTable * xmlEntitiesTablePtr;
    xmlEntityPtr	xmlAddDocEntity		(xmlDocPtr doc,
    					 const xmlChar * name,
    					 int type,
    					 const xmlChar * ExternalID,
    					 const xmlChar * SystemID,
    					 const xmlChar * content);
    xmlChar *	xmlEncodeEntitiesReentrant	(xmlDocPtr doc,
    						 const xmlChar * input);
    xmlEntityPtr	xmlGetDocEntity		(xmlDocPtr doc,
    					 const xmlChar * name);
    xmlEntityPtr	xmlGetDtdEntity		(xmlDocPtr doc,
    					 const xmlChar * name);
    xmlEntityPtr	xmlAddDtdEntity		(xmlDocPtr doc,
    					 const xmlChar * name,
    					 int type,
    					 const xmlChar * ExternalID,
    					 const xmlChar * SystemID,
    					 const xmlChar * content);
    xmlEntitiesTablePtr	xmlCopyEntitiesTable	(xmlEntitiesTablePtr table);
    void	xmlFreeEntitiesTable		(xmlEntitiesTablePtr table);
    xmlEntityPtr	xmlGetParameterEntity	(xmlDocPtr doc,
    					 const xmlChar * name);
    void	xmlDumpEntitiesTable		(xmlBufferPtr buf,
    					 xmlEntitiesTablePtr table);
    void	xmlDumpEntityDecl		(xmlBufferPtr buf,
    					 xmlEntityPtr ent);
    void	xmlCleanupPredefinedEntities	(void);
    xmlEntitiesTablePtr	xmlCreateEntitiesTable	(void);
    const xmlChar *	xmlEncodeEntities	(xmlDocPtr doc,
    					 const xmlChar * input);
    xmlChar *	xmlEncodeSpecialChars	(xmlDocPtr doc,
    					 const xmlChar * input);
    xmlEntityPtr	xmlGetPredefinedEntity	(const xmlChar * name);
    void	xmlInitializePredefinedEntities	(void);

## Description

## Details

### Structure xmlEntitiesTable

    struct _xmlHashTable {
    The content of this structure is not made public by the API.
    } xmlEntitiesTable;

### Typedef xmlEntitiesTablePtr

    xmlEntitiesTable * xmlEntitiesTablePtr;

### Enum xmlEntityType

    enum xmlEntityType {
        XML_INTERNAL_GENERAL_ENTITY = 1
        XML_EXTERNAL_GENERAL_PARSED_ENTITY = 2
        XML_EXTERNAL_GENERAL_UNPARSED_ENTITY = 3
        XML_INTERNAL_PARAMETER_ENTITY = 4
        XML_EXTERNAL_PARAMETER_ENTITY = 5
        XML_INTERNAL_PREDEFINED_ENTITY = 6
    };

### xmlAddDocEntity ()

    xmlEntityPtr	xmlAddDocEntity		(xmlDocPtr doc,
    					 const xmlChar * name,
    					 int type,
    					 const xmlChar * ExternalID,
    					 const xmlChar * SystemID,
    					 const xmlChar * content)

Register a new entity for this document.

`doc`: | the document
`name`: | the entity name
`type`: | the entity type XML_xxx_yyy_ENTITY
`ExternalID`: | the entity external ID if available
`SystemID`: | the entity system ID if available
`content`: | the entity content
`Returns`: | a pointer to the entity or NULL in case of error

### xmlAddDtdEntity ()

    xmlEntityPtr	xmlAddDtdEntity		(xmlDocPtr doc,
    					 const xmlChar * name,
    					 int type,
    					 const xmlChar * ExternalID,
    					 const xmlChar * SystemID,
    					 const xmlChar * content)

Register a new entity for this document DTD external subset.

`doc`: | the document
`name`: | the entity name
`type`: | the entity type XML_xxx_yyy_ENTITY
`ExternalID`: | the entity external ID if available
`SystemID`: | the entity system ID if available
`content`: | the entity content
`Returns`: | a pointer to the entity or NULL in case of error

### xmlCleanupPredefinedEntities ()

    void	xmlCleanupPredefinedEntities	(void)

Cleanup up the predefined entities table. Deprecated call

### xmlCopyEntitiesTable ()

    xmlEntitiesTablePtr	xmlCopyEntitiesTable	(xmlEntitiesTablePtr table)

Build a copy of an entity table.

`table`: | An entity table
`Returns`: | the new xmlEntitiesTablePtr or NULL in case of error.

### xmlCreateEntitiesTable ()

    xmlEntitiesTablePtr	xmlCreateEntitiesTable	(void)

create and initialize an empty entities hash table. This really doesn't make sense and should be deprecated

`Returns`: | the xmlEntitiesTablePtr just created or NULL in case of error.

### xmlDumpEntitiesTable ()

    void	xmlDumpEntitiesTable		(xmlBufferPtr buf,
    					 xmlEntitiesTablePtr table)

This will dump the content of the entity table as an XML DTD definition

`buf`: | An XML buffer.
`table`: | An entity table

### xmlDumpEntityDecl ()

    void	xmlDumpEntityDecl		(xmlBufferPtr buf,
    					 xmlEntityPtr ent)

This will dump the content of the entity table as an XML DTD definition

`buf`: | An XML buffer.
`ent`: | An entity table

### xmlEncodeEntities ()

    const xmlChar *	xmlEncodeEntities	(xmlDocPtr doc,
    					 const xmlChar * input)

TODO: remove xmlEncodeEntities, once we are not afraid of breaking binary compatibility People must migrate their code to xmlEncodeEntitiesReentrant ! This routine will issue a warning when encountered.

`doc`: | the document containing the string
`input`: | A string to convert to XML.
`Returns`: | NULL

### xmlEncodeEntitiesReentrant ()

    xmlChar *	xmlEncodeEntitiesReentrant	(xmlDocPtr doc,
    						 const xmlChar * input)

Do a global encoding of a string, replacing the predefined entities and non ASCII values with their entities and CharRef counterparts. Contrary to xmlEncodeEntities, this routine is reentrant, and result must be deallocated.

`doc`: | the document containing the string
`input`: | A string to convert to XML.
`Returns`: | A newly allocated string with the substitution done.

### xmlEncodeSpecialChars ()

    xmlChar *	xmlEncodeSpecialChars	(xmlDocPtr doc,
    					 const xmlChar * input)

Do a global encoding of a string, replacing the predefined entities this routine is reentrant, and result must be deallocated.

`doc`: | the document containing the string
`input`: | A string to convert to XML.
`Returns`: | A newly allocated string with the substitution done.

### xmlFreeEntitiesTable ()

    void	xmlFreeEntitiesTable		(xmlEntitiesTablePtr table)

Deallocate the memory used by an entities hash table.

`table`: | An entity table

### xmlGetDocEntity ()

    xmlEntityPtr	xmlGetDocEntity		(xmlDocPtr doc,
    					 const xmlChar * name)

Do an entity lookup in the document entity hash table and

`doc`: | the document referencing the entity
`name`: | the entity name
`Returns`: | the corresponding entity, otherwise a lookup is done in the predefined entities too. Returns A pointer to the entity structure or NULL if not found.

### xmlGetDtdEntity ()

    xmlEntityPtr	xmlGetDtdEntity		(xmlDocPtr doc,
    					 const xmlChar * name)

Do an entity lookup in the DTD entity hash table and

`doc`: | the document referencing the entity
`name`: | the entity name
`Returns`: | the corresponding entity, if found. Note: the first argument is the document node, not the DTD node. Returns A pointer to the entity structure or NULL if not found.

### xmlGetParameterEntity ()

    xmlEntityPtr	xmlGetParameterEntity	(xmlDocPtr doc,
    					 const xmlChar * name)

Do an entity lookup in the internal and external subsets and

`doc`: | the document referencing the entity
`name`: | the entity name
`Returns`: | the corresponding parameter entity, if found. Returns A pointer to the entity structure or NULL if not found.

### xmlGetPredefinedEntity ()

    xmlEntityPtr	xmlGetPredefinedEntity	(const xmlChar * name)

Check whether this name is an predefined entity.

`name`: | the entity name
`Returns`: | NULL if not, otherwise the entity

### xmlInitializePredefinedEntities ()

    void	xmlInitializePredefinedEntities	(void)

Set up the predefined entities. Deprecated call