Daniel Veillard | 9698445 | 2000-08-31 13:50:12 +0000 | [diff] [blame^] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" |
| 2 | "http://www.w3.org/TR/REC-html40/loose.dtd"> |
| 3 | <html> |
| 4 | <head> |
| 5 | <title>Libxml Input/Output handling</title> |
| 6 | <meta name="GENERATOR" content="amaya V3.2.1"> |
| 7 | <meta http-equiv="Content-Type" content="text/html"> |
| 8 | </head> |
| 9 | |
| 10 | <body bgcolor="#ffffff"> |
| 11 | <h1 align="center">Libxml Input/Output handling</h1> |
| 12 | |
| 13 | <p>Location: <a |
| 14 | href="http://xmlsoft.org/xmlio.html">http://xmlsoft.org/xmlio.html</a></p> |
| 15 | |
| 16 | <p>Libxml home page: <a href="http://xmlsoft.org/">http://xmlsoft.org/</a></p> |
| 17 | |
| 18 | <p>Mailing-list archive: <a |
| 19 | href="http://xmlsoft.org/messages/">http://xmlsoft.org/messages/</a></p> |
| 20 | |
| 21 | <p>Version: $Revision:$</p> |
| 22 | |
| 23 | <p>Table of Content:</p> |
| 24 | <ol> |
| 25 | <li><a href="#General">General overview</a></li> |
| 26 | <li><a href="#basic">The basic buffer type</a></li> |
| 27 | <li><a href="#Input">Input I/O handlers</a></li> |
| 28 | <li><a href="#Output">Output I/O handlers</a></li> |
| 29 | <li><a href="#Example">Example of customized I/O</a></li> |
| 30 | </ol> |
| 31 | |
| 32 | <h2><a name="General">General overview</a></h2> |
| 33 | |
| 34 | <p>The module <code><a |
| 35 | href="http://xmlsoft.org/html/gnome-xml-xmlio.html">xmlIO.h</a></code> |
| 36 | provides the interfaces to the libxml I/O system. This consists of 3 main |
| 37 | parts:</p> |
| 38 | <ul> |
| 39 | <li>Input I/O buffers which are a commodity structure used by the parser(s) |
| 40 | input layer to handle fetching the informations to feed the parser. This |
| 41 | provides buffering and is also a placeholder where the encoding convertors |
| 42 | to UTF8 are piggy-backed.</li> |
| 43 | <li>Output I/O buffers are similar to the Input ones and fulfill similar |
| 44 | task but when generating a serialization from a tree.</li> |
| 45 | <li>A mechanism to register sets of I/O callbacks and associate them with |
| 46 | specific naming schemes like the protocol part of the URIs. |
| 47 | <p>This affect the default I/O operations and allows to use specific I/O |
| 48 | handlers for certain names.</p> |
| 49 | </li> |
| 50 | </ul> |
| 51 | |
| 52 | <p> The general mechanism used when loading http://rpmfind.net/xml.html for |
| 53 | example in the HTML parser is the following:</p> |
| 54 | <ol> |
| 55 | <li>the URI string is checked against the existing registered handlers using |
| 56 | their match() callback function, if the HTTP module was compiled in, it is |
| 57 | registered and its macth() function will succeed</li> |
| 58 | <li>the open() function of the handler is called and if successful will |
| 59 | return an I/O Input buffer</li> |
| 60 | <li>the parser will the start reading from this buffer and progressively |
| 61 | fetch information from the resource, calling the read() function of the |
| 62 | handler until the resource is exhausted</li> |
| 63 | <li>if an encoding change is detected it will be installed on the input |
| 64 | buffer, providing buffering and efficient use of the conversion |
| 65 | routines</li> |
| 66 | <li>once the parser has finished, the close() function of the handler is |
| 67 | called once and the Input buffer and associed resources are |
| 68 | deallocated.</li> |
| 69 | </ol> |
| 70 | |
| 71 | <p>The user defined callbacks are checked first to allow overriding of the |
| 72 | default libxml I/O routines.</p> |
| 73 | |
| 74 | <h2><a name="basic">The basic buffer type</a></h2> |
| 75 | |
| 76 | <p>All the buffer manipulation handling is done using the |
| 77 | <code>xmlBuffer</code> type define in <code><a |
| 78 | href="http://xmlsoft.org/html/gnome-xml-tree.html">tree.h</a> </code>which is |
| 79 | a resizable memory buffer. The buffer allocation strategy can be selected to |
| 80 | be either best-fit or use an exponential doubling one (CPU vs. memory use |
| 81 | tradeoff). The values are <code>XML_BUFFER_ALLOC_EXACT</code> and |
| 82 | <code>XML_BUFFER_ALLOC_DOUBLEIT</code>, and can be set individually or on a |
| 83 | system wide basis using <code>xmlBufferSetAllocationScheme()</code>. A number |
| 84 | of functions allows to manipulate buffers with names starting with the |
| 85 | <code>xmlBuffer...</code> prefix.</p> |
| 86 | |
| 87 | <h2><a name="Input">Input I/O handlers</a></h2> |
| 88 | |
| 89 | <p>An Input I/O handler is a simple structure |
| 90 | <code>xmlParserInputBuffer</code> containing a context associated to the |
| 91 | resource (file descriptor, or pointer to a protocol handler), the read() and |
| 92 | close() callbacks to use and an xmlBuffer. And extra xmlBuffer and a charset |
| 93 | encoding handler are also present to support charset conversion when |
| 94 | needed.</p> |
| 95 | |
| 96 | <h2><a name="Output">Output I/O handlers</a></h2> |
| 97 | |
| 98 | <p>An Output handler <code>xmlOutputBuffer</code> is completely similar to an |
| 99 | Input one except the callbacks are write() and close().</p> |
| 100 | |
| 101 | <h2><a name="Example">Example of customized I/O</a></h2> |
| 102 | |
| 103 | <p>This example come from <a href="http://xmlsoft.org/messages/0708.html">a |
| 104 | real use case</a>, xmlDocDump() closes the FILE * passed by the application |
| 105 | and this was a problem. The <a |
| 106 | href="http://xmlsoft.org/messages/0711.html">solution</a> was to redefine a |
| 107 | new output handler with the closing call deactivated:</p> |
| 108 | <ol> |
| 109 | <li>First define a new I/O ouput allocator where the output don't close the |
| 110 | file: |
| 111 | <pre>xmlOutputBufferPtr <br> |
| 112 | xmlOutputBufferCreateOwn(FILE *file, xmlCharEncodingHandlerPtr encoder) { <br> |
| 113 | xmlOutputBufferPtr ret; <br> |
| 114 | <br> |
| 115 | if (xmlOutputCallbackInitialized == 0) <br> |
| 116 | xmlRegisterDefaultOutputCallbacks(); <br> |
| 117 | <br> |
| 118 | if (file == NULL) return(NULL); <br> |
| 119 | </pre> |
| 120 | <pre> ret = xmlAllocOutputBuffer(encoder); <br> |
| 121 | if (ret != NULL) { <br> |
| 122 | ret->context = file; <br> |
| 123 | ret->writecallback = xmlFileWrite; <br> |
| 124 | ret->closecallback = NULL; /* No close callback */ <br> |
| 125 | } <br> |
| 126 | </pre> |
| 127 | <pre> return(ret); <br> |
| 128 | } </pre> |
| 129 | </li> |
| 130 | <li>And then use it to save the document: |
| 131 | <pre>FILE *f; |
| 132 | xmlOutputBufferPtr output;</pre> |
| 133 | <pre>xmlDocPtr doc; |
| 134 | int res; |
| 135 | <br> |
| 136 | f = ... |
| 137 | doc = .... |
| 138 | output = xmlOutputBufferCreateOwn(f, NULL); |
| 139 | <br> |
| 140 | res = xmlSaveFileTo(output, doc, NULL); |
| 141 | |
| 142 | </pre> |
| 143 | </li> |
| 144 | </ol> |
| 145 | |
| 146 | <p><a href="mailto:Daniel.Veillard@w3.org">Daniel Veillard</a></p> |
| 147 | |
| 148 | <p>$Id$</p> |
| 149 | </body> |
| 150 | </html> |