entities

Name

entities —

Synopsis



enum        xmlEntityType;
struct      xmlEntity;
typedef     xmlEntityPtr;
#define     XML_MIN_ENTITIES_TABLE
struct      xmlEntitiesTable;
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);
int         xmlEntityAddReference           (xmlEntityPtr ent,
                                             const xmlChar *to);

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 {
#ifndef XML_WITHOUT_CORBA
    void           *_private;	        /* for Corba, must be first ! */
#endif
    xmlElementType          type;       /* XML_ENTITY_DECL, must be second ! */
    const xmlChar          *name;	/* Attribute name */
    struct _xmlNode    *children;	/* NULL */
    struct _xmlNode        *last;	/* NULL */
    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;	/* next entity in the hash table */
    const xmlChar           *URI;	/* the full URI as computed */

#ifdef WITH_EXTRA_ENT_DETECT
    /* Referenced entities name stack */
    xmlChar           *ent;             /* Current parsed Node */
    int                entNr;           /* Depth of the parsing stack */
    int                entMax;          /* Max depth of the parsing stack */
    xmlChar *         *entTab;          /* array of nodes */
#endif
};


xmlEntityPtr

typedef xmlEntity *xmlEntityPtr;


XML_MIN_ENTITIES_TABLE

#define XML_MIN_ENTITIES_TABLE	32


struct xmlEntitiesTable

struct xmlEntitiesTable {
    int nb_entities;		/* number of elements stored */
    int max_entities;		/* maximum number of elements */
    xmlEntityPtr *table;	/* the table of entities */
};


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, othervise the entity


xmlGetDocEntity ()

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

Do an entity lookup in the document entity hash table and returns the corrsponding 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.

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.


xmlEntityAddReference ()

int         xmlEntityAddReference           (xmlEntityPtr ent,
                                             const xmlChar *to);

Function to register reuse of an existing entity from a (new) one Used to keep track of references and detect cycles (well formedness errors !).

ent : an existing entity
to : the entity name it's referencing
Returns : 0 if Okay, -1 in case of general error, 1 in case of loop detection.