From 2bb89090d16cfcc42bb0015de9532094e1e57936 Mon Sep 17 00:00:00 2001 From: Daniel Veillard Date: Thu, 31 Aug 2000 14:57:50 +0000 Subject: [PATCH] Added doc on the xmlExternalEntityLoaders and example for catalogs, Daniel --- ChangeLog | 5 ++++ doc/xmlio.html | 64 ++++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 64 insertions(+), 5 deletions(-) diff --git a/ChangeLog b/ChangeLog index fefa4027..54a1c84b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Thu Aug 31 16:55:55 CEST 2000 Daniel Veillard + + * doc/xmlio.html: added doc and example for entity loader + redefinition. + Thu Aug 31 14:59:28 CEST 2000 Daniel Veillard * doc/xmlio.html doc/xml.html: added a doc on the I/O mechanism diff --git a/doc/xmlio.html b/doc/xmlio.html index 87af4c2f..71a6c5f8 100644 --- a/doc/xmlio.html +++ b/doc/xmlio.html @@ -18,7 +18,7 @@ href="http://xmlsoft.org/xmlio.html">http://xmlsoft.org/xmlio.html

Mailing-list archive: http://xmlsoft.org/messages/

-

Version: $Revision: 1.1 $

+

Version: $Revision: 1.2 $

Table of Content:

    @@ -26,6 +26,7 @@ href="http://xmlsoft.org/messages/">http://xmlsoft.org/messages/

  1. The basic buffer type
  2. Input I/O handlers
  3. Output I/O handlers
    4. +
  4. The entities loader
  5. Example of customized I/O
@@ -33,9 +34,16 @@ href="http://xmlsoft.org/messages/">http://xmlsoft.org/messages/

The module xmlIO.h -provides the interfaces to the libxml I/O system. This consists of 3 main +provides the interfaces to the libxml I/O system. This consists of 4 main parts:

    +
  • Entities loader, this is a routine which tries to fetch the entities + (files) based on their PUBLIC and SYSTEM identifiers. The default loader + don't look at the public identifier since libxml do not maintain a + catalog. You can redefine you own entity loader by using + xmlGetExternalEntityLoader() and + xmlSetExternalEntityLoader(). Check the + example.
  • Input I/O buffers which are a commodity structure used by the parser(s) input layer to handle fetching the informations to feed the parser. This provides buffering and is also a placeholder where the encoding convertors @@ -49,12 +57,14 @@ parts:

-

The general mechanism used when loading http://rpmfind.net/xml.html for +

The general mechanism used when loading http://rpmfind.net/xml.html for example in the HTML parser is the following:

    +
  1. The default entity loader calls xmlNewInputFromFile() with + the parsing context and the URI string.
  2. the URI string is checked against the existing registered handlers using their match() callback function, if the HTTP module was compiled in, it is - registered and its macth() function will succeed
    3. + registered and its match() function will succeeds
  3. the open() function of the handler is called and if successful will return an I/O Input buffer
  4. the parser will the start reading from this buffer and progressively @@ -98,6 +108,48 @@ needed.

    An Output handler xmlOutputBuffer is completely similar to an Input one except the callbacks are write() and close().

    +

    The entities loader

    + +

    The entity loader resolves requests for new entities and create inputs for +the parser. Creating an input from a filename or an URI string is done through +the xmlNewInputFromFile() routine. The default entity loader do not handle +the PUBLIC identifier associated with an entity (if any). So it just calls +xmlNewInputFromFile() with the SYSTEM identifier (which is mandatory in +XML).

    + +

    If you want to hook up a catalog mechanism then you simply need to override +the default entity loader, here is an example:

    +
    #include <libxml/xmlIO.h>
+
+xmlExternalEntityLoader defaultLoader = NULL;
+
+xmlParserInputPtr
+xmlMyExternalEntityLoader(const char *URL, const char *ID,
+                               xmlParserCtxtPtr ctxt) {
+    xmlParserInputPtr ret;
+    const char *fileID = NULL;
+    /* lookup for the fileID depending on ID */
+
+    ret = xmlNewInputFromFile(ctxt, fileID);
+    if (ret != NULL)
+        return(ret);
+    if (defaultLoader != NULL)
+        ret = defaultLoader(URL, ID, ctxt);
+    return(ret);
+}
+
+int main(..) {
+    ...
+
+    /*
+     * Install our own entity loader
+     */
+    defaultLoader = xmlGetExternalEntityLoader();
+    xmlSetExternalEntityLoader(xmlMyExternalEntityLoader);
+
+    ...
+}
    +

    Example of customized I/O

    This example come from a @@ -123,6 +175,8 @@ xmlOutputBufferCreateOwn(FILE *file, xmlCharEncodingHandlerPtr encoder) {         ret->closecallback = NULL; /* No close callback */     }     return(ret);
    + + }

  5. And then use it to save the document: @@ -142,6 +196,6 @@ res = xmlSaveFileTo(output, doc, NULL);

    Daniel Veillard

    -

    $Id: xmlio.html,v 1.1 2000/08/31 13:50:12 veillard Exp $

    +

    $Id: xmlio.html,v 1.2 2000/08/31 14:19:54 veillard Exp $