## entities

entities —

## Synopsis

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

## Description

## Details

### enum xmlEntityType

    typedef enum {
        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
    } xmlEntityType;

### struct xmlEntity

    struct xmlEntity {
        void           *_private;	        /* application data */
        xmlElementType          type;       /* XML_ENTITY_DECL, must be second ! */
        const xmlChar          *name;	/* Entity name */
        struct _xmlNode    *children;	/* First child link */
        struct _xmlNode        *last;	/* Last child link */
        struct _xmlDtd       *parent;	/* -> DTD */
        struct _xmlNode        *next;	/* next sibling link  */
        struct _xmlNode        *prev;	/* previous sibling link  */
        struct _xmlDoc          *doc;       /* the containing document */

        xmlChar                *orig;	/* content without ref substitution */
        xmlChar             *content;	/* content or ndata if unparsed */
        int                   length;	/* the content length */
        xmlEntityType          etype;	/* The entity type */
        const xmlChar    *ExternalID;	/* External identifier for PUBLIC */
        const xmlChar      *SystemID;	/* URI for a SYSTEM or PUBLIC Entity */

        struct _xmlEntity     *nexte;	/* unused */
        const xmlChar           *URI;	/* the full URI as computed */
        int                    owner;	/* does the entity own the childrens */
    };

### xmlEntitiesTablePtr

    typedef xmlEntitiesTable *xmlEntitiesTablePtr;

### xmlInitializePredefinedEntities ()

    void        xmlInitializePredefinedEntities (void);

Set up the predefined entities.

### 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

### 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

### xmlGetDocEntity ()

    xmlEntityPtr xmlGetDocEntity                (xmlDocPtr doc,
                                                 const xmlChar *name);

Do an entity lookup in the document entity hash table and returns the corresponding entity, otherwise a lookup is done in the predefined entities too.

`doc` : | the document referencing the entity
`name` : | the entity name
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 returns the corresponding entity, if found. Note: the first argument is the document node, not the DTD node.

`doc` : | the document referencing the entity
`name` : | the entity name
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 returns the corresponding parameter entity, if found.

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

### xmlEncodeEntities ()

    const xmlChar* xmlEncodeEntities            (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.

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 : | A newly allocated string with the substitution done.

### 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.

### xmlCreateEntitiesTable ()

    xmlEntitiesTablePtr xmlCreateEntitiesTable  (void);

create and initialize an empty entities hash table.

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

### 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.

### xmlFreeEntitiesTable ()

    void        xmlFreeEntitiesTable            (xmlEntitiesTablePtr table);

Deallocate the memory used by an entities hash table.

`table` : | An entity table

### 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

### xmlCleanupPredefinedEntities ()

    void        xmlCleanupPredefinedEntities    (void);

Cleanup up the predefined entities table.