libxml2: catalog.h File Reference

libxml2

Loading...
Searching...
No Matches
Macros | Typedefs | Functions
catalog.h File Reference

interfaces to the Catalog handling system More...

## Macros
#define | XML_CATALOGS_NAMESPACE (const xmlChar *) "urn:oasis:names:tc:entity:xmlns:xml:catalog"
| The namespace for the XML Catalogs elements.
#define | XML_CATALOG_PI (const xmlChar *) "oasis-xml-catalog"
| The specific XML Catalog Processing Instruction name.

## Typedefs
typedef struct _xmlCatalog | xmlCatalog
| XML catalog.

## Functions
xmlCatalog * | xmlNewCatalog (int sgml)
| create a new Catalog.
xmlCatalog * | xmlLoadACatalog (const char *filename)
| Load the catalog and build the associated data structures.
xmlCatalog * | xmlLoadSGMLSuperCatalog (const char *filename)
| Load an SGML super catalog.
int | xmlConvertSGMLCatalog (xmlCatalog *catal)
| Convert all the SGML catalog entries as XML ones.
int | xmlACatalogAdd (xmlCatalog *catal, const xmlChar *type, const xmlChar *orig, const xmlChar *replace)
| Add an entry in the catalog, it may overwrite existing but different entries.
int | xmlACatalogRemove (xmlCatalog *catal, const xmlChar *value)
| Remove an entry from the catalog.
xmlChar * | xmlACatalogResolve (xmlCatalog *catal, const xmlChar *pubID, const xmlChar *sysID)
| Do a complete resolution lookup of an External Identifier.
xmlChar * | xmlACatalogResolveSystem (xmlCatalog *catal, const xmlChar *sysID)
| Try to lookup the catalog resource for a system ID.
xmlChar * | xmlACatalogResolvePublic (xmlCatalog *catal, const xmlChar *pubID)
| Try to lookup the catalog local reference associated to a public ID in that catalog.
xmlChar * | xmlACatalogResolveURI (xmlCatalog *catal, const xmlChar *URI)
| Do a complete resolution lookup of an URI.
void | xmlACatalogDump (xmlCatalog *catal, FILE *out)
| Dump the given catalog to the given file.
void | xmlFreeCatalog (xmlCatalog *catal)
| Free the memory allocated to a Catalog.
int | xmlCatalogIsEmpty (xmlCatalog *catal)
| Check is a catalog is empty.
void | xmlInitializeCatalog (void)
| Load the default system catalog.
int | xmlLoadCatalog (const char *filename)
| Load the catalog and makes its definitions effective for the default external entity loader.
void | xmlLoadCatalogs (const char *paths)
| Load the catalogs and makes their definitions effective for the default external entity loader.
void | xmlCatalogCleanup (void)
| Free up all the memory associated with catalogs.
void | xmlCatalogDump (FILE *out)
| Dump all the global catalog content to the given file.
xmlDocPtr | xmlCatalogDumpDoc (void)
| Dump all the global catalog content as a xmlDoc This function is just for testing/debugging purposes.
xmlChar * | xmlCatalogResolve (const xmlChar *pubID, const xmlChar *sysID)
| Do a complete resolution lookup of an External Identifier.
xmlChar * | xmlCatalogResolveSystem (const xmlChar *sysID)
| Try to lookup the catalog resource for a system ID.
xmlChar * | xmlCatalogResolvePublic (const xmlChar *pubID)
| Try to lookup the catalog reference associated to a public ID.
xmlChar * | xmlCatalogResolveURI (const xmlChar *URI)
| Do a complete resolution lookup of an URI.
int | xmlCatalogAdd (const xmlChar *type, const xmlChar *orig, const xmlChar *replace)
| Add an entry in the catalog, it may overwrite existing but different entries.
int | xmlCatalogRemove (const xmlChar *value)
| Remove an entry from the catalog.
xmlDoc * | xmlParseCatalogFile (const char *filename)
| parse an XML file and build a tree.
int | xmlCatalogConvert (void)
| Convert all the SGML catalog entries as XML ones.
void | xmlCatalogFreeLocal (void *catalogs)
| Free up the memory associated to the catalog list.
void * | xmlCatalogAddLocal (void *catalogs, const xmlChar *URL)
| Add the new entry to the catalog list.
xmlChar * | xmlCatalogLocalResolve (void *catalogs, const xmlChar *pubID, const xmlChar *sysID)
| Do a complete resolution lookup of an External Identifier using a document's private catalog list.
xmlChar * | xmlCatalogLocalResolveURI (void *catalogs, const xmlChar *URI)
| Do a complete resolution lookup of an URI using a document's private catalog list.
int | xmlCatalogSetDebug (int level)
| Used to set the debug level for catalog operation, 0 disable debugging, 1 enable it.
xmlCatalogPrefer | xmlCatalogSetDefaultPrefer (xmlCatalogPrefer prefer)
| Allows to set the preference between public and system for deletion in XML Catalog resolution.
void | xmlCatalogSetDefaults (xmlCatalogAllow allow)
| Used to set the user preference w.r.t.
xmlCatalogAllow | xmlCatalogGetDefaults (void)
| Used to get the user preference w.r.t.
const xmlChar * | xmlCatalogGetSystem (const xmlChar *sysID)
| Try to lookup the catalog reference associated to a system ID.
const xmlChar * | xmlCatalogGetPublic (const xmlChar *pubID)
| Try to lookup the catalog reference associated to a public ID.

## Detailed Description

interfaces to the Catalog handling system

the catalog module implements the support for XML Catalogs and SGML catalogs

SGML Open Technical Resolution TR9401:1997. http://www.jclark.com/sp/catalog.htm

XML Catalogs Working Draft 06 August 2001 http://www.oasis-open.org/committees/entity/spec-2001-08-06.html

Copyright
  See Copyright for the status of this software.

Author
  Daniel Veillard

## Function Documentation

## ◆ xmlACatalogAdd()

int xmlACatalogAdd | ( | xmlCatalog * | catal,
|  | const xmlChar * | type,
|  | const xmlChar * | orig,
|  | const xmlChar * | replace
| ) |  |

Add an entry in the catalog, it may overwrite existing but different entries.

Deprecated:
  Internal function, don't use

Parameters

  catal | a Catalog
  type | the type of record to add to the catalog
  orig | the system, public or prefix to match
  replace | the replacement value for the match

Returns
  0 if successful, -1 otherwise

## ◆ xmlACatalogDump()

void xmlACatalogDump | ( | xmlCatalog * | catal,
|  | FILE * | out
| ) |  |

Dump the given catalog to the given file.

Deprecated:
  Internal function, don't use

Parameters

  catal | a Catalog
  out | the file.

## ◆ xmlACatalogRemove()

int xmlACatalogRemove | ( | xmlCatalog * | catal,
|  | const xmlChar * | value
| ) |  |

Remove an entry from the catalog.

Deprecated:
  Internal function, don't use

Parameters

  catal | a Catalog
  value | the value to remove

Returns
  the number of entries removed if successful, -1 otherwise

## ◆ xmlACatalogResolve()

xmlChar * xmlACatalogResolve | ( | xmlCatalog * | catal,
|  | const xmlChar * | pubID,
|  | const xmlChar * | sysID
| ) |  |

Do a complete resolution lookup of an External Identifier.

Deprecated:
  Internal function, don't use

Parameters

  catal | a Catalog
  pubID | the public ID string
  sysID | the system ID string

Returns
  the URI of the resource or NULL if not found, it must be freed by the caller.

## ◆ xmlACatalogResolvePublic()

xmlChar * xmlACatalogResolvePublic | ( | xmlCatalog * | catal,
|  | const xmlChar * | pubID
| ) |  |

Try to lookup the catalog local reference associated to a public ID in that catalog.

Deprecated:
  Internal function, don't use

Parameters

  catal | a Catalog
  pubID | the public ID string

Returns
  the local resource if found or NULL otherwise, the value returned must be freed by the caller.

## ◆ xmlACatalogResolveSystem()

xmlChar * xmlACatalogResolveSystem | ( | xmlCatalog * | catal,
|  | const xmlChar * | sysID
| ) |  |

Try to lookup the catalog resource for a system ID.

Deprecated:
  Internal function, don't use

Parameters

  catal | a Catalog
  sysID | the system ID string

Returns
  the resource if found or NULL otherwise, the value returned must be freed by the caller.

## ◆ xmlACatalogResolveURI()

xmlChar * xmlACatalogResolveURI | ( | xmlCatalog * | catal,
|  | const xmlChar * | URI
| ) |  |

Do a complete resolution lookup of an URI.

Deprecated:
  Internal function, don't use

Parameters

  catal | a Catalog
  URI | the URI

Returns
  the URI of the resource or NULL if not found, it must be freed by the caller.

## ◆ xmlCatalogAdd()

int xmlCatalogAdd | ( | const xmlChar * | type,
|  | const xmlChar * | orig,
|  | const xmlChar * | replace
| ) |  |

Add an entry in the catalog, it may overwrite existing but different entries.

If called before any other catalog routine, allows to override the default shared catalog put in place by xmlInitializeCatalog;

Parameters

  type | the type of record to add to the catalog
  orig | the system, public or prefix to match
  replace | the replacement value for the match

Returns
  0 if successful, -1 otherwise

## ◆ xmlCatalogAddLocal()

void * xmlCatalogAddLocal | ( | void * | catalogs,
|  | const xmlChar * | URL
| ) |  |

Add the new entry to the catalog list.

Parameters

  catalogs | a document's list of catalogs
  URL | the URL to a new local catalog

Returns
  the updated list

## ◆ xmlCatalogConvert()

int xmlCatalogConvert | ( | void |  | ) |

Convert all the SGML catalog entries as XML ones.

Returns
  the number of entries converted if successful, -1 otherwise

## ◆ xmlCatalogDump()

void xmlCatalogDump | ( | FILE * | out | ) |

Dump all the global catalog content to the given file.

Parameters

  out | the file.

## ◆ xmlCatalogDumpDoc()

xmlDocPtr xmlCatalogDumpDoc | ( | void |  | ) |

Dump all the global catalog content as a xmlDoc This function is just for testing/debugging purposes.

Returns
  The catalog as xmlDoc or NULL if failed, it must be freed by the caller.

## ◆ xmlCatalogFreeLocal()

void xmlCatalogFreeLocal | ( | void * | catalogs | ) |

Free up the memory associated to the catalog list.

Parameters

  catalogs | a document's list of catalogs

## ◆ xmlCatalogGetDefaults()

xmlCatalogAllow xmlCatalogGetDefaults | ( | void |  | ) |

Used to get the user preference w.r.t.

to what catalogs should be accepted

Deprecated:
  Use XML_PARSE_NO_SYS_CATALOG and XML_PARSE_CATALOG_PI.

Returns
  the current xmlCatalogAllow value

## ◆ xmlCatalogGetPublic()

const xmlChar * xmlCatalogGetPublic | ( | const xmlChar * | pubID | ) |

Try to lookup the catalog reference associated to a public ID.

Deprecated:
  use xmlCatalogResolvePublic

Parameters

  pubID | the public ID string

Returns
  the resource if found or NULL otherwise.

## ◆ xmlCatalogGetSystem()

const xmlChar * xmlCatalogGetSystem | ( | const xmlChar * | sysID | ) |

Try to lookup the catalog reference associated to a system ID.

Deprecated:
  use xmlCatalogResolveSystem

Parameters

  sysID | the system ID string

Returns
  the resource if found or NULL otherwise.

## ◆ xmlCatalogIsEmpty()

int xmlCatalogIsEmpty | ( | xmlCatalog * | catal | ) |

Check is a catalog is empty.

Deprecated:
  Internal function, don't use

Parameters

  catal | should this create an SGML catalog

Returns
  1 if the catalog is empty, 0 if not, amd -1 in case of error.

## ◆ xmlCatalogLocalResolve()

xmlChar * xmlCatalogLocalResolve | ( | void * | catalogs,
|  | const xmlChar * | pubID,
|  | const xmlChar * | sysID
| ) |  |

Do a complete resolution lookup of an External Identifier using a document's private catalog list.

Parameters

  catalogs | a document's list of catalogs
  pubID | the public ID string
  sysID | the system ID string

Returns
  the URI of the resource or NULL if not found, it must be freed by the caller.

## ◆ xmlCatalogLocalResolveURI()

xmlChar * xmlCatalogLocalResolveURI | ( | void * | catalogs,
|  | const xmlChar * | URI
| ) |  |

Do a complete resolution lookup of an URI using a document's private catalog list.

Parameters

  catalogs | a document's list of catalogs
  URI | the URI

Returns
  the URI of the resource or NULL if not found, it must be freed by the caller.

## ◆ xmlCatalogRemove()

int xmlCatalogRemove | ( | const xmlChar * | value | ) |

Remove an entry from the catalog.

Parameters

  value | the value to remove

Returns
  the number of entries removed if successful, -1 otherwise

## ◆ xmlCatalogResolve()

xmlChar * xmlCatalogResolve | ( | const xmlChar * | pubID,
|  | const xmlChar * | sysID
| ) |  |

Do a complete resolution lookup of an External Identifier.

Parameters

  pubID | the public ID string
  sysID | the system ID string

Returns
  the URI of the resource or NULL if not found, it must be freed by the caller.

## ◆ xmlCatalogResolvePublic()

xmlChar * xmlCatalogResolvePublic | ( | const xmlChar * | pubID | ) |

Try to lookup the catalog reference associated to a public ID.

Parameters

  pubID | the public ID string

Returns
  the resource if found or NULL otherwise, the value returned must be freed by the caller.

## ◆ xmlCatalogResolveSystem()

xmlChar * xmlCatalogResolveSystem | ( | const xmlChar * | sysID | ) |

Try to lookup the catalog resource for a system ID.

Parameters

  sysID | the system ID string

Returns
  the resource if found or NULL otherwise, the value returned must be freed by the caller.

## ◆ xmlCatalogResolveURI()

xmlChar * xmlCatalogResolveURI | ( | const xmlChar * | URI | ) |

Do a complete resolution lookup of an URI.

Parameters

  URI | the URI

Returns
  the URI of the resource or NULL if not found, it must be freed by the caller.

## ◆ xmlCatalogSetDebug()

int xmlCatalogSetDebug | ( | int | level | ) |

Used to set the debug level for catalog operation, 0 disable debugging, 1 enable it.

Parameters

  level | the debug level of catalogs required

Returns
  the previous value of the catalog debugging level

## ◆ xmlCatalogSetDefaultPrefer()

xmlCatalogPrefer xmlCatalogSetDefaultPrefer | ( | xmlCatalogPrefer | prefer | ) |

Allows to set the preference between public and system for deletion in XML Catalog resolution.

C.f. section 4.1.1 of the spec Values accepted are XML_CATA_PREFER_PUBLIC or XML_CATA_PREFER_SYSTEM

Deprecated:
  This setting is global and not thread-safe.

Parameters

  prefer | the default preference for delegation

Returns
  the previous value of the default preference for delegation

## ◆ xmlCatalogSetDefaults()

void xmlCatalogSetDefaults | ( | xmlCatalogAllow | allow | ) |

Used to set the user preference w.r.t.

to what catalogs should be accepted

Deprecated:
  Use XML_PARSE_NO_SYS_CATALOG and XML_PARSE_CATALOG_PI.

Parameters

  allow | what catalogs should be accepted

## ◆ xmlConvertSGMLCatalog()

int xmlConvertSGMLCatalog | ( | xmlCatalog * | catal | ) |

Convert all the SGML catalog entries as XML ones.

Deprecated:
  Internal function, don't use

Parameters

  catal | the catalog

Returns
  the number of entries converted if successful, -1 otherwise

## ◆ xmlFreeCatalog()

void xmlFreeCatalog | ( | xmlCatalog * | catal | ) |

Free the memory allocated to a Catalog.

Deprecated:
  Internal function, don't use

Parameters

  catal | a Catalog

## ◆ xmlLoadACatalog()

xmlCatalog * xmlLoadACatalog | ( | const char * | filename | ) |

Load the catalog and build the associated data structures.

This can be either an XML Catalog or an SGML Catalog It will recurse in SGML CATALOG entries. On the other hand XML Catalogs are not handled recursively.

Deprecated:
  Internal function, don't use

Parameters

  filename | a file path

Returns
  the catalog parsed or NULL in case of error

## ◆ xmlLoadCatalog()

int xmlLoadCatalog | ( | const char * | filename | ) |

Load the catalog and makes its definitions effective for the default external entity loader.

It will recurse in SGML CATALOG entries. this function is not thread safe, catalog initialization should preferably be done once at startup

Parameters

  filename | a file path

Returns
  0 in case of success -1 in case of error

## ◆ xmlLoadCatalogs()

void xmlLoadCatalogs | ( | const char * | pathss | ) |

Load the catalogs and makes their definitions effective for the default external entity loader.

this function is not thread safe, catalog initialization should preferably be done once at startup

Parameters

  pathss | a list of directories separated by a colon or a space.

## ◆ xmlLoadSGMLSuperCatalog()

xmlCatalog * xmlLoadSGMLSuperCatalog | ( | const char * | filename | ) |

Load an SGML super catalog.

It won't expand CATALOG or DELEGATE references. This is only needed for manipulating SGML Super Catalogs like adding and removing CATALOG or DELEGATE entries.

Deprecated:
  Internal function, don't use

Parameters

  filename | a file path

Returns
  the catalog parsed or NULL in case of error

## ◆ xmlNewCatalog()

xmlCatalog * xmlNewCatalog | ( | int | sgml | ) |

create a new Catalog.

Deprecated:
  Internal function, don't use

Parameters

  sgml | should this create an SGML catalog

Returns
  the xmlCatalog or NULL in case of error

## ◆ xmlParseCatalogFile()

xmlDoc * xmlParseCatalogFile | ( | const char * | filename | ) |

parse an XML file and build a tree.

It's like xmlParseFile except it bypass all catalog lookups.

Deprecated:
  Internal function, don't use

Parameters

  filename | the filename

Returns
  the resulting document tree or NULL in case of error