libxml2/doc/xmlio.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   5 <link rel="SHORTCUT ICON" href="/favicon.ico">
   6 <style type="text/css"><!--
   7 TD {font-family: Verdana,Arial,Helvetica}
   8 BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}
   9 H1 {font-family: Verdana,Arial,Helvetica}
  10 H2 {font-family: Verdana,Arial,Helvetica}
  11 H3 {font-family: Verdana,Arial,Helvetica}
  12 A:link, A:visited, A:active { text-decoration: underline }
  13 --></style>
  14 <title>I/O Interfaces</title>
  15 </head>
  16 <body bgcolor="#8b7765" text="#000000" link="#000000" vlink="#000000">
  17 <table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr>
  18 <td width="180">
  19 <a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo"></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo"></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo"></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo"></a></div>
  20 </td>
  21 <td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center">
  22 <h1>The XML C library for Gnome</h1>
  23 <h2>I/O Interfaces</h2>
  24 </td></tr></table></td></tr></table></td>
  25 </tr></table>
  26 <table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr>
  27 <td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td>
  28 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  29 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr>
  30 <tr><td bgcolor="#fffacd">
  31 <form action="search.php" enctype="application/x-www-form-urlencoded" method="GET">
  32 <input name="query" type="TEXT" size="20" value=""><input name="submit" type="submit" value="Search ...">
  33 </form>
  34 <ul>
  35 <li><a href="index.html">Home</a></li>
  36 <li><a href="intro.html">Introduction</a></li>
  37 <li><a href="FAQ.html">FAQ</a></li>
  38 <li><a href="docs.html">Documentation</a></li>
  39 <li><a href="bugs.html">Reporting bugs and getting help</a></li>
  40 <li><a href="help.html">How to help</a></li>
  41 <li><a href="downloads.html">Downloads</a></li>
  42 <li><a href="news.html">News</a></li>
  43 <li><a href="XMLinfo.html">XML</a></li>
  44 <li><a href="XSLT.html">XSLT</a></li>
  45 <li><a href="python.html">Python and bindings</a></li>
  46 <li><a href="architecture.html">libxml architecture</a></li>
  47 <li><a href="tree.html">The tree output</a></li>
  48 <li><a href="interface.html">The SAX interface</a></li>
  49 <li><a href="xmldtd.html">Validation &amp; DTDs</a></li>
  50 <li><a href="xmlmem.html">Memory Management</a></li>
  51 <li><a href="encoding.html">Encodings support</a></li>
  52 <li><a href="xmlio.html">I/O Interfaces</a></li>
  53 <li><a href="catalog.html">Catalog support</a></li>
  54 <li><a href="library.html">The parser interfaces</a></li>
  55 <li><a href="entities.html">Entities or no entities</a></li>
  56 <li><a href="namespaces.html">Namespaces</a></li>
  57 <li><a href="upgrade.html">Upgrading 1.x code</a></li>
  58 <li><a href="threads.html">Thread safety</a></li>
  59 <li><a href="DOM.html">DOM Principles</a></li>
  60 <li><a href="example.html">A real example</a></li>
  61 <li><a href="contribs.html">Contributions</a></li>
  62 <li><a href="xmlreader.html">The Reader Interface</a></li>
  63 <li><a href="tutorial/index.html">Tutorial</a></li>
  64 <li><a href="guidelines.html">XML Guidelines</a></li>
  65 <li>
  66 <a href="xml.html">flat page</a>, <a href="site.xsl">stylesheet</a>
  67 </li>
  68 </ul>
  69 </td></tr>
  70 </table>
  71 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  72 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr>
  73 <tr><td bgcolor="#fffacd"><ul>
  74 <li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li>
  75 <li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li>
  76 <li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li>
  77 <li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li>
  78 <li><a href="ftp://xmlsoft.org/">FTP</a></li>
  79 <li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li>
  80 <li><a href="http://garypennington.net/libxml2/">Solaris binaries</a></li>
  81 <li><a href="http://www.zveno.com/open_source/libxml2xslt.html">MacOsX binaries</a></li>
  82 <li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li>
  83 <li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml&amp;product=libxml2">Bug Tracker</a></li>
  84 </ul></td></tr>
  85 </table>
  86 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  87 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>API Indexes</b></center></td></tr>
  88 <tr><td bgcolor="#fffacd"><ul>
  89 <li><a href="APIchunk0.html">Alphabetic</a></li>
  90 <li><a href="APIconstructors.html">Constructors</a></li>
  91 <li><a href="APIfunctions.html">Functions/Types</a></li>
  92 <li><a href="APIfiles.html">Modules</a></li>
  93 <li><a href="APIsymbols.html">Symbols</a></li>
  94 </ul></td></tr>
  95 </table>
  96 </td></tr></table></td>
  97 <td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd">
  98 <p>Table of Content:</p>
  99 <ol>
 100 <li><a href="#General1">General overview</a></li>
 101   <li><a href="#basic">The basic buffer type</a></li>
 102   <li><a href="#Input">Input I/O handlers</a></li>
 103   <li><a href="#Output">Output I/O handlers</a></li>
 104   <li><a href="#entities">The entities loader</a></li>
 105   <li><a href="#Example2">Example of customized I/O</a></li>
 106 </ol>
 107 <h3><a name="General1">General overview</a></h3>
 108 <p>The module <code><a href="http://xmlsoft.org/html/libxml-xmlio.html">xmlIO.h</a></code> provides
 109 the interfaces to the libxml I/O system. This consists of 4 main parts:</p>
 110 <ul>
 111 <li>Entities loader, this is a routine which tries to fetch the entities
 112     (files) based on their PUBLIC and SYSTEM identifiers. The default loader
 113     don't look at the public identifier since libxml do not maintain a
 114     catalog. You can redefine you own entity loader by using
 115     <code>xmlGetExternalEntityLoader()</code> and
 116     <code>xmlSetExternalEntityLoader()</code>. <a href="#entities">Check the
 117     example</a>.</li>
 118   <li>Input I/O buffers which are a commodity structure used by the parser(s)
 119     input layer to handle fetching the informations to feed the parser. This
 120     provides buffering and is also a placeholder where the encoding
 121     converters to UTF8 are piggy-backed.</li>
 122   <li>Output I/O buffers are similar to the Input ones and fulfill similar
 123     task but when generating a serialization from a tree.</li>
 124   <li>A mechanism to register sets of I/O callbacks and associate them with
 125     specific naming schemes like the protocol part of the URIs.
 126     <p>This affect the default I/O operations and allows to use specific I/O
 127     handlers for certain names.</p>
 128   </li>
 129 </ul>
 130 <p>The general mechanism used when loading http://rpmfind.net/xml.html for
 131 example in the HTML parser is the following:</p>
 132 <ol>
 133 <li>The default entity loader calls <code>xmlNewInputFromFile()</code> with
 134     the parsing context and the URI string.</li>
 135   <li>the URI string is checked against the existing registered handlers
 136     using their match() callback function, if the HTTP module was compiled
 137     in, it is registered and its match() function will succeeds</li>
 138   <li>the open() function of the handler is called and if successful will
 139     return an I/O Input buffer</li>
 140   <li>the parser will the start reading from this buffer and progressively
 141     fetch information from the resource, calling the read() function of the
 142     handler until the resource is exhausted</li>
 143   <li>if an encoding change is detected it will be installed on the input
 144     buffer, providing buffering and efficient use of the conversion
 145   routines</li>
 146   <li>once the parser has finished, the close() function of the handler is
 147     called once and the Input buffer and associated resources are
 148   deallocated.</li>
 149 </ol>
 150 <p>The user defined callbacks are checked first to allow overriding of the
 151 default libxml I/O routines.</p>
 152 <h3><a name="basic">The basic buffer type</a></h3>
 153 <p>All the buffer manipulation handling is done using the
 154 <code>xmlBuffer</code> type define in <code><a href="http://xmlsoft.org/html/libxml-tree.html">tree.h</a> </code>which is a
 155 resizable memory buffer. The buffer allocation strategy can be selected to be
 156 either best-fit or use an exponential doubling one (CPU vs. memory use
 157 trade-off). The values are <code>XML_BUFFER_ALLOC_EXACT</code> and
 158 <code>XML_BUFFER_ALLOC_DOUBLEIT</code>, and can be set individually or on a
 159 system wide basis using <code>xmlBufferSetAllocationScheme()</code>. A number
 160 of functions allows to manipulate buffers with names starting with the
 161 <code>xmlBuffer...</code> prefix.</p>
 162 <h3><a name="Input">Input I/O handlers</a></h3>
 163 <p>An Input I/O handler is a simple structure
 164 <code>xmlParserInputBuffer</code> containing a context associated to the
 165 resource (file descriptor, or pointer to a protocol handler), the read() and
 166 close() callbacks to use and an xmlBuffer. And extra xmlBuffer and a charset
 167 encoding handler are also present to support charset conversion when
 168 needed.</p>
 169 <h3><a name="Output">Output I/O handlers</a></h3>
 170 <p>An Output handler <code>xmlOutputBuffer</code> is completely similar to an
 171 Input one except the callbacks are write() and close().</p>
 172 <h3><a name="entities">The entities loader</a></h3>
 173 <p>The entity loader resolves requests for new entities and create inputs for
 174 the parser. Creating an input from a filename or an URI string is done
 175 through the xmlNewInputFromFile() routine.  The default entity loader do not
 176 handle the PUBLIC identifier associated with an entity (if any). So it just
 177 calls xmlNewInputFromFile() with the SYSTEM identifier (which is mandatory in
 178 XML).</p>
 179 <p>If you want to hook up a catalog mechanism then you simply need to
 180 override the default entity loader, here is an example:</p>
 181 <pre>#include &lt;libxml/xmlIO.h&gt;
 182
 183 xmlExternalEntityLoader defaultLoader = NULL;
 184
 185 xmlParserInputPtr
 186 xmlMyExternalEntityLoader(const char *URL, const char *ID,
 187                                xmlParserCtxtPtr ctxt) {
 188     xmlParserInputPtr ret;
 189     const char *fileID = NULL;
 190     /* lookup for the fileID depending on ID */
 191
 192     ret = xmlNewInputFromFile(ctxt, fileID);
 193     if (ret != NULL)
 194         return(ret);
 195     if (defaultLoader != NULL)
 196         ret = defaultLoader(URL, ID, ctxt);
 197     return(ret);
 198 }
 199
 200 int main(..) {
 201     ...
 202
 203     /*
 204      * Install our own entity loader
 205      */
 206     defaultLoader = xmlGetExternalEntityLoader();
 207     xmlSetExternalEntityLoader(xmlMyExternalEntityLoader);
 208
 209     ...
 210 }</pre>
 211 <h3><a name="Example2">Example of customized I/O</a></h3>
 212 <p>This example come from <a href="http://xmlsoft.org/messages/0708.html">a
 213 real use case</a>,  xmlDocDump() closes the FILE * passed by the application
 214 and this was a problem. The <a href="http://xmlsoft.org/messages/0711.html">solution</a> was to redefine a
 215 new output handler with the closing call deactivated:</p>
 216 <ol>
 217 <li>First define a new I/O output allocator where the output don't close
 218     the file:
 219     <pre>xmlOutputBufferPtr
 220 xmlOutputBufferCreateOwn(FILE *file, xmlCharEncodingHandlerPtr encoder) {
 221     xmlOutputBufferPtr ret;
 222
 223     if (xmlOutputCallbackInitialized == 0)
 224         xmlRegisterDefaultOutputCallbacks();
 225
 226     if (file == NULL) return(NULL);
 227     ret = xmlAllocOutputBuffer(encoder);
 228     if (ret != NULL) {
 229         ret-&gt;context = file;
 230         ret-&gt;writecallback = xmlFileWrite;
 231         ret-&gt;closecallback = NULL;  /* No close callback */
 232     }
 233     return(ret); <br>
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269 } </pre>
 270   </li>
 271   <li>And then use it to save the document:
 272     <pre>FILE *f;
 273 xmlOutputBufferPtr output;
 274 xmlDocPtr doc;
 275 int res;
 276
 277 f = ...
 278 doc = ....
 279
 280 output = xmlOutputBufferCreateOwn(f, NULL);
 281 res = xmlSaveFileTo(output, doc, NULL);
 282     </pre>
 283   </li>
 284 </ol>
 285 <p><a href="bugs.html">Daniel Veillard</a></p>
 286 </td></tr></table></td></tr></table></td></tr></table></td>
 287 </tr></table></td></tr></table>
 288 </body>
 289 </html>