reference.html revision 1.1.1.8.2.2 1 1.1.1.8.2.1 martin <?xml version="1.0" encoding="utf-8"?>
2 1.1 tron <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
3 1.1.1.8.2.1 martin "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
4 1.1.1.8.2.1 martin <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5 1.1.1.8.2.1 martin <head>
6 1.1.1.8.2.1 martin <!--
7 1.1.1.6 christos __ __ _
8 1.1.1.6 christos ___\ \/ /_ __ __ _| |_
9 1.1.1.6 christos / _ \\ /| '_ \ / _` | __|
10 1.1.1.6 christos | __// \| |_) | (_| | |_
11 1.1.1.6 christos \___/_/\_\ .__/ \__,_|\__|
12 1.1.1.6 christos |_| XML parser
13 1.1.1.6 christos
14 1.1.1.6 christos Copyright (c) 2000 Clark Cooper <coopercc (a] users.sourceforge.net>
15 1.1.1.6 christos Copyright (c) 2000-2004 Fred L. Drake, Jr. <fdrake (a] users.sourceforge.net>
16 1.1.1.6 christos Copyright (c) 2002-2012 Karl Waclawek <karl (a] waclawek.net>
17 1.1.1.8.2.1 martin Copyright (c) 2017-2026 Sebastian Pipping <sebastian (a] pipping.org>
18 1.1.1.6 christos Copyright (c) 2017 Jakub Wilk <jwilk (a] jwilk.net>
19 1.1.1.6 christos Copyright (c) 2021 Tomas Korbar <tkorbar (a] redhat.com>
20 1.1.1.6 christos Copyright (c) 2021 Nicolas Cavallari <nicolas.cavallari (a] green-communications.fr>
21 1.1.1.7 wiz Copyright (c) 2022 Thijs Schreijer <thijs (a] thijsschreijer.nl>
22 1.1.1.8.2.1 martin Copyright (c) 2023-2025 Hanno Bck <hanno (a] gentoo.org>
23 1.1.1.7 wiz Copyright (c) 2023 Sony Corporation / Snild Dolkow <snild (a] sony.com>
24 1.1.1.6 christos Licensed under the MIT license:
25 1.1.1.6 christos
26 1.1.1.6 christos Permission is hereby granted, free of charge, to any person obtaining
27 1.1.1.6 christos a copy of this software and associated documentation files (the
28 1.1.1.6 christos "Software"), to deal in the Software without restriction, including
29 1.1.1.6 christos without limitation the rights to use, copy, modify, merge, publish,
30 1.1.1.6 christos distribute, sublicense, and/or sell copies of the Software, and to permit
31 1.1.1.6 christos persons to whom the Software is furnished to do so, subject to the
32 1.1.1.6 christos following conditions:
33 1.1.1.6 christos
34 1.1.1.6 christos The above copyright notice and this permission notice shall be included
35 1.1.1.6 christos in all copies or substantial portions of the Software.
36 1.1.1.6 christos
37 1.1.1.6 christos THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
38 1.1.1.6 christos EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
39 1.1.1.6 christos MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
40 1.1.1.6 christos NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
41 1.1.1.6 christos DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
42 1.1.1.6 christos OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
43 1.1.1.6 christos USE OR OTHER DEALINGS IN THE SOFTWARE.
44 1.1.1.6 christos -->
45 1.1.1.8.2.1 martin
46 1.1.1.8.2.1 martin <title>
47 1.1.1.8.2.1 martin Expat XML Parser
48 1.1.1.8.2.1 martin </title>
49 1.1.1.8.2.1 martin <meta name="author" content="Clark Cooper, coopercc (a] netheaven.com" />
50 1.1.1.8.2.1 martin <link href="ok.min.css" rel="stylesheet" />
51 1.1.1.8.2.1 martin <link href="style.css" rel="stylesheet" />
52 1.1.1.8.2.1 martin </head>
53 1.1.1.8.2.1 martin <body>
54 1.1.1.8.2.1 martin <div>
55 1.1.1.8.2.1 martin <h1>
56 1.1.1.8.2.2 martin The Expat XML Parser <small>Release 2.8.2</small>
57 1.1.1.8.2.1 martin </h1>
58 1.1.1.8.2.1 martin </div>
59 1.1.1.8.2.1 martin
60 1.1.1.8.2.1 martin <div class="content">
61 1.1.1.8.2.1 martin <p>
62 1.1.1.8.2.1 martin Expat is a library, written in C, for parsing XML documents. It's the underlying
63 1.1.1.8.2.1 martin XML parser for the open source Mozilla project, Perl's <code>XML::Parser</code>,
64 1.1.1.8.2.1 martin Python's <code>xml.parsers.expat</code>, and other open-source XML parsers.
65 1.1.1.8.2.1 martin </p>
66 1.1.1.8.2.1 martin
67 1.1.1.8.2.1 martin <p>
68 1.1.1.8.2.1 martin This library is the creation of James Clark, who's also given us groff (an nroff
69 1.1.1.8.2.1 martin look-alike), Jade (an implementation of ISO's DSSSL stylesheet language for
70 1.1.1.8.2.1 martin SGML), XP (a Java XML parser package), XT (a Java XSL engine). James was also the
71 1.1.1.8.2.1 martin technical lead on the XML Working Group at W3C that produced the XML
72 1.1.1.8.2.1 martin specification.
73 1.1.1.8.2.1 martin </p>
74 1.1.1.8.2.1 martin
75 1.1.1.8.2.1 martin <p>
76 1.1.1.8.2.1 martin This is free software, licensed under the <a href="../COPYING">MIT/X Consortium
77 1.1.1.8.2.1 martin license</a>. You may download it from <a href="https://libexpat.github.io/">the
78 1.1.1.8.2.1 martin Expat home page</a>.
79 1.1.1.8.2.1 martin </p>
80 1.1.1.8.2.1 martin
81 1.1.1.8.2.1 martin <p>
82 1.1.1.8.2.1 martin The bulk of this document was originally commissioned as an article by <a href=
83 1.1.1.8.2.1 martin "https://www.xml.com/">XML.com</a>. They graciously allowed Clark Cooper to
84 1.1.1.8.2.1 martin retain copyright and to distribute it with Expat. This version has been
85 1.1.1.8.2.1 martin substantially extended to include documentation on features which have been added
86 1.1.1.8.2.1 martin since the original article was published, and additional information on using the
87 1.1.1.8.2.1 martin original interface.
88 1.1.1.8.2.1 martin </p>
89 1.1.1.8.2.1 martin
90 1.1.1.8.2.1 martin <hr />
91 1.1.1.8.2.1 martin
92 1.1.1.8.2.1 martin <h2>
93 1.1.1.8.2.1 martin Table of Contents
94 1.1.1.8.2.1 martin </h2>
95 1.1.1.8.2.1 martin
96 1.1.1.6 christos <ul>
97 1.1.1.8.2.1 martin <li>
98 1.1.1.8.2.1 martin <a href="#overview">Overview</a>
99 1.1.1.8.2.1 martin </li>
100 1.1.1.8.2.1 martin
101 1.1.1.8.2.1 martin <li>
102 1.1.1.8.2.1 martin <a href="#building">Building and Installing</a>
103 1.1.1.8.2.1 martin </li>
104 1.1.1.8.2.1 martin
105 1.1.1.8.2.1 martin <li>
106 1.1.1.8.2.1 martin <a href="#using">Using Expat</a>
107 1.1.1.8.2.1 martin </li>
108 1.1.1.8.2.1 martin
109 1.1.1.8.2.1 martin <li>
110 1.1.1.8.2.1 martin <a href="#reference">Reference</a>
111 1.1.1.8.2.1 martin <ul>
112 1.1.1.8.2.1 martin <li>
113 1.1.1.8.2.1 martin <a href="#creation">Parser Creation Functions</a>
114 1.1.1.8.2.1 martin <ul>
115 1.1.1.8.2.1 martin <li>
116 1.1.1.8.2.1 martin <a href="#XML_ParserCreate">XML_ParserCreate</a>
117 1.1.1.8.2.1 martin </li>
118 1.1.1.8.2.1 martin
119 1.1.1.8.2.1 martin <li>
120 1.1.1.8.2.1 martin <a href="#XML_ParserCreateNS">XML_ParserCreateNS</a>
121 1.1.1.8.2.1 martin </li>
122 1.1.1.8.2.1 martin
123 1.1.1.8.2.1 martin <li>
124 1.1.1.8.2.1 martin <a href="#XML_ParserCreate_MM">XML_ParserCreate_MM</a>
125 1.1.1.8.2.1 martin </li>
126 1.1.1.8.2.1 martin
127 1.1.1.8.2.1 martin <li>
128 1.1.1.8.2.1 martin <a href=
129 1.1.1.8.2.1 martin "#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a>
130 1.1.1.8.2.1 martin </li>
131 1.1.1.8.2.1 martin
132 1.1.1.8.2.1 martin <li>
133 1.1.1.8.2.1 martin <a href="#XML_ParserFree">XML_ParserFree</a>
134 1.1.1.8.2.1 martin </li>
135 1.1.1.8.2.1 martin
136 1.1.1.8.2.1 martin <li>
137 1.1.1.8.2.1 martin <a href="#XML_ParserReset">XML_ParserReset</a>
138 1.1.1.8.2.1 martin </li>
139 1.1.1.8.2.1 martin </ul>
140 1.1.1.8.2.1 martin </li>
141 1.1.1.8.2.1 martin
142 1.1.1.8.2.1 martin <li>
143 1.1.1.8.2.1 martin <a href="#parsing">Parsing Functions</a>
144 1.1.1.8.2.1 martin <ul>
145 1.1.1.8.2.1 martin <li>
146 1.1.1.8.2.1 martin <a href="#XML_Parse">XML_Parse</a>
147 1.1.1.8.2.1 martin </li>
148 1.1.1.8.2.1 martin
149 1.1.1.8.2.1 martin <li>
150 1.1.1.8.2.1 martin <a href="#XML_ParseBuffer">XML_ParseBuffer</a>
151 1.1.1.8.2.1 martin </li>
152 1.1.1.8.2.1 martin
153 1.1.1.8.2.1 martin <li>
154 1.1.1.8.2.1 martin <a href="#XML_GetBuffer">XML_GetBuffer</a>
155 1.1.1.8.2.1 martin </li>
156 1.1.1.8.2.1 martin
157 1.1.1.8.2.1 martin <li>
158 1.1.1.8.2.1 martin <a href="#XML_StopParser">XML_StopParser</a>
159 1.1.1.8.2.1 martin </li>
160 1.1.1.8.2.1 martin
161 1.1.1.8.2.1 martin <li>
162 1.1.1.8.2.1 martin <a href="#XML_ResumeParser">XML_ResumeParser</a>
163 1.1.1.8.2.1 martin </li>
164 1.1.1.8.2.1 martin
165 1.1.1.8.2.1 martin <li>
166 1.1.1.8.2.1 martin <a href="#XML_GetParsingStatus">XML_GetParsingStatus</a>
167 1.1.1.8.2.1 martin </li>
168 1.1.1.8.2.1 martin </ul>
169 1.1.1.8.2.1 martin </li>
170 1.1.1.8.2.1 martin
171 1.1.1.8.2.1 martin <li>
172 1.1.1.8.2.1 martin <a href="#setting">Handler Setting Functions</a>
173 1.1.1.8.2.1 martin <ul>
174 1.1.1.8.2.1 martin <li>
175 1.1.1.8.2.1 martin <a href="#XML_SetStartElementHandler">XML_SetStartElementHandler</a>
176 1.1.1.8.2.1 martin </li>
177 1.1.1.8.2.1 martin
178 1.1.1.8.2.1 martin <li>
179 1.1.1.8.2.1 martin <a href="#XML_SetEndElementHandler">XML_SetEndElementHandler</a>
180 1.1.1.8.2.1 martin </li>
181 1.1.1.8.2.1 martin
182 1.1.1.8.2.1 martin <li>
183 1.1.1.8.2.1 martin <a href="#XML_SetElementHandler">XML_SetElementHandler</a>
184 1.1.1.8.2.1 martin </li>
185 1.1.1.8.2.1 martin
186 1.1.1.8.2.1 martin <li>
187 1.1.1.8.2.1 martin <a href="#XML_SetCharacterDataHandler">XML_SetCharacterDataHandler</a>
188 1.1.1.8.2.1 martin </li>
189 1.1.1.8.2.1 martin
190 1.1.1.8.2.1 martin <li>
191 1.1.1.8.2.1 martin <a href=
192 1.1.1.8.2.1 martin "#XML_SetProcessingInstructionHandler">XML_SetProcessingInstructionHandler</a>
193 1.1.1.8.2.1 martin </li>
194 1.1.1.8.2.1 martin
195 1.1.1.8.2.1 martin <li>
196 1.1.1.8.2.1 martin <a href="#XML_SetCommentHandler">XML_SetCommentHandler</a>
197 1.1.1.8.2.1 martin </li>
198 1.1.1.8.2.1 martin
199 1.1.1.8.2.1 martin <li>
200 1.1.1.8.2.1 martin <a href=
201 1.1.1.8.2.1 martin "#XML_SetStartCdataSectionHandler">XML_SetStartCdataSectionHandler</a>
202 1.1.1.8.2.1 martin </li>
203 1.1.1.8.2.1 martin
204 1.1.1.8.2.1 martin <li>
205 1.1.1.8.2.1 martin <a href=
206 1.1.1.8.2.1 martin "#XML_SetEndCdataSectionHandler">XML_SetEndCdataSectionHandler</a>
207 1.1.1.8.2.1 martin </li>
208 1.1.1.8.2.1 martin
209 1.1.1.8.2.1 martin <li>
210 1.1.1.8.2.1 martin <a href="#XML_SetCdataSectionHandler">XML_SetCdataSectionHandler</a>
211 1.1.1.8.2.1 martin </li>
212 1.1.1.8.2.1 martin
213 1.1.1.8.2.1 martin <li>
214 1.1.1.8.2.1 martin <a href="#XML_SetDefaultHandler">XML_SetDefaultHandler</a>
215 1.1.1.8.2.1 martin </li>
216 1.1.1.8.2.1 martin
217 1.1.1.8.2.1 martin <li>
218 1.1.1.8.2.1 martin <a href="#XML_SetDefaultHandlerExpand">XML_SetDefaultHandlerExpand</a>
219 1.1.1.8.2.1 martin </li>
220 1.1.1.8.2.1 martin
221 1.1.1.8.2.1 martin <li>
222 1.1.1.8.2.1 martin <a href=
223 1.1.1.8.2.1 martin "#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a>
224 1.1.1.8.2.1 martin </li>
225 1.1.1.8.2.1 martin
226 1.1.1.8.2.1 martin <li>
227 1.1.1.8.2.1 martin <a href=
228 1.1.1.8.2.1 martin "#XML_SetExternalEntityRefHandlerArg">XML_SetExternalEntityRefHandlerArg</a>
229 1.1.1.8.2.1 martin </li>
230 1.1.1.8.2.1 martin
231 1.1.1.8.2.1 martin <li>
232 1.1.1.8.2.1 martin <a href="#XML_SetSkippedEntityHandler">XML_SetSkippedEntityHandler</a>
233 1.1.1.8.2.1 martin </li>
234 1.1.1.8.2.1 martin
235 1.1.1.8.2.1 martin <li>
236 1.1.1.8.2.1 martin <a href=
237 1.1.1.8.2.1 martin "#XML_SetUnknownEncodingHandler">XML_SetUnknownEncodingHandler</a>
238 1.1.1.8.2.1 martin </li>
239 1.1.1.8.2.1 martin
240 1.1.1.8.2.1 martin <li>
241 1.1.1.8.2.1 martin <a href=
242 1.1.1.8.2.1 martin "#XML_SetStartNamespaceDeclHandler">XML_SetStartNamespaceDeclHandler</a>
243 1.1.1.8.2.1 martin </li>
244 1.1.1.8.2.1 martin
245 1.1.1.8.2.1 martin <li>
246 1.1.1.8.2.1 martin <a href=
247 1.1.1.8.2.1 martin "#XML_SetEndNamespaceDeclHandler">XML_SetEndNamespaceDeclHandler</a>
248 1.1.1.8.2.1 martin </li>
249 1.1.1.8.2.1 martin
250 1.1.1.8.2.1 martin <li>
251 1.1.1.8.2.1 martin <a href="#XML_SetNamespaceDeclHandler">XML_SetNamespaceDeclHandler</a>
252 1.1.1.8.2.1 martin </li>
253 1.1.1.8.2.1 martin
254 1.1.1.8.2.1 martin <li>
255 1.1.1.8.2.1 martin <a href="#XML_SetXmlDeclHandler">XML_SetXmlDeclHandler</a>
256 1.1.1.8.2.1 martin </li>
257 1.1.1.8.2.1 martin
258 1.1.1.8.2.1 martin <li>
259 1.1.1.8.2.1 martin <a href=
260 1.1.1.8.2.1 martin "#XML_SetStartDoctypeDeclHandler">XML_SetStartDoctypeDeclHandler</a>
261 1.1.1.8.2.1 martin </li>
262 1.1.1.8.2.1 martin
263 1.1.1.8.2.1 martin <li>
264 1.1.1.8.2.1 martin <a href=
265 1.1.1.8.2.1 martin "#XML_SetEndDoctypeDeclHandler">XML_SetEndDoctypeDeclHandler</a>
266 1.1.1.8.2.1 martin </li>
267 1.1.1.8.2.1 martin
268 1.1.1.8.2.1 martin <li>
269 1.1.1.8.2.1 martin <a href="#XML_SetDoctypeDeclHandler">XML_SetDoctypeDeclHandler</a>
270 1.1.1.8.2.1 martin </li>
271 1.1.1.8.2.1 martin
272 1.1.1.8.2.1 martin <li>
273 1.1.1.8.2.1 martin <a href="#XML_SetElementDeclHandler">XML_SetElementDeclHandler</a>
274 1.1.1.8.2.1 martin </li>
275 1.1.1.8.2.1 martin
276 1.1.1.8.2.1 martin <li>
277 1.1.1.8.2.1 martin <a href="#XML_SetAttlistDeclHandler">XML_SetAttlistDeclHandler</a>
278 1.1.1.8.2.1 martin </li>
279 1.1.1.8.2.1 martin
280 1.1.1.8.2.1 martin <li>
281 1.1.1.8.2.1 martin <a href="#XML_SetEntityDeclHandler">XML_SetEntityDeclHandler</a>
282 1.1.1.8.2.1 martin </li>
283 1.1.1.8.2.1 martin
284 1.1.1.8.2.1 martin <li>
285 1.1.1.8.2.1 martin <a href=
286 1.1.1.8.2.1 martin "#XML_SetUnparsedEntityDeclHandler">XML_SetUnparsedEntityDeclHandler</a>
287 1.1.1.8.2.1 martin </li>
288 1.1.1.8.2.1 martin
289 1.1.1.8.2.1 martin <li>
290 1.1.1.8.2.1 martin <a href="#XML_SetNotationDeclHandler">XML_SetNotationDeclHandler</a>
291 1.1.1.8.2.1 martin </li>
292 1.1.1.8.2.1 martin
293 1.1.1.8.2.1 martin <li>
294 1.1.1.8.2.1 martin <a href="#XML_SetNotStandaloneHandler">XML_SetNotStandaloneHandler</a>
295 1.1.1.8.2.1 martin </li>
296 1.1.1.8.2.1 martin </ul>
297 1.1.1.8.2.1 martin </li>
298 1.1.1.8.2.1 martin
299 1.1.1.8.2.1 martin <li>
300 1.1.1.8.2.1 martin <a href="#position">Parse Position and Error Reporting Functions</a>
301 1.1.1.8.2.1 martin <ul>
302 1.1.1.8.2.1 martin <li>
303 1.1.1.8.2.1 martin <a href="#XML_GetErrorCode">XML_GetErrorCode</a>
304 1.1.1.8.2.1 martin </li>
305 1.1.1.8.2.1 martin
306 1.1.1.8.2.1 martin <li>
307 1.1.1.8.2.1 martin <a href="#XML_ErrorString">XML_ErrorString</a>
308 1.1.1.8.2.1 martin </li>
309 1.1.1.8.2.1 martin
310 1.1.1.8.2.1 martin <li>
311 1.1.1.8.2.1 martin <a href="#XML_GetCurrentByteIndex">XML_GetCurrentByteIndex</a>
312 1.1.1.8.2.1 martin </li>
313 1.1.1.8.2.1 martin
314 1.1.1.8.2.1 martin <li>
315 1.1.1.8.2.1 martin <a href="#XML_GetCurrentLineNumber">XML_GetCurrentLineNumber</a>
316 1.1.1.8.2.1 martin </li>
317 1.1.1.8.2.1 martin
318 1.1.1.8.2.1 martin <li>
319 1.1.1.8.2.1 martin <a href="#XML_GetCurrentColumnNumber">XML_GetCurrentColumnNumber</a>
320 1.1.1.8.2.1 martin </li>
321 1.1.1.8.2.1 martin
322 1.1.1.8.2.1 martin <li>
323 1.1.1.8.2.1 martin <a href="#XML_GetCurrentByteCount">XML_GetCurrentByteCount</a>
324 1.1.1.8.2.1 martin </li>
325 1.1.1.8.2.1 martin
326 1.1.1.8.2.1 martin <li>
327 1.1.1.8.2.1 martin <a href="#XML_GetInputContext">XML_GetInputContext</a>
328 1.1.1.8.2.1 martin </li>
329 1.1.1.8.2.1 martin </ul>
330 1.1.1.8.2.1 martin </li>
331 1.1.1.8.2.1 martin
332 1.1.1.8.2.1 martin <li>
333 1.1.1.8.2.1 martin <a href="#attack-protection">Attack Protection</a>
334 1.1.1.8.2.1 martin <ul>
335 1.1.1.8.2.1 martin <li>
336 1.1.1.8.2.1 martin <a href=
337 1.1.1.8.2.1 martin "#XML_SetBillionLaughsAttackProtectionMaximumAmplification">XML_SetBillionLaughsAttackProtectionMaximumAmplification</a>
338 1.1.1.8.2.1 martin </li>
339 1.1.1.8.2.1 martin
340 1.1.1.8.2.1 martin <li>
341 1.1.1.8.2.1 martin <a href=
342 1.1.1.8.2.1 martin "#XML_SetBillionLaughsAttackProtectionActivationThreshold">XML_SetBillionLaughsAttackProtectionActivationThreshold</a>
343 1.1.1.8.2.1 martin </li>
344 1.1.1.8.2.1 martin
345 1.1.1.8.2.1 martin <li>
346 1.1.1.8.2.1 martin <a href=
347 1.1.1.8.2.1 martin "#XML_SetAllocTrackerMaximumAmplification">XML_SetAllocTrackerMaximumAmplification</a>
348 1.1.1.8.2.1 martin </li>
349 1.1.1.8.2.1 martin
350 1.1.1.8.2.1 martin <li>
351 1.1.1.8.2.1 martin <a href=
352 1.1.1.8.2.1 martin "#XML_SetAllocTrackerActivationThreshold">XML_SetAllocTrackerActivationThreshold</a>
353 1.1.1.8.2.1 martin </li>
354 1.1.1.8.2.1 martin
355 1.1.1.8.2.1 martin <li>
356 1.1.1.8.2.1 martin <a href=
357 1.1.1.8.2.1 martin "#XML_SetReparseDeferralEnabled">XML_SetReparseDeferralEnabled</a>
358 1.1.1.8.2.1 martin </li>
359 1.1.1.8.2.1 martin </ul>
360 1.1.1.8.2.1 martin </li>
361 1.1.1.8.2.1 martin
362 1.1.1.8.2.1 martin <li>
363 1.1.1.8.2.1 martin <a href="#miscellaneous">Miscellaneous Functions</a>
364 1.1.1.8.2.1 martin <ul>
365 1.1.1.8.2.1 martin <li>
366 1.1.1.8.2.1 martin <a href="#XML_SetUserData">XML_SetUserData</a>
367 1.1.1.8.2.1 martin </li>
368 1.1.1.8.2.1 martin
369 1.1.1.8.2.1 martin <li>
370 1.1.1.8.2.1 martin <a href="#XML_GetUserData">XML_GetUserData</a>
371 1.1.1.8.2.1 martin </li>
372 1.1.1.8.2.1 martin
373 1.1.1.8.2.1 martin <li>
374 1.1.1.8.2.1 martin <a href="#XML_UseParserAsHandlerArg">XML_UseParserAsHandlerArg</a>
375 1.1.1.8.2.1 martin </li>
376 1.1.1.8.2.1 martin
377 1.1.1.8.2.1 martin <li>
378 1.1.1.8.2.1 martin <a href="#XML_SetBase">XML_SetBase</a>
379 1.1.1.8.2.1 martin </li>
380 1.1.1.8.2.1 martin
381 1.1.1.8.2.1 martin <li>
382 1.1.1.8.2.1 martin <a href="#XML_GetBase">XML_GetBase</a>
383 1.1.1.8.2.1 martin </li>
384 1.1.1.8.2.1 martin
385 1.1.1.8.2.1 martin <li>
386 1.1.1.8.2.1 martin <a href=
387 1.1.1.8.2.1 martin "#XML_GetSpecifiedAttributeCount">XML_GetSpecifiedAttributeCount</a>
388 1.1.1.8.2.1 martin </li>
389 1.1.1.8.2.1 martin
390 1.1.1.8.2.1 martin <li>
391 1.1.1.8.2.1 martin <a href="#XML_GetIdAttributeIndex">XML_GetIdAttributeIndex</a>
392 1.1.1.8.2.1 martin </li>
393 1.1.1.8.2.1 martin
394 1.1.1.8.2.1 martin <li>
395 1.1.1.8.2.1 martin <a href="#XML_GetAttributeInfo">XML_GetAttributeInfo</a>
396 1.1.1.8.2.1 martin </li>
397 1.1.1.8.2.1 martin
398 1.1.1.8.2.1 martin <li>
399 1.1.1.8.2.1 martin <a href="#XML_SetEncoding">XML_SetEncoding</a>
400 1.1.1.8.2.1 martin </li>
401 1.1.1.8.2.1 martin
402 1.1.1.8.2.1 martin <li>
403 1.1.1.8.2.1 martin <a href="#XML_SetParamEntityParsing">XML_SetParamEntityParsing</a>
404 1.1.1.8.2.1 martin </li>
405 1.1.1.8.2.1 martin
406 1.1.1.8.2.1 martin <li>
407 1.1.1.8.2.1 martin <a href="#XML_SetHashSalt">XML_SetHashSalt</a> (deprecated)
408 1.1.1.8.2.1 martin </li>
409 1.1.1.8.2.1 martin
410 1.1.1.8.2.1 martin <li>
411 1.1.1.8.2.1 martin <a href="#XML_SetHashSalt16Bytes">XML_SetHashSalt16Bytes</a>
412 1.1.1.8.2.1 martin </li>
413 1.1.1.8.2.1 martin
414 1.1.1.8.2.1 martin <li>
415 1.1.1.8.2.1 martin <a href="#XML_UseForeignDTD">XML_UseForeignDTD</a>
416 1.1.1.8.2.1 martin </li>
417 1.1.1.8.2.1 martin
418 1.1.1.8.2.1 martin <li>
419 1.1.1.8.2.1 martin <a href="#XML_SetReturnNSTriplet">XML_SetReturnNSTriplet</a>
420 1.1.1.8.2.1 martin </li>
421 1.1.1.8.2.1 martin
422 1.1.1.8.2.1 martin <li>
423 1.1.1.8.2.1 martin <a href="#XML_DefaultCurrent">XML_DefaultCurrent</a>
424 1.1.1.8.2.1 martin </li>
425 1.1.1.8.2.1 martin
426 1.1.1.8.2.1 martin <li>
427 1.1.1.8.2.1 martin <a href="#XML_ExpatVersion">XML_ExpatVersion</a>
428 1.1.1.8.2.1 martin </li>
429 1.1.1.8.2.1 martin
430 1.1.1.8.2.1 martin <li>
431 1.1.1.8.2.1 martin <a href="#XML_ExpatVersionInfo">XML_ExpatVersionInfo</a>
432 1.1.1.8.2.1 martin </li>
433 1.1.1.8.2.1 martin
434 1.1.1.8.2.1 martin <li>
435 1.1.1.8.2.1 martin <a href="#XML_GetFeatureList">XML_GetFeatureList</a>
436 1.1.1.8.2.1 martin </li>
437 1.1.1.8.2.1 martin
438 1.1.1.8.2.1 martin <li>
439 1.1.1.8.2.1 martin <a href="#XML_FreeContentModel">XML_FreeContentModel</a>
440 1.1.1.8.2.1 martin </li>
441 1.1.1.8.2.1 martin
442 1.1.1.8.2.1 martin <li>
443 1.1.1.8.2.1 martin <a href="#XML_MemMalloc">XML_MemMalloc</a>
444 1.1.1.8.2.1 martin </li>
445 1.1.1.8.2.1 martin
446 1.1.1.8.2.1 martin <li>
447 1.1.1.8.2.1 martin <a href="#XML_MemRealloc">XML_MemRealloc</a>
448 1.1.1.8.2.1 martin </li>
449 1.1.1.8.2.1 martin
450 1.1.1.8.2.1 martin <li>
451 1.1.1.8.2.1 martin <a href="#XML_MemFree">XML_MemFree</a>
452 1.1.1.8.2.1 martin </li>
453 1.1.1.8.2.1 martin </ul>
454 1.1.1.8.2.1 martin </li>
455 1.1.1.8.2.1 martin </ul>
456 1.1.1.8.2.1 martin </li>
457 1.1.1.6 christos </ul>
458 1.1 tron
459 1.1.1.8.2.1 martin <hr />
460 1.1.1.8.2.1 martin
461 1.1.1.8.2.1 martin <h2>
462 1.1.1.8.2.1 martin <a id="overview" name="overview">Overview</a>
463 1.1.1.8.2.1 martin </h2>
464 1.1.1.8.2.1 martin
465 1.1.1.8.2.1 martin <p>
466 1.1.1.8.2.1 martin Expat is a stream-oriented parser. You register callback (or handler) functions
467 1.1.1.8.2.1 martin with the parser and then start feeding it the document. As the parser recognizes
468 1.1.1.8.2.1 martin parts of the document, it will call the appropriate handler for that part (if
469 1.1.1.8.2.1 martin you've registered one.) The document is fed to the parser in pieces, so you can
470 1.1.1.8.2.1 martin start parsing before you have all the document. This also allows you to parse
471 1.1.1.8.2.1 martin really huge documents that won't fit into memory.
472 1.1.1.8.2.1 martin </p>
473 1.1.1.8.2.1 martin
474 1.1.1.8.2.1 martin <p>
475 1.1.1.8.2.1 martin Expat can be intimidating due to the many kinds of handlers and options you can
476 1.1.1.8.2.1 martin set. But you only need to learn four functions in order to do 90% of what you'll
477 1.1.1.8.2.1 martin want to do with it:
478 1.1.1.8.2.1 martin </p>
479 1.1.1.8.2.1 martin
480 1.1.1.8.2.1 martin <dl>
481 1.1.1.8.2.1 martin <dt>
482 1.1.1.8.2.1 martin <code><a href="#XML_ParserCreate">XML_ParserCreate</a></code>
483 1.1.1.8.2.1 martin </dt>
484 1.1.1.8.2.1 martin
485 1.1.1.8.2.1 martin <dd>
486 1.1.1.8.2.1 martin Create a new parser object.
487 1.1.1.8.2.1 martin </dd>
488 1.1.1.8.2.1 martin
489 1.1.1.8.2.1 martin <dt>
490 1.1.1.8.2.1 martin <code><a href="#XML_SetElementHandler">XML_SetElementHandler</a></code>
491 1.1.1.8.2.1 martin </dt>
492 1.1.1.8.2.1 martin
493 1.1.1.8.2.1 martin <dd>
494 1.1.1.8.2.1 martin Set handlers for start and end tags.
495 1.1.1.8.2.1 martin </dd>
496 1.1.1.8.2.1 martin
497 1.1.1.8.2.1 martin <dt>
498 1.1.1.8.2.1 martin <code><a href=
499 1.1.1.8.2.1 martin "#XML_SetCharacterDataHandler">XML_SetCharacterDataHandler</a></code>
500 1.1.1.8.2.1 martin </dt>
501 1.1.1.8.2.1 martin
502 1.1.1.8.2.1 martin <dd>
503 1.1.1.8.2.1 martin Set handler for text.
504 1.1.1.8.2.1 martin </dd>
505 1.1.1.8.2.1 martin
506 1.1.1.8.2.1 martin <dt>
507 1.1.1.8.2.1 martin <code><a href="#XML_Parse">XML_Parse</a></code>
508 1.1.1.8.2.1 martin </dt>
509 1.1.1.8.2.1 martin
510 1.1.1.8.2.1 martin <dd>
511 1.1.1.8.2.1 martin Pass a buffer full of document to the parser
512 1.1.1.8.2.1 martin </dd>
513 1.1.1.8.2.1 martin </dl>
514 1.1.1.8.2.1 martin
515 1.1.1.8.2.1 martin <p>
516 1.1.1.8.2.1 martin These functions and others are described in the <a href=
517 1.1.1.8.2.1 martin "#reference">reference</a> part of this document. The reference section also
518 1.1.1.8.2.1 martin describes in detail the parameters passed to the different types of handlers.
519 1.1.1.8.2.1 martin </p>
520 1.1.1.8.2.1 martin
521 1.1.1.8.2.1 martin <p>
522 1.1.1.8.2.1 martin Let's look at a very simple example program that only uses 3 of the above
523 1.1.1.8.2.1 martin functions (it doesn't need to set a character handler.) The program <a href=
524 1.1.1.8.2.1 martin "../examples/outline.c">outline.c</a> prints an element outline, indenting child
525 1.1.1.8.2.1 martin elements to distinguish them from the parent element that contains them. The
526 1.1.1.8.2.1 martin start handler does all the work. It prints two indenting spaces for every level
527 1.1.1.8.2.1 martin of ancestor elements, then it prints the element and attribute information.
528 1.1.1.8.2.1 martin Finally it increments the global <code>Depth</code> variable.
529 1.1.1.8.2.1 martin </p>
530 1.1.1.8.2.1 martin
531 1.1.1.8.2.1 martin <pre class="eg">
532 1.1 tron int Depth;
533 1.1 tron
534 1.1 tron void XMLCALL
535 1.1 tron start(void *data, const char *el, const char **attr) {
536 1.1 tron int i;
537 1.1 tron
538 1.1 tron for (i = 0; i < Depth; i++)
539 1.1 tron printf(" ");
540 1.1 tron
541 1.1 tron printf("%s", el);
542 1.1 tron
543 1.1 tron for (i = 0; attr[i]; i += 2) {
544 1.1 tron printf(" %s='%s'", attr[i], attr[i + 1]);
545 1.1 tron }
546 1.1 tron
547 1.1 tron printf("\n");
548 1.1 tron Depth++;
549 1.1 tron } /* End of start handler */
550 1.1 tron </pre>
551 1.1.1.8.2.1 martin <p>
552 1.1.1.8.2.1 martin The end tag simply does the bookkeeping work of decrementing <code>Depth</code>.
553 1.1.1.8.2.1 martin </p>
554 1.1 tron
555 1.1.1.8.2.1 martin <pre class="eg">
556 1.1 tron void XMLCALL
557 1.1 tron end(void *data, const char *el) {
558 1.1 tron Depth--;
559 1.1 tron } /* End of end handler */
560 1.1 tron </pre>
561 1.1.1.8.2.1 martin <p>
562 1.1.1.8.2.1 martin Note the <code>XMLCALL</code> annotation used for the callbacks. This is used to
563 1.1.1.8.2.1 martin ensure that the Expat and the callbacks are using the same calling convention in
564 1.1.1.8.2.1 martin case the compiler options used for Expat itself and the client code are
565 1.1.1.8.2.1 martin different. Expat tries not to care what the default calling convention is, though
566 1.1.1.8.2.1 martin it may require that it be compiled with a default convention of "cdecl" on some
567 1.1.1.8.2.1 martin platforms. For code which uses Expat, however, the calling convention is
568 1.1.1.8.2.1 martin specified by the <code>XMLCALL</code> annotation on most platforms; callbacks
569 1.1.1.8.2.1 martin should be defined using this annotation.
570 1.1.1.8.2.1 martin </p>
571 1.1.1.8.2.1 martin
572 1.1.1.8.2.1 martin <p>
573 1.1.1.8.2.1 martin The <code>XMLCALL</code> annotation was added in Expat 1.95.7, but existing
574 1.1.1.8.2.1 martin working Expat applications don't need to add it (since they are already using the
575 1.1.1.8.2.1 martin "cdecl" calling convention, or they wouldn't be working). The annotation is only
576 1.1.1.8.2.1 martin needed if the default calling convention may be something other than "cdecl". To
577 1.1.1.8.2.1 martin use the annotation safely with older versions of Expat, you can conditionally
578 1.1.1.8.2.1 martin define it <em>after</em> including Expat's header file:
579 1.1.1.8.2.1 martin </p>
580 1.1 tron
581 1.1.1.8.2.1 martin <pre class="eg">
582 1.1 tron #include <expat.h>
583 1.1 tron
584 1.1 tron #ifndef XMLCALL
585 1.1.1.8.2.1 martin #if defined(_MSC_VER) && !defined(__BEOS__) && !defined(__CYGWIN__)
586 1.1 tron #define XMLCALL __cdecl
587 1.1 tron #elif defined(__GNUC__)
588 1.1 tron #define XMLCALL __attribute__((cdecl))
589 1.1 tron #else
590 1.1 tron #define XMLCALL
591 1.1 tron #endif
592 1.1 tron #endif
593 1.1 tron </pre>
594 1.1.1.8.2.1 martin <p>
595 1.1.1.8.2.1 martin After creating the parser, the main program just has the job of shoveling the
596 1.1.1.8.2.1 martin document to the parser so that it can do its work.
597 1.1.1.8.2.1 martin </p>
598 1.1.1.8.2.1 martin
599 1.1.1.8.2.1 martin <hr />
600 1.1.1.8.2.1 martin
601 1.1.1.8.2.1 martin <h2>
602 1.1.1.8.2.1 martin <a id="building" name="building">Building and Installing Expat</a>
603 1.1.1.8.2.1 martin </h2>
604 1.1.1.8.2.1 martin
605 1.1.1.8.2.1 martin <p>
606 1.1.1.8.2.1 martin The Expat distribution comes as a compressed (with GNU gzip) tar file. You may
607 1.1.1.8.2.1 martin download the latest version from <a href=
608 1.1.1.8.2.1 martin "https://sourceforge.net/projects/expat/">Source Forge</a>. After unpacking this,
609 1.1.1.8.2.1 martin cd into the directory. Then follow either the Win32 directions or Unix directions
610 1.1.1.8.2.1 martin below.
611 1.1.1.8.2.1 martin </p>
612 1.1.1.8.2.1 martin
613 1.1.1.8.2.1 martin <h3>
614 1.1.1.8.2.1 martin Building under Win32
615 1.1.1.8.2.1 martin </h3>
616 1.1.1.8.2.1 martin
617 1.1.1.8.2.1 martin <p>
618 1.1.1.8.2.1 martin If you're using the GNU compiler under cygwin, follow the Unix directions in the
619 1.1.1.8.2.1 martin next section. Otherwise if you have Microsoft's Developer Studio installed, you
620 1.1.1.8.2.1 martin can use CMake to generate a <code>.sln</code> file, e.g. <code>cmake -G"Visual
621 1.1.1.8.2.1 martin Studio 17 2022" -DCMAKE_BUILD_TYPE=RelWithDebInfo .</code> , and build Expat
622 1.1.1.8.2.1 martin using <code>msbuild /m expat.sln</code> after.
623 1.1.1.8.2.1 martin </p>
624 1.1.1.8.2.1 martin
625 1.1.1.8.2.1 martin <p>
626 1.1.1.8.2.1 martin Alternatively, you may download the Win32 binary package that contains the
627 1.1.1.8.2.1 martin "expat.h" include file and a pre-built DLL.
628 1.1.1.8.2.1 martin </p>
629 1.1.1.8.2.1 martin
630 1.1.1.8.2.1 martin <h3>
631 1.1.1.8.2.1 martin Building under Unix (or GNU)
632 1.1.1.8.2.1 martin </h3>
633 1.1.1.8.2.1 martin
634 1.1.1.8.2.1 martin <p>
635 1.1.1.8.2.1 martin First you'll need to run the configure shell script in order to configure the
636 1.1.1.8.2.1 martin Makefiles and headers for your system.
637 1.1.1.8.2.1 martin </p>
638 1.1.1.8.2.1 martin
639 1.1.1.8.2.1 martin <p>
640 1.1.1.8.2.1 martin If you're happy with all the defaults that configure picks for you, and you have
641 1.1.1.8.2.1 martin permission on your system to install into /usr/local, you can install Expat with
642 1.1.1.8.2.1 martin this sequence of commands:
643 1.1.1.8.2.1 martin </p>
644 1.1 tron
645 1.1.1.8.2.1 martin <pre class="eg">
646 1.1 tron ./configure
647 1.1 tron make
648 1.1 tron make install
649 1.1 tron </pre>
650 1.1.1.8.2.1 martin <p>
651 1.1.1.8.2.1 martin There are some options that you can provide to this script, but the only one
652 1.1.1.8.2.1 martin we'll mention here is the <code>--prefix</code> option. You can find out all the
653 1.1.1.8.2.1 martin options available by running configure with just the <code>--help</code> option.
654 1.1.1.8.2.1 martin </p>
655 1.1.1.8.2.1 martin
656 1.1.1.8.2.1 martin <p>
657 1.1.1.8.2.1 martin By default, the configure script sets things up so that the library gets
658 1.1.1.8.2.1 martin installed in <code>/usr/local/lib</code> and the associated header file in
659 1.1.1.8.2.1 martin <code>/usr/local/include</code>. But if you were to give the option,
660 1.1.1.8.2.1 martin <code>--prefix=/home/me/mystuff</code>, then the library and header would get
661 1.1.1.8.2.1 martin installed in <code>/home/me/mystuff/lib</code> and
662 1.1.1.8.2.1 martin <code>/home/me/mystuff/include</code> respectively.
663 1.1.1.8.2.1 martin </p>
664 1.1.1.8.2.1 martin
665 1.1.1.8.2.1 martin <h3>
666 1.1.1.8.2.1 martin Configuring Expat Using the Pre-Processor
667 1.1.1.8.2.1 martin </h3>
668 1.1.1.8.2.1 martin
669 1.1.1.8.2.1 martin <p>
670 1.1.1.8.2.1 martin Expat's feature set can be configured using a small number of pre-processor
671 1.1.1.8.2.1 martin definitions. The symbols are:
672 1.1.1.8.2.1 martin </p>
673 1.1.1.8.2.1 martin
674 1.1.1.8.2.1 martin <dl class="cpp-symbols">
675 1.1.1.8.2.1 martin <dt>
676 1.1.1.8.2.1 martin <a id="XML_GE" name="XML_GE">XML_GE</a>
677 1.1.1.8.2.1 martin </dt>
678 1.1.1.8.2.1 martin
679 1.1.1.8.2.1 martin <dd>
680 1.1.1.8.2.1 martin Added in Expat 2.6.0. Include support for <a href=
681 1.1.1.8.2.1 martin "https://www.w3.org/TR/2006/REC-xml-20060816/#sec-physical-struct">general
682 1.1.1.8.2.1 martin entities</a> (syntax <code>&e1;</code> to reference and syntax
683 1.1.1.8.2.1 martin <code><!ENTITY e1 'value1'></code> (an internal general entity) or
684 1.1.1.8.2.1 martin <code><!ENTITY e2 SYSTEM 'file2'></code> (an external general entity) to
685 1.1.1.8.2.1 martin declare). With <code>XML_GE</code> enabled, general entities will be replaced
686 1.1.1.8.2.1 martin by their declared replacement text; for this to work for <em>external</em>
687 1.1.1.8.2.1 martin general entities, in addition an <code><a href=
688 1.1.1.8.2.1 martin "#XML_SetExternalEntityRefHandler">XML_ExternalEntityRefHandler</a></code> must
689 1.1.1.8.2.1 martin be set using <code><a href=
690 1.1.1.8.2.1 martin "#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a></code>.
691 1.1.1.8.2.1 martin Also, enabling <code>XML_GE</code> makes the functions <code><a href=
692 1.1.1.8.2.1 martin "#XML_SetBillionLaughsAttackProtectionMaximumAmplification">XML_SetBillionLaughsAttackProtectionMaximumAmplification</a></code>
693 1.1.1.8.2.1 martin and <code><a href=
694 1.1.1.8.2.1 martin "#XML_SetBillionLaughsAttackProtectionActivationThreshold">XML_SetBillionLaughsAttackProtectionActivationThreshold</a></code>
695 1.1.1.8.2.1 martin available.<br />
696 1.1.1.8.2.1 martin With <code>XML_GE</code> disabled, Expat has a smaller memory footprint and can
697 1.1.1.8.2.1 martin be faster, but will not load external general entities and will replace all
698 1.1.1.8.2.1 martin general entities (except the <a href=
699 1.1.1.8.2.1 martin "https://www.w3.org/TR/2006/REC-xml-20060816/#sec-predefined-ent">predefined
700 1.1.1.8.2.1 martin five</a>: <code>amp</code>, <code>apos</code>, <code>gt</code>,
701 1.1.1.8.2.1 martin <code>lt</code>, <code>quot</code>) with a self-reference: for example,
702 1.1.1.8.2.1 martin referencing an entity <code>e1</code> via <code>&e1;</code> will be
703 1.1.1.8.2.1 martin replaced by text <code>&e1;</code>.
704 1.1.1.8.2.1 martin </dd>
705 1.1.1.8.2.1 martin
706 1.1.1.8.2.1 martin <dt>
707 1.1.1.8.2.1 martin <a id="XML_DTD" name="XML_DTD">XML_DTD</a>
708 1.1.1.8.2.1 martin </dt>
709 1.1.1.8.2.1 martin
710 1.1.1.8.2.1 martin <dd>
711 1.1.1.8.2.1 martin Include support for using and reporting DTD-based content. If this is defined,
712 1.1.1.8.2.1 martin default attribute values from an external DTD subset are reported and attribute
713 1.1.1.8.2.1 martin value normalization occurs based on the type of attributes defined in the
714 1.1.1.8.2.1 martin external subset. Without this, Expat has a smaller memory footprint and can be
715 1.1.1.8.2.1 martin faster, but will not load external parameter entities or process conditional
716 1.1.1.8.2.1 martin sections. If defined, makes the functions <code><a href=
717 1.1.1.8.2.1 martin "#XML_SetBillionLaughsAttackProtectionMaximumAmplification">XML_SetBillionLaughsAttackProtectionMaximumAmplification</a></code>
718 1.1.1.8.2.1 martin and <code><a href=
719 1.1.1.8.2.1 martin "#XML_SetBillionLaughsAttackProtectionActivationThreshold">XML_SetBillionLaughsAttackProtectionActivationThreshold</a></code>
720 1.1.1.8.2.1 martin available.
721 1.1.1.8.2.1 martin </dd>
722 1.1.1.8.2.1 martin
723 1.1.1.8.2.1 martin <dt>
724 1.1.1.8.2.1 martin <a id="XML_NS" name="XML_NS">XML_NS</a>
725 1.1.1.8.2.1 martin </dt>
726 1.1.1.8.2.1 martin
727 1.1.1.8.2.1 martin <dd>
728 1.1.1.8.2.1 martin When defined, support for the <cite><a href=
729 1.1.1.8.2.1 martin "https://www.w3.org/TR/REC-xml-names/">Namespaces in XML</a></cite>
730 1.1.1.8.2.1 martin specification is included.
731 1.1.1.8.2.1 martin </dd>
732 1.1.1.8.2.1 martin
733 1.1.1.8.2.1 martin <dt>
734 1.1.1.8.2.1 martin <a id="XML_UNICODE" name="XML_UNICODE">XML_UNICODE</a>
735 1.1.1.8.2.1 martin </dt>
736 1.1.1.8.2.1 martin
737 1.1.1.8.2.1 martin <dd>
738 1.1.1.8.2.1 martin When defined, character data reported to the application is encoded in UTF-16
739 1.1.1.8.2.1 martin using wide characters of the type <code>XML_Char</code>. This is implied if
740 1.1.1.8.2.1 martin <code>XML_UNICODE_WCHAR_T</code> is defined.
741 1.1.1.8.2.1 martin </dd>
742 1.1.1.8.2.1 martin
743 1.1.1.8.2.1 martin <dt>
744 1.1.1.8.2.1 martin <a id="XML_UNICODE_WCHAR_T" name="XML_UNICODE_WCHAR_T">XML_UNICODE_WCHAR_T</a>
745 1.1.1.8.2.1 martin </dt>
746 1.1.1.8.2.1 martin
747 1.1.1.8.2.1 martin <dd>
748 1.1.1.8.2.1 martin If defined, causes the <code>XML_Char</code> character type to be defined using
749 1.1.1.8.2.1 martin the <code>wchar_t</code> type; otherwise, <code>unsigned short</code> is used.
750 1.1.1.8.2.1 martin Defining this implies <code>XML_UNICODE</code>.
751 1.1.1.8.2.1 martin </dd>
752 1.1.1.8.2.1 martin
753 1.1.1.8.2.1 martin <dt>
754 1.1.1.8.2.1 martin <a id="XML_LARGE_SIZE" name="XML_LARGE_SIZE">XML_LARGE_SIZE</a>
755 1.1.1.8.2.1 martin </dt>
756 1.1.1.8.2.1 martin
757 1.1.1.8.2.1 martin <dd>
758 1.1.1.8.2.1 martin If defined, causes the <code>XML_Size</code> and <code>XML_Index</code> integer
759 1.1.1.8.2.1 martin types to be at least 64 bits in size. This is intended to support processing of
760 1.1.1.8.2.1 martin very large input streams, where the return values of <code><a href=
761 1.1.1.8.2.1 martin "#XML_GetCurrentByteIndex">XML_GetCurrentByteIndex</a></code>, <code><a href=
762 1.1.1.8.2.1 martin "#XML_GetCurrentLineNumber">XML_GetCurrentLineNumber</a></code> and
763 1.1.1.8.2.1 martin <code><a href=
764 1.1.1.8.2.1 martin "#XML_GetCurrentColumnNumber">XML_GetCurrentColumnNumber</a></code> could
765 1.1.1.8.2.1 martin overflow. It may not be supported by all compilers, and is turned off by
766 1.1.1.8.2.1 martin default.
767 1.1.1.8.2.1 martin </dd>
768 1.1.1.8.2.1 martin
769 1.1.1.8.2.1 martin <dt>
770 1.1.1.8.2.1 martin <a id="XML_CONTEXT_BYTES" name="XML_CONTEXT_BYTES">XML_CONTEXT_BYTES</a>
771 1.1.1.8.2.1 martin </dt>
772 1.1.1.8.2.1 martin
773 1.1.1.8.2.1 martin <dd>
774 1.1.1.8.2.1 martin The number of input bytes of markup context which the parser will ensure are
775 1.1.1.8.2.1 martin available for reporting via <code><a href=
776 1.1.1.8.2.1 martin "#XML_GetInputContext">XML_GetInputContext</a></code>. This is normally set to
777 1.1.1.8.2.1 martin 1024, and must be set to a positive integer to enable. If this is set to zero,
778 1.1.1.8.2.1 martin the input context will not be available and <code><a href=
779 1.1.1.8.2.1 martin "#XML_GetInputContext">XML_GetInputContext</a></code> will always report
780 1.1.1.8.2.1 martin <code>NULL</code>. Without this, Expat has a smaller memory footprint and can
781 1.1.1.8.2.1 martin be faster.
782 1.1.1.8.2.1 martin </dd>
783 1.1.1.8.2.1 martin
784 1.1.1.8.2.1 martin <dt>
785 1.1.1.8.2.1 martin <a id="XML_STATIC" name="XML_STATIC">XML_STATIC</a>
786 1.1.1.8.2.1 martin </dt>
787 1.1.1.8.2.1 martin
788 1.1.1.8.2.1 martin <dd>
789 1.1.1.8.2.1 martin On Windows, this should be set if Expat is going to be linked statically with
790 1.1.1.8.2.1 martin the code that calls it; this is required to get all the right MSVC magic
791 1.1.1.8.2.1 martin annotations correct. This is ignored on other platforms.
792 1.1.1.8.2.1 martin </dd>
793 1.1.1.8.2.1 martin
794 1.1.1.8.2.1 martin <dt>
795 1.1.1.8.2.1 martin <a id="XML_ATTR_INFO" name="XML_ATTR_INFO">XML_ATTR_INFO</a>
796 1.1.1.8.2.1 martin </dt>
797 1.1.1.8.2.1 martin
798 1.1.1.8.2.1 martin <dd>
799 1.1.1.8.2.1 martin If defined, makes the additional function <code><a href=
800 1.1.1.8.2.1 martin "#XML_GetAttributeInfo">XML_GetAttributeInfo</a></code> available for reporting
801 1.1.1.8.2.1 martin attribute byte offsets.
802 1.1.1.8.2.1 martin </dd>
803 1.1.1.8.2.1 martin </dl>
804 1.1.1.8.2.1 martin
805 1.1.1.8.2.1 martin <hr />
806 1.1.1.8.2.1 martin
807 1.1.1.8.2.1 martin <h2>
808 1.1.1.8.2.1 martin <a id="using" name="using">Using Expat</a>
809 1.1.1.8.2.1 martin </h2>
810 1.1.1.8.2.1 martin
811 1.1.1.8.2.1 martin <h3>
812 1.1.1.8.2.1 martin Compiling and Linking Against Expat
813 1.1.1.8.2.1 martin </h3>
814 1.1.1.8.2.1 martin
815 1.1.1.8.2.1 martin <p>
816 1.1.1.8.2.1 martin Unless you installed Expat in a location not expected by your compiler and
817 1.1.1.8.2.1 martin linker, all you have to do to use Expat in your programs is to include the Expat
818 1.1.1.8.2.1 martin header (<code>#include <expat.h></code>) in your files that make calls to
819 1.1.1.8.2.1 martin it and to tell the linker that it needs to link against the Expat library. On
820 1.1.1.8.2.1 martin Unix systems, this would usually be done with the <code>-lexpat</code> argument.
821 1.1.1.8.2.1 martin Otherwise, you'll need to tell the compiler where to look for the Expat header
822 1.1.1.8.2.1 martin and the linker where to find the Expat library. You may also need to take steps
823 1.1.1.8.2.1 martin to tell the operating system where to find this library at run time.
824 1.1.1.8.2.1 martin </p>
825 1.1.1.8.2.1 martin
826 1.1.1.8.2.1 martin <p>
827 1.1.1.8.2.1 martin On a Unix-based system, here's what a Makefile might look like when Expat is
828 1.1.1.8.2.1 martin installed in a standard location:
829 1.1.1.8.2.1 martin </p>
830 1.1 tron
831 1.1.1.8.2.1 martin <pre class="eg">
832 1.1 tron CC=cc
833 1.1 tron LDFLAGS=
834 1.1 tron LIBS= -lexpat
835 1.1 tron xmlapp: xmlapp.o
836 1.1 tron $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS)
837 1.1 tron </pre>
838 1.1.1.8.2.1 martin <p>
839 1.1.1.8.2.1 martin If you installed Expat in, say, <code>/home/me/mystuff</code>, then the Makefile
840 1.1.1.8.2.1 martin would look like this:
841 1.1.1.8.2.1 martin </p>
842 1.1 tron
843 1.1.1.8.2.1 martin <pre class="eg">
844 1.1 tron CC=cc
845 1.1 tron CFLAGS= -I/home/me/mystuff/include
846 1.1 tron LDFLAGS=
847 1.1 tron LIBS= -L/home/me/mystuff/lib -lexpat
848 1.1 tron xmlapp: xmlapp.o
849 1.1 tron $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS)
850 1.1 tron </pre>
851 1.1.1.8.2.1 martin <p>
852 1.1.1.8.2.1 martin You'd also have to set the environment variable <code>LD_LIBRARY_PATH</code> to
853 1.1.1.8.2.1 martin <code>/home/me/mystuff/lib</code> (or to
854 1.1.1.8.2.1 martin <code>${LD_LIBRARY_PATH}:/home/me/mystuff/lib</code> if LD_LIBRARY_PATH already
855 1.1.1.8.2.1 martin has some directories in it) in order to run your application.
856 1.1.1.8.2.1 martin </p>
857 1.1.1.8.2.1 martin
858 1.1.1.8.2.1 martin <h3>
859 1.1.1.8.2.1 martin Expat Basics
860 1.1.1.8.2.1 martin </h3>
861 1.1.1.8.2.1 martin
862 1.1.1.8.2.1 martin <p>
863 1.1.1.8.2.1 martin As we saw in the example in the overview, the first step in parsing an XML
864 1.1.1.8.2.1 martin document with Expat is to create a parser object. There are <a href=
865 1.1.1.8.2.1 martin "#creation">three functions</a> in the Expat API for creating a parser object.
866 1.1.1.8.2.1 martin However, only two of these (<code><a href=
867 1.1.1.8.2.1 martin "#XML_ParserCreate">XML_ParserCreate</a></code> and <code><a href=
868 1.1.1.8.2.1 martin "#XML_ParserCreateNS">XML_ParserCreateNS</a></code>) can be used for constructing
869 1.1.1.8.2.1 martin a parser for a top-level document. The object returned by these functions is an
870 1.1.1.8.2.1 martin opaque pointer (i.e. "expat.h" declares it as void *) to data with further
871 1.1.1.8.2.1 martin internal structure. In order to free the memory associated with this object you
872 1.1.1.8.2.1 martin must call <code><a href="#XML_ParserFree">XML_ParserFree</a></code>. Note that if
873 1.1.1.8.2.1 martin you have provided any <a href="#userdata">user data</a> that gets stored in the
874 1.1.1.8.2.1 martin parser, then your application is responsible for freeing it prior to calling
875 1.1.1.8.2.1 martin <code>XML_ParserFree</code>.
876 1.1.1.8.2.1 martin </p>
877 1.1.1.8.2.1 martin
878 1.1.1.8.2.1 martin <p>
879 1.1.1.8.2.1 martin The objects returned by the parser creation functions are good for parsing only
880 1.1.1.8.2.1 martin one XML document or external parsed entity. If your application needs to parse
881 1.1.1.8.2.1 martin many XML documents, then it needs to create a parser object for each one. The
882 1.1.1.8.2.1 martin best way to deal with this is to create a higher level object that contains all
883 1.1.1.8.2.1 martin the default initialization you want for your parser objects.
884 1.1.1.8.2.1 martin </p>
885 1.1.1.8.2.1 martin
886 1.1.1.8.2.1 martin <p>
887 1.1.1.8.2.1 martin Walking through a document hierarchy with a stream oriented parser will require a
888 1.1.1.8.2.1 martin good stack mechanism in order to keep track of current context. For instance, to
889 1.1.1.8.2.1 martin answer the simple question, "What element does this text belong to?" requires a
890 1.1.1.8.2.1 martin stack, since the parser may have descended into other elements that are children
891 1.1.1.8.2.1 martin of the current one and has encountered this text on the way out.
892 1.1.1.8.2.1 martin </p>
893 1.1.1.8.2.1 martin
894 1.1.1.8.2.1 martin <p>
895 1.1.1.8.2.1 martin The things you're likely to want to keep on a stack are the currently opened
896 1.1.1.8.2.1 martin element and it's attributes. You push this information onto the stack in the
897 1.1.1.8.2.1 martin start handler and you pop it off in the end handler.
898 1.1.1.8.2.1 martin </p>
899 1.1.1.8.2.1 martin
900 1.1.1.8.2.1 martin <p>
901 1.1.1.8.2.1 martin For some tasks, it is sufficient to just keep information on what the depth of
902 1.1.1.8.2.1 martin the stack is (or would be if you had one.) The outline program shown above
903 1.1.1.8.2.1 martin presents one example. Another such task would be skipping over a complete
904 1.1.1.8.2.1 martin element. When you see the start tag for the element you want to skip, you set a
905 1.1.1.8.2.1 martin skip flag and record the depth at which the element started. When the end tag
906 1.1.1.8.2.1 martin handler encounters the same depth, the skipped element has ended and the flag may
907 1.1.1.8.2.1 martin be cleared. If you follow the convention that the root element starts at 1, then
908 1.1.1.8.2.1 martin you can use the same variable for skip flag and skip depth.
909 1.1.1.8.2.1 martin </p>
910 1.1 tron
911 1.1.1.8.2.1 martin <pre class="eg">
912 1.1 tron void
913 1.1 tron init_info(Parseinfo *info) {
914 1.1.1.8.2.1 martin info->skip = 0;
915 1.1.1.8.2.1 martin info->depth = 1;
916 1.1 tron /* Other initializations here */
917 1.1 tron } /* End of init_info */
918 1.1 tron
919 1.1 tron void XMLCALL
920 1.1 tron rawstart(void *data, const char *el, const char **attr) {
921 1.1 tron Parseinfo *inf = (Parseinfo *) data;
922 1.1 tron
923 1.1.1.8.2.1 martin if (! inf->skip) {
924 1.1 tron if (should_skip(inf, el, attr)) {
925 1.1.1.8.2.1 martin inf->skip = inf->depth;
926 1.1 tron }
927 1.1 tron else
928 1.1 tron start(inf, el, attr); /* This does rest of start handling */
929 1.1 tron }
930 1.1 tron
931 1.1.1.8.2.1 martin inf->depth++;
932 1.1 tron } /* End of rawstart */
933 1.1 tron
934 1.1 tron void XMLCALL
935 1.1 tron rawend(void *data, const char *el) {
936 1.1 tron Parseinfo *inf = (Parseinfo *) data;
937 1.1 tron
938 1.1.1.8.2.1 martin inf->depth--;
939 1.1 tron
940 1.1.1.8.2.1 martin if (! inf->skip)
941 1.1 tron end(inf, el); /* This does rest of end handling */
942 1.1 tron
943 1.1.1.8.2.1 martin if (inf->skip == inf->depth)
944 1.1.1.8.2.1 martin inf->skip = 0;
945 1.1 tron } /* End rawend */
946 1.1 tron </pre>
947 1.1.1.8.2.1 martin <p>
948 1.1.1.8.2.1 martin Notice in the above example the difference in how depth is manipulated in the
949 1.1.1.8.2.1 martin start and end handlers. The end tag handler should be the mirror image of the
950 1.1.1.8.2.1 martin start tag handler. This is necessary to properly model containment. Since, in the
951 1.1.1.8.2.1 martin start tag handler, we incremented depth <em>after</em> the main body of start tag
952 1.1.1.8.2.1 martin code, then in the end handler, we need to manipulate it <em>before</em> the main
953 1.1.1.8.2.1 martin body. If we'd decided to increment it first thing in the start handler, then we'd
954 1.1.1.8.2.1 martin have had to decrement it last thing in the end handler.
955 1.1.1.8.2.1 martin </p>
956 1.1.1.8.2.1 martin
957 1.1.1.8.2.1 martin <h3 id="userdata">
958 1.1.1.8.2.1 martin Communicating between handlers
959 1.1.1.8.2.1 martin </h3>
960 1.1.1.8.2.1 martin
961 1.1.1.8.2.1 martin <p>
962 1.1.1.8.2.1 martin In order to be able to pass information between different handlers without using
963 1.1.1.8.2.1 martin globals, you'll need to define a data structure to hold the shared variables. You
964 1.1.1.8.2.1 martin can then tell Expat (with the <code><a href=
965 1.1.1.8.2.1 martin "#XML_SetUserData">XML_SetUserData</a></code> function) to pass a pointer to this
966 1.1.1.8.2.1 martin structure to the handlers. This is the first argument received by most handlers.
967 1.1.1.8.2.1 martin In the <a href="#reference">reference section</a>, an argument to a callback
968 1.1.1.8.2.1 martin function is named <code>userData</code> and have type <code>void *</code> if the
969 1.1.1.8.2.1 martin user data is passed; it will have the type <code>XML_Parser</code> if the parser
970 1.1.1.8.2.1 martin itself is passed. When the parser is passed, the user data may be retrieved using
971 1.1.1.8.2.1 martin <code><a href="#XML_GetUserData">XML_GetUserData</a></code>.
972 1.1.1.8.2.1 martin </p>
973 1.1.1.8.2.1 martin
974 1.1.1.8.2.1 martin <p>
975 1.1.1.8.2.1 martin One common case where multiple calls to a single handler may need to communicate
976 1.1.1.8.2.1 martin using an application data structure is the case when content passed to the
977 1.1.1.8.2.1 martin character data handler (set by <code><a href=
978 1.1.1.8.2.1 martin "#XML_SetCharacterDataHandler">XML_SetCharacterDataHandler</a></code>) needs to
979 1.1.1.8.2.1 martin be accumulated. A common first-time mistake with any of the event-oriented
980 1.1.1.8.2.1 martin interfaces to an XML parser is to expect all the text contained in an element to
981 1.1.1.8.2.1 martin be reported by a single call to the character data handler. Expat, like many
982 1.1.1.8.2.1 martin other XML parsers, reports such data as a sequence of calls; there's no way to
983 1.1.1.8.2.1 martin know when the end of the sequence is reached until a different callback is made.
984 1.1.1.8.2.1 martin A buffer referenced by the user data structure proves both an effective and
985 1.1.1.8.2.1 martin convenient place to accumulate character data.
986 1.1.1.8.2.1 martin </p>
987 1.1.1.8.2.1 martin <!-- XXX example needed here -->
988 1.1.1.8.2.1 martin
989 1.1.1.8.2.1 martin <h3>
990 1.1.1.8.2.1 martin XML Version
991 1.1.1.8.2.1 martin </h3>
992 1.1.1.8.2.1 martin
993 1.1.1.8.2.1 martin <p>
994 1.1.1.8.2.1 martin Expat is an XML 1.0 parser, and as such never complains based on the value of the
995 1.1.1.8.2.1 martin <code>version</code> pseudo-attribute in the XML declaration, if present.
996 1.1.1.8.2.1 martin </p>
997 1.1.1.8.2.1 martin
998 1.1.1.8.2.1 martin <p>
999 1.1.1.8.2.1 martin If an application needs to check the version number (to support alternate
1000 1.1.1.8.2.1 martin processing), it should use the <code><a href=
1001 1.1.1.8.2.1 martin "#XML_SetXmlDeclHandler">XML_SetXmlDeclHandler</a></code> function to set a
1002 1.1.1.8.2.1 martin handler that uses the information in the XML declaration to determine what to do.
1003 1.1.1.8.2.1 martin This example shows how to check that only a version number of <code>"1.0"</code>
1004 1.1.1.8.2.1 martin is accepted:
1005 1.1.1.8.2.1 martin </p>
1006 1.1 tron
1007 1.1.1.8.2.1 martin <pre class="eg">
1008 1.1 tron static int wrong_version;
1009 1.1 tron static XML_Parser parser;
1010 1.1 tron
1011 1.1 tron static void XMLCALL
1012 1.1 tron xmldecl_handler(void *userData,
1013 1.1 tron const XML_Char *version,
1014 1.1 tron const XML_Char *encoding,
1015 1.1 tron int standalone)
1016 1.1 tron {
1017 1.1 tron static const XML_Char Version_1_0[] = {'1', '.', '0', 0};
1018 1.1 tron
1019 1.1 tron int i;
1020 1.1 tron
1021 1.1 tron for (i = 0; i < (sizeof(Version_1_0) / sizeof(Version_1_0[0])); ++i) {
1022 1.1 tron if (version[i] != Version_1_0[i]) {
1023 1.1 tron wrong_version = 1;
1024 1.1 tron /* also clear all other handlers: */
1025 1.1 tron XML_SetCharacterDataHandler(parser, NULL);
1026 1.1 tron ...
1027 1.1 tron return;
1028 1.1 tron }
1029 1.1 tron }
1030 1.1 tron ...
1031 1.1 tron }
1032 1.1 tron </pre>
1033 1.1.1.8.2.1 martin <h3>
1034 1.1.1.8.2.1 martin Namespace Processing
1035 1.1.1.8.2.1 martin </h3>
1036 1.1.1.8.2.1 martin
1037 1.1.1.8.2.1 martin <p>
1038 1.1.1.8.2.1 martin When the parser is created using the <code><a href=
1039 1.1.1.8.2.1 martin "#XML_ParserCreateNS">XML_ParserCreateNS</a></code>, function, Expat performs
1040 1.1.1.8.2.1 martin namespace processing. Under namespace processing, Expat consumes
1041 1.1.1.8.2.1 martin <code>xmlns</code> and <code>xmlns:...</code> attributes, which declare
1042 1.1.1.8.2.1 martin namespaces for the scope of the element in which they occur. This means that your
1043 1.1.1.8.2.1 martin start handler will not see these attributes. Your application can still be
1044 1.1.1.8.2.1 martin informed of these declarations by setting namespace declaration handlers with
1045 1.1.1.8.2.1 martin <a href=
1046 1.1.1.8.2.1 martin "#XML_SetNamespaceDeclHandler"><code>XML_SetNamespaceDeclHandler</code></a>.
1047 1.1.1.8.2.1 martin </p>
1048 1.1.1.8.2.1 martin
1049 1.1.1.8.2.1 martin <p>
1050 1.1.1.8.2.1 martin Element type and attribute names that belong to a given namespace are passed to
1051 1.1.1.8.2.1 martin the appropriate handler in expanded form. By default this expanded form is a
1052 1.1.1.8.2.1 martin concatenation of the namespace URI, the separator character (which is the 2nd
1053 1.1.1.8.2.1 martin argument to <code><a href="#XML_ParserCreateNS">XML_ParserCreateNS</a></code>),
1054 1.1.1.8.2.1 martin and the local name (i.e. the part after the colon). Names with undeclared
1055 1.1.1.8.2.1 martin prefixes are not well-formed when namespace processing is enabled, and will
1056 1.1.1.8.2.1 martin trigger an error. Unprefixed attribute names are never expanded, and unprefixed
1057 1.1.1.8.2.1 martin element names are only expanded when they are in the scope of a default
1058 1.1.1.8.2.1 martin namespace.
1059 1.1.1.8.2.1 martin </p>
1060 1.1.1.8.2.1 martin
1061 1.1.1.8.2.1 martin <p>
1062 1.1.1.8.2.1 martin However if <code><a href=
1063 1.1.1.8.2.1 martin "#XML_SetReturnNSTriplet">XML_SetReturnNSTriplet</a></code> has been called with
1064 1.1.1.8.2.1 martin a non-zero <code>do_nst</code> parameter, then the expanded form for names with
1065 1.1.1.8.2.1 martin an explicit prefix is a concatenation of: URI, separator, local name, separator,
1066 1.1.1.8.2.1 martin prefix.
1067 1.1.1.8.2.1 martin </p>
1068 1.1.1.8.2.1 martin
1069 1.1.1.8.2.1 martin <p>
1070 1.1.1.8.2.1 martin You can set handlers for the start of a namespace declaration and for the end of
1071 1.1.1.8.2.1 martin a scope of a declaration with the <code><a href=
1072 1.1.1.8.2.1 martin "#XML_SetNamespaceDeclHandler">XML_SetNamespaceDeclHandler</a></code> function.
1073 1.1.1.8.2.1 martin The StartNamespaceDeclHandler is called prior to the start tag handler and the
1074 1.1.1.8.2.1 martin EndNamespaceDeclHandler is called after the corresponding end tag that ends the
1075 1.1.1.8.2.1 martin namespace's scope. The namespace start handler gets passed the prefix and URI for
1076 1.1.1.8.2.1 martin the namespace. For a default namespace declaration (xmlns='...'), the prefix will
1077 1.1.1.8.2.1 martin be <code>NULL</code>. The URI will be <code>NULL</code> for the case where the
1078 1.1.1.8.2.1 martin default namespace is being unset. The namespace end handler just gets the prefix
1079 1.1.1.8.2.1 martin for the closing scope.
1080 1.1.1.8.2.1 martin </p>
1081 1.1.1.8.2.1 martin
1082 1.1.1.8.2.1 martin <p>
1083 1.1.1.8.2.1 martin These handlers are called for each declaration. So if, for instance, a start tag
1084 1.1.1.8.2.1 martin had three namespace declarations, then the StartNamespaceDeclHandler would be
1085 1.1.1.8.2.1 martin called three times before the start tag handler is called, once for each
1086 1.1.1.8.2.1 martin declaration.
1087 1.1.1.8.2.1 martin </p>
1088 1.1.1.8.2.1 martin
1089 1.1.1.8.2.1 martin <h3>
1090 1.1.1.8.2.1 martin Character Encodings
1091 1.1.1.8.2.1 martin </h3>
1092 1.1.1.8.2.1 martin
1093 1.1.1.8.2.1 martin <p>
1094 1.1.1.8.2.1 martin While XML is based on Unicode, and every XML processor is required to recognized
1095 1.1.1.8.2.1 martin UTF-8 and UTF-16 (1 and 2 byte encodings of Unicode), other encodings may be
1096 1.1.1.8.2.1 martin declared in XML documents or entities. For the main document, an XML declaration
1097 1.1.1.8.2.1 martin may contain an encoding declaration:
1098 1.1.1.8.2.1 martin </p>
1099 1.1 tron
1100 1.1.1.8.2.1 martin <pre>
1101 1.1 tron <?xml version="1.0" encoding="ISO-8859-2"?>
1102 1.1 tron </pre>
1103 1.1.1.8.2.1 martin <p>
1104 1.1.1.8.2.1 martin External parsed entities may begin with a text declaration, which looks like an
1105 1.1.1.8.2.1 martin XML declaration with just an encoding declaration:
1106 1.1.1.8.2.1 martin </p>
1107 1.1 tron
1108 1.1.1.8.2.1 martin <pre>
1109 1.1 tron <?xml encoding="Big5"?>
1110 1.1 tron </pre>
1111 1.1.1.8.2.1 martin <p>
1112 1.1.1.8.2.1 martin With Expat, you may also specify an encoding at the time of creating a parser.
1113 1.1.1.8.2.1 martin This is useful when the encoding information may come from a source outside the
1114 1.1.1.8.2.1 martin document itself (like a higher level protocol.)
1115 1.1.1.8.2.1 martin </p>
1116 1.1.1.8.2.1 martin
1117 1.1.1.8.2.1 martin <p>
1118 1.1.1.8.2.1 martin <a id="builtin_encodings" name="builtin_encodings"></a>There are four built-in
1119 1.1.1.8.2.1 martin encodings in Expat:
1120 1.1.1.8.2.1 martin </p>
1121 1.1.1.8.2.1 martin
1122 1.1.1.8.2.1 martin <ul>
1123 1.1.1.8.2.1 martin <li>UTF-8
1124 1.1.1.8.2.1 martin </li>
1125 1.1.1.8.2.1 martin
1126 1.1.1.8.2.1 martin <li>UTF-16
1127 1.1.1.8.2.1 martin </li>
1128 1.1.1.8.2.1 martin
1129 1.1.1.8.2.1 martin <li>ISO-8859-1
1130 1.1.1.8.2.1 martin </li>
1131 1.1.1.8.2.1 martin
1132 1.1.1.8.2.1 martin <li>US-ASCII
1133 1.1.1.8.2.1 martin </li>
1134 1.1.1.8.2.1 martin </ul>
1135 1.1 tron
1136 1.1.1.8.2.1 martin <p>
1137 1.1.1.8.2.1 martin Anything else discovered in an encoding declaration or in the protocol encoding
1138 1.1.1.8.2.1 martin specified in the parser constructor, triggers a call to the
1139 1.1.1.8.2.1 martin <code>UnknownEncodingHandler</code>. This handler gets passed the encoding name
1140 1.1.1.8.2.1 martin and a pointer to an <code>XML_Encoding</code> data structure. Your handler must
1141 1.1.1.8.2.1 martin fill in this structure and return <code>XML_STATUS_OK</code> if it knows how to
1142 1.1.1.8.2.1 martin deal with the encoding. Otherwise the handler should return
1143 1.1.1.8.2.1 martin <code>XML_STATUS_ERROR</code>. The handler also gets passed a pointer to an
1144 1.1.1.8.2.1 martin optional application data structure that you may indicate when you set the
1145 1.1.1.8.2.1 martin handler.
1146 1.1.1.8.2.1 martin </p>
1147 1.1.1.8.2.1 martin
1148 1.1.1.8.2.1 martin <p>
1149 1.1.1.8.2.1 martin Expat places restrictions on character encodings that it can support by filling
1150 1.1.1.8.2.1 martin in the <code>XML_Encoding</code> structure. include file:
1151 1.1.1.8.2.1 martin </p>
1152 1.1.1.8.2.1 martin
1153 1.1.1.8.2.1 martin <ol>
1154 1.1.1.8.2.1 martin <li>Every ASCII character that can appear in a well-formed XML document must be
1155 1.1.1.8.2.1 martin represented by a single byte, and that byte must correspond to it's ASCII
1156 1.1.1.8.2.1 martin encoding (except for the characters $@\^'{}~)
1157 1.1.1.8.2.1 martin </li>
1158 1.1.1.8.2.1 martin
1159 1.1.1.8.2.1 martin <li>Characters must be encoded in 4 bytes or less.
1160 1.1.1.8.2.1 martin </li>
1161 1.1.1.8.2.1 martin
1162 1.1.1.8.2.1 martin <li>All characters encoded must have Unicode scalar values less than or equal to
1163 1.1.1.8.2.1 martin 65535 (0xFFFF)<em>This does not apply to the built-in support for UTF-16 and
1164 1.1.1.8.2.1 martin UTF-8</em>
1165 1.1.1.8.2.1 martin </li>
1166 1.1.1.8.2.1 martin
1167 1.1.1.8.2.1 martin <li>No character may be encoded by more that one distinct sequence of bytes
1168 1.1.1.8.2.1 martin </li>
1169 1.1.1.8.2.1 martin </ol>
1170 1.1.1.8.2.1 martin
1171 1.1.1.8.2.1 martin <p>
1172 1.1.1.8.2.1 martin <code>XML_Encoding</code> contains an array of integers that correspond to the
1173 1.1.1.8.2.1 martin 1st byte of an encoding sequence. If the value in the array for a byte is zero or
1174 1.1.1.8.2.1 martin positive, then the byte is a single byte encoding that encodes the Unicode scalar
1175 1.1.1.8.2.1 martin value contained in the array. A -1 in this array indicates a malformed byte. If
1176 1.1.1.8.2.1 martin the value is -2, -3, or -4, then the byte is the beginning of a 2, 3, or 4 byte
1177 1.1.1.8.2.1 martin sequence respectively. Multi-byte sequences are sent to the convert function
1178 1.1.1.8.2.1 martin pointed at in the <code>XML_Encoding</code> structure. This function should
1179 1.1.1.8.2.1 martin return the Unicode scalar value for the sequence or -1 if the sequence is
1180 1.1.1.8.2.1 martin malformed.
1181 1.1.1.8.2.1 martin </p>
1182 1.1.1.8.2.1 martin
1183 1.1.1.8.2.1 martin <p>
1184 1.1.1.8.2.1 martin One pitfall that novice Expat users are likely to fall into is that although
1185 1.1.1.8.2.1 martin Expat may accept input in various encodings, the strings that it passes to the
1186 1.1.1.8.2.1 martin handlers are always encoded in UTF-8 or UTF-16 (depending on how Expat was
1187 1.1.1.8.2.1 martin compiled). Your application is responsible for any translation of these strings
1188 1.1.1.8.2.1 martin into other encodings.
1189 1.1.1.8.2.1 martin </p>
1190 1.1.1.8.2.1 martin
1191 1.1.1.8.2.1 martin <h3>
1192 1.1.1.8.2.1 martin Handling External Entity References
1193 1.1.1.8.2.1 martin </h3>
1194 1.1.1.8.2.1 martin
1195 1.1.1.8.2.1 martin <p>
1196 1.1.1.8.2.1 martin Expat does not read or parse external entities directly. Note that any external
1197 1.1.1.8.2.1 martin DTD is a special case of an external entity. If you've set no
1198 1.1.1.8.2.1 martin <code>ExternalEntityRefHandler</code>, then external entity references are
1199 1.1.1.8.2.1 martin silently ignored. Otherwise, it calls your handler with the information needed to
1200 1.1.1.8.2.1 martin read and parse the external entity.
1201 1.1.1.8.2.1 martin </p>
1202 1.1.1.8.2.1 martin
1203 1.1.1.8.2.1 martin <p>
1204 1.1.1.8.2.1 martin Your handler isn't actually responsible for parsing the entity, but it is
1205 1.1.1.8.2.1 martin responsible for creating a subsidiary parser with <code><a href=
1206 1.1.1.8.2.1 martin "#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></code> that
1207 1.1.1.8.2.1 martin will do the job. This returns an instance of <code>XML_Parser</code> that has
1208 1.1.1.8.2.1 martin handlers and other data structures initialized from the parent parser. You may
1209 1.1.1.8.2.1 martin then use <code><a href="#XML_Parse">XML_Parse</a></code> or <code><a href=
1210 1.1.1.8.2.1 martin "#XML_ParseBuffer">XML_ParseBuffer</a></code> calls against this parser. Since
1211 1.1.1.8.2.1 martin external entities my refer to other external entities, your handler should be
1212 1.1.1.8.2.1 martin prepared to be called recursively.
1213 1.1.1.8.2.1 martin </p>
1214 1.1.1.8.2.1 martin
1215 1.1.1.8.2.1 martin <h3>
1216 1.1.1.8.2.1 martin Parsing DTDs
1217 1.1.1.8.2.1 martin </h3>
1218 1.1.1.8.2.1 martin
1219 1.1.1.8.2.1 martin <p>
1220 1.1.1.8.2.1 martin In order to parse parameter entities, before starting the parse, you must call
1221 1.1.1.8.2.1 martin <code><a href="#XML_SetParamEntityParsing">XML_SetParamEntityParsing</a></code>
1222 1.1.1.8.2.1 martin with one of the following arguments:
1223 1.1.1.8.2.1 martin </p>
1224 1.1.1.8.2.1 martin
1225 1.1.1.8.2.1 martin <dl>
1226 1.1.1.8.2.1 martin <dt>
1227 1.1.1.8.2.1 martin <code>XML_PARAM_ENTITY_PARSING_NEVER</code>
1228 1.1.1.8.2.1 martin </dt>
1229 1.1.1.8.2.1 martin
1230 1.1.1.8.2.1 martin <dd>
1231 1.1.1.8.2.1 martin Don't parse parameter entities or the external subset
1232 1.1.1.8.2.1 martin </dd>
1233 1.1.1.8.2.1 martin
1234 1.1.1.8.2.1 martin <dt>
1235 1.1.1.8.2.1 martin <code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code>
1236 1.1.1.8.2.1 martin </dt>
1237 1.1.1.8.2.1 martin
1238 1.1.1.8.2.1 martin <dd>
1239 1.1.1.8.2.1 martin Parse parameter entities and the external subset unless <code>standalone</code>
1240 1.1.1.8.2.1 martin was set to "yes" in the XML declaration.
1241 1.1.1.8.2.1 martin </dd>
1242 1.1.1.8.2.1 martin
1243 1.1.1.8.2.1 martin <dt>
1244 1.1.1.8.2.1 martin <code>XML_PARAM_ENTITY_PARSING_ALWAYS</code>
1245 1.1.1.8.2.1 martin </dt>
1246 1.1.1.8.2.1 martin
1247 1.1.1.8.2.1 martin <dd>
1248 1.1.1.8.2.1 martin Always parse parameter entities and the external subset
1249 1.1.1.8.2.1 martin </dd>
1250 1.1.1.8.2.1 martin </dl>
1251 1.1.1.8.2.1 martin
1252 1.1.1.8.2.1 martin <p>
1253 1.1.1.8.2.1 martin In order to read an external DTD, you also have to set an external entity
1254 1.1.1.8.2.1 martin reference handler as described above.
1255 1.1.1.8.2.1 martin </p>
1256 1.1.1.8.2.1 martin
1257 1.1.1.8.2.1 martin <h3 id="stop-resume">
1258 1.1.1.8.2.1 martin Temporarily Stopping Parsing
1259 1.1.1.8.2.1 martin </h3>
1260 1.1.1.8.2.1 martin
1261 1.1.1.8.2.1 martin <p>
1262 1.1.1.8.2.1 martin Expat 1.95.8 introduces a new feature: its now possible to stop parsing
1263 1.1.1.8.2.1 martin temporarily from within a handler function, even if more data has already been
1264 1.1.1.8.2.1 martin passed into the parser. Applications for this include
1265 1.1.1.8.2.1 martin </p>
1266 1.1 tron
1267 1.1.1.8.2.1 martin <ul>
1268 1.1.1.8.2.1 martin <li>Supporting the <a href="https://www.w3.org/TR/xinclude/">XInclude</a>
1269 1.1.1.8.2.1 martin specification.
1270 1.1.1.8.2.1 martin </li>
1271 1.1.1.8.2.1 martin
1272 1.1.1.8.2.1 martin <li>Delaying further processing until additional information is available from
1273 1.1.1.8.2.1 martin some other source.
1274 1.1.1.8.2.1 martin </li>
1275 1.1.1.8.2.1 martin
1276 1.1.1.8.2.1 martin <li>Adjusting processor load as task priorities shift within an application.
1277 1.1.1.8.2.1 martin </li>
1278 1.1.1.8.2.1 martin
1279 1.1.1.8.2.1 martin <li>Stopping parsing completely (simply free or reset the parser instead of
1280 1.1.1.8.2.1 martin resuming in the outer parsing loop). This can be useful if an application-domain
1281 1.1.1.8.2.1 martin error is found in the XML being parsed or if the result of the parse is
1282 1.1.1.8.2.1 martin determined not to be useful after all.
1283 1.1.1.8.2.1 martin </li>
1284 1.1.1.8.2.1 martin </ul>
1285 1.1 tron
1286 1.1.1.8.2.1 martin <p>
1287 1.1.1.8.2.1 martin To take advantage of this feature, the main parsing loop of an application needs
1288 1.1.1.8.2.1 martin to support this specifically. It cannot be supported with a parsing loop
1289 1.1.1.8.2.1 martin compatible with Expat 1.95.7 or earlier (though existing loops will continue to
1290 1.1.1.8.2.1 martin work without supporting the stop/resume feature).
1291 1.1.1.8.2.1 martin </p>
1292 1.1.1.8.2.1 martin
1293 1.1.1.8.2.1 martin <p>
1294 1.1.1.8.2.1 martin An application that uses this feature for a single parser will have the rough
1295 1.1.1.8.2.1 martin structure (in pseudo-code):
1296 1.1.1.8.2.1 martin </p>
1297 1.1.1.8.2.1 martin
1298 1.1.1.8.2.1 martin <pre class="pseudocode">
1299 1.1 tron fd = open_input()
1300 1.1 tron p = create_parser()
1301 1.1 tron
1302 1.1 tron if parse_xml(p, fd) {
1303 1.1 tron /* suspended */
1304 1.1 tron
1305 1.1 tron int suspended = 1;
1306 1.1 tron
1307 1.1 tron while (suspended) {
1308 1.1 tron do_something_else()
1309 1.1 tron if ready_to_resume() {
1310 1.1 tron suspended = continue_parsing(p, fd);
1311 1.1 tron }
1312 1.1 tron }
1313 1.1 tron }
1314 1.1 tron </pre>
1315 1.1.1.8.2.1 martin <p>
1316 1.1.1.8.2.1 martin An application that may resume any of several parsers based on input (either from
1317 1.1.1.8.2.1 martin the XML being parsed or some other source) will certainly have more interesting
1318 1.1.1.8.2.1 martin control structures.
1319 1.1.1.8.2.1 martin </p>
1320 1.1.1.8.2.1 martin
1321 1.1.1.8.2.1 martin <p>
1322 1.1.1.8.2.1 martin This C function could be used for the <code>parse_xml</code> function mentioned
1323 1.1.1.8.2.1 martin in the pseudo-code above:
1324 1.1.1.8.2.1 martin </p>
1325 1.1 tron
1326 1.1.1.8.2.1 martin <pre class="eg">
1327 1.1 tron #define BUFF_SIZE 10240
1328 1.1 tron
1329 1.1 tron /* Parse a document from the open file descriptor 'fd' until the parse
1330 1.1 tron is complete (the document has been completely parsed, or there's
1331 1.1 tron been an error), or the parse is stopped. Return non-zero when
1332 1.1 tron the parse is merely suspended.
1333 1.1 tron */
1334 1.1 tron int
1335 1.1 tron parse_xml(XML_Parser p, int fd)
1336 1.1 tron {
1337 1.1 tron for (;;) {
1338 1.1 tron int last_chunk;
1339 1.1 tron int bytes_read;
1340 1.1 tron enum XML_Status status;
1341 1.1 tron
1342 1.1 tron void *buff = XML_GetBuffer(p, BUFF_SIZE);
1343 1.1 tron if (buff == NULL) {
1344 1.1 tron /* handle error... */
1345 1.1 tron return 0;
1346 1.1 tron }
1347 1.1 tron bytes_read = read(fd, buff, BUFF_SIZE);
1348 1.1 tron if (bytes_read < 0) {
1349 1.1 tron /* handle error... */
1350 1.1 tron return 0;
1351 1.1 tron }
1352 1.1 tron status = XML_ParseBuffer(p, bytes_read, bytes_read == 0);
1353 1.1 tron switch (status) {
1354 1.1 tron case XML_STATUS_ERROR:
1355 1.1 tron /* handle error... */
1356 1.1 tron return 0;
1357 1.1 tron case XML_STATUS_SUSPENDED:
1358 1.1 tron return 1;
1359 1.1 tron }
1360 1.1 tron if (bytes_read == 0)
1361 1.1 tron return 0;
1362 1.1 tron }
1363 1.1 tron }
1364 1.1 tron </pre>
1365 1.1.1.8.2.1 martin <p>
1366 1.1.1.8.2.1 martin The corresponding <code>continue_parsing</code> function is somewhat simpler,
1367 1.1.1.8.2.1 martin since it only need deal with the return code from <code><a href=
1368 1.1.1.8.2.1 martin "#XML_ResumeParser">XML_ResumeParser</a></code>; it can delegate the input
1369 1.1.1.8.2.1 martin handling to the <code>parse_xml</code> function:
1370 1.1.1.8.2.1 martin </p>
1371 1.1 tron
1372 1.1.1.8.2.1 martin <pre class="eg">
1373 1.1 tron /* Continue parsing a document which had been suspended. The 'p' and
1374 1.1 tron 'fd' arguments are the same as passed to parse_xml(). Return
1375 1.1 tron non-zero when the parse is suspended.
1376 1.1 tron */
1377 1.1 tron int
1378 1.1 tron continue_parsing(XML_Parser p, int fd)
1379 1.1 tron {
1380 1.1 tron enum XML_Status status = XML_ResumeParser(p);
1381 1.1 tron switch (status) {
1382 1.1 tron case XML_STATUS_ERROR:
1383 1.1 tron /* handle error... */
1384 1.1 tron return 0;
1385 1.1 tron case XML_ERROR_NOT_SUSPENDED:
1386 1.1 tron /* handle error... */
1387 1.1 tron return 0;.
1388 1.1 tron case XML_STATUS_SUSPENDED:
1389 1.1 tron return 1;
1390 1.1 tron }
1391 1.1 tron return parse_xml(p, fd);
1392 1.1 tron }
1393 1.1 tron </pre>
1394 1.1.1.8.2.1 martin <p>
1395 1.1.1.8.2.1 martin Now that we've seen what a mess the top-level parsing loop can become, what have
1396 1.1.1.8.2.1 martin we gained? Very simply, we can now use the <code><a href=
1397 1.1.1.8.2.1 martin "#XML_StopParser">XML_StopParser</a></code> function to stop parsing, without
1398 1.1.1.8.2.1 martin having to go to great lengths to avoid additional processing that we're expecting
1399 1.1.1.8.2.1 martin to ignore. As a bonus, we get to stop parsing <em>temporarily</em>, and come back
1400 1.1.1.8.2.1 martin to it when we're ready.
1401 1.1.1.8.2.1 martin </p>
1402 1.1.1.8.2.1 martin
1403 1.1.1.8.2.1 martin <p>
1404 1.1.1.8.2.1 martin To stop parsing from a handler function, use the <code><a href=
1405 1.1.1.8.2.1 martin "#XML_StopParser">XML_StopParser</a></code> function. This function takes two
1406 1.1.1.8.2.1 martin arguments; the parser being stopped and a flag indicating whether the parse can
1407 1.1.1.8.2.1 martin be resumed in the future.
1408 1.1.1.8.2.1 martin </p>
1409 1.1.1.8.2.1 martin <!-- XXX really need more here -->
1410 1.1.1.8.2.1 martin
1411 1.1.1.8.2.1 martin <hr />
1412 1.1.1.8.2.1 martin <!-- ================================================================ -->
1413 1.1.1.8.2.1 martin
1414 1.1.1.8.2.1 martin <h2>
1415 1.1.1.8.2.1 martin <a id="reference" name="reference">Expat Reference</a>
1416 1.1.1.8.2.1 martin </h2>
1417 1.1.1.8.2.1 martin
1418 1.1.1.8.2.1 martin <h3>
1419 1.1.1.8.2.1 martin <a id="creation" name="creation">Parser Creation</a>
1420 1.1.1.8.2.1 martin </h3>
1421 1.1.1.8.2.1 martin
1422 1.1.1.8.2.1 martin <h4 id="XML_ParserCreate">
1423 1.1.1.8.2.1 martin XML_ParserCreate
1424 1.1.1.8.2.1 martin </h4>
1425 1.1 tron
1426 1.1.1.8.2.1 martin <pre class="fcndec">
1427 1.1 tron XML_Parser XMLCALL
1428 1.1 tron XML_ParserCreate(const XML_Char *encoding);
1429 1.1 tron </pre>
1430 1.1.1.8.2.1 martin <div class="fcndef">
1431 1.1.1.8.2.1 martin <p>
1432 1.1.1.8.2.1 martin Construct a new parser. If encoding is non-<code>NULL</code>, it specifies a
1433 1.1.1.8.2.1 martin character encoding to use for the document. This overrides the document
1434 1.1.1.8.2.1 martin encoding declaration. There are four built-in encodings:
1435 1.1.1.8.2.1 martin </p>
1436 1.1.1.8.2.1 martin
1437 1.1.1.8.2.1 martin <ul>
1438 1.1.1.8.2.1 martin <li>US-ASCII
1439 1.1.1.8.2.1 martin </li>
1440 1.1.1.8.2.1 martin
1441 1.1.1.8.2.1 martin <li>UTF-8
1442 1.1.1.8.2.1 martin </li>
1443 1.1.1.8.2.1 martin
1444 1.1.1.8.2.1 martin <li>UTF-16
1445 1.1.1.8.2.1 martin </li>
1446 1.1.1.8.2.1 martin
1447 1.1.1.8.2.1 martin <li>ISO-8859-1
1448 1.1.1.8.2.1 martin </li>
1449 1.1.1.8.2.1 martin </ul>
1450 1.1.1.8.2.1 martin
1451 1.1.1.8.2.1 martin <p>
1452 1.1.1.8.2.1 martin Any other value will invoke a call to the UnknownEncodingHandler.
1453 1.1.1.8.2.1 martin </p>
1454 1.1.1.8.2.1 martin </div>
1455 1.1.1.8.2.1 martin
1456 1.1.1.8.2.1 martin <h4 id="XML_ParserCreateNS">
1457 1.1.1.8.2.1 martin XML_ParserCreateNS
1458 1.1.1.8.2.1 martin </h4>
1459 1.1 tron
1460 1.1.1.8.2.1 martin <pre class="fcndec">
1461 1.1 tron XML_Parser XMLCALL
1462 1.1 tron XML_ParserCreateNS(const XML_Char *encoding,
1463 1.1 tron XML_Char sep);
1464 1.1 tron </pre>
1465 1.1.1.8.2.1 martin <div class="fcndef">
1466 1.1.1.8.2.1 martin Constructs a new parser that has namespace processing in effect. Namespace
1467 1.1.1.8.2.1 martin expanded element names and attribute names are returned as a concatenation of the
1468 1.1.1.8.2.1 martin namespace URI, <em>sep</em>, and the local part of the name. This means that you
1469 1.1.1.8.2.1 martin should pick a character for <em>sep</em> that can't be part of an URI. Since
1470 1.1.1.8.2.1 martin Expat does not check namespace URIs for conformance, the only safe choice for a
1471 1.1.1.8.2.1 martin namespace separator is a character that is illegal in XML. For instance,
1472 1.1.1.8.2.1 martin <code>'\xFF'</code> is not legal in UTF-8, and <code>'\xFFFF'</code> is not legal
1473 1.1.1.8.2.1 martin in UTF-16. There is a special case when <em>sep</em> is the null character
1474 1.1.1.8.2.1 martin <code>'\0'</code>: the namespace URI and the local part will be concatenated
1475 1.1.1.8.2.1 martin without any separator - this is intended to support RDF processors. It is a
1476 1.1.1.8.2.1 martin programming error to use the null separator with <a href=
1477 1.1.1.8.2.1 martin "#XML_SetReturnNSTriplet">namespace triplets</a>.
1478 1.1.1.8.2.1 martin </div>
1479 1.1.1.8.2.1 martin
1480 1.1.1.8.2.1 martin <p>
1481 1.1.1.8.2.1 martin <strong>Note:</strong> Expat does not validate namespace URIs (beyond encoding)
1482 1.1.1.8.2.1 martin against RFC 3986 today (and is not required to do so with regard to the XML 1.0
1483 1.1.1.8.2.1 martin namespaces specification) but it may start doing that in future releases. Before
1484 1.1.1.8.2.1 martin that, an application using Expat must be ready to receive namespace URIs
1485 1.1.1.8.2.1 martin containing non-URI characters.
1486 1.1.1.8.2.1 martin </p>
1487 1.1.1.8.2.1 martin
1488 1.1.1.8.2.1 martin <h4 id="XML_ParserCreate_MM">
1489 1.1.1.8.2.1 martin XML_ParserCreate_MM
1490 1.1.1.8.2.1 martin </h4>
1491 1.1.1.7 wiz
1492 1.1.1.8.2.1 martin <pre class="fcndec">
1493 1.1 tron XML_Parser XMLCALL
1494 1.1 tron XML_ParserCreate_MM(const XML_Char *encoding,
1495 1.1 tron const XML_Memory_Handling_Suite *ms,
1496 1.1.1.8.2.1 martin const XML_Char *sep);
1497 1.1 tron </pre>
1498 1.1.1.8.2.1 martin
1499 1.1.1.8.2.1 martin <pre class="signature">
1500 1.1 tron typedef struct {
1501 1.1 tron void *(XMLCALL *malloc_fcn)(size_t size);
1502 1.1 tron void *(XMLCALL *realloc_fcn)(void *ptr, size_t size);
1503 1.1 tron void (XMLCALL *free_fcn)(void *ptr);
1504 1.1 tron } XML_Memory_Handling_Suite;
1505 1.1 tron </pre>
1506 1.1.1.8.2.1 martin <div class="fcndef">
1507 1.1.1.8.2.1 martin <p>
1508 1.1.1.8.2.1 martin Construct a new parser using the suite of memory handling functions specified
1509 1.1.1.8.2.1 martin in <code>ms</code>. If <code>ms</code> is <code>NULL</code>, then use the
1510 1.1.1.8.2.1 martin standard set of memory management functions. If <code>sep</code> is
1511 1.1.1.8.2.1 martin non-<code>NULL</code>, then namespace processing is enabled in the created
1512 1.1.1.8.2.1 martin parser and the character pointed at by sep is used as the separator between the
1513 1.1.1.8.2.1 martin namespace URI and the local part of the name.
1514 1.1.1.8.2.1 martin </p>
1515 1.1.1.8.2.1 martin </div>
1516 1.1.1.8.2.1 martin
1517 1.1.1.8.2.1 martin <h4 id="XML_ExternalEntityParserCreate">
1518 1.1.1.8.2.1 martin XML_ExternalEntityParserCreate
1519 1.1.1.8.2.1 martin </h4>
1520 1.1 tron
1521 1.1.1.8.2.1 martin <pre class="fcndec">
1522 1.1 tron XML_Parser XMLCALL
1523 1.1 tron XML_ExternalEntityParserCreate(XML_Parser p,
1524 1.1 tron const XML_Char *context,
1525 1.1 tron const XML_Char *encoding);
1526 1.1 tron </pre>
1527 1.1.1.8.2.1 martin <div class="fcndef">
1528 1.1.1.8.2.1 martin <p>
1529 1.1.1.8.2.1 martin Construct a new <code>XML_Parser</code> object for parsing an external general
1530 1.1.1.8.2.1 martin entity. Context is the context argument passed in a call to a
1531 1.1.1.8.2.1 martin ExternalEntityRefHandler. Other state information such as handlers, user data,
1532 1.1.1.8.2.1 martin namespace processing is inherited from the parser passed as the 1st argument.
1533 1.1.1.8.2.1 martin So you shouldn't need to call any of the behavior changing functions on this
1534 1.1.1.8.2.1 martin parser (unless you want it to act differently than the parent parser).
1535 1.1.1.8.2.1 martin </p>
1536 1.1.1.8.2.1 martin
1537 1.1.1.8.2.1 martin <p>
1538 1.1.1.8.2.1 martin <strong>Note:</strong> Please be sure to free subparsers created by
1539 1.1.1.8.2.1 martin <code><a href=
1540 1.1.1.8.2.1 martin "#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></code>
1541 1.1.1.8.2.1 martin <em>prior to</em> freeing their related parent parser, as subparsers reference
1542 1.1.1.8.2.1 martin and use parts of their respective parent parser, internally. Parent parsers
1543 1.1.1.8.2.1 martin must outlive subparsers.
1544 1.1.1.8.2.1 martin </p>
1545 1.1.1.8.2.1 martin </div>
1546 1.1.1.8.2.1 martin
1547 1.1.1.8.2.1 martin <h4 id="XML_ParserFree">
1548 1.1.1.8.2.1 martin XML_ParserFree
1549 1.1.1.8.2.1 martin </h4>
1550 1.1 tron
1551 1.1.1.8.2.1 martin <pre class="fcndec">
1552 1.1 tron void XMLCALL
1553 1.1 tron XML_ParserFree(XML_Parser p);
1554 1.1 tron </pre>
1555 1.1.1.8.2.1 martin <div class="fcndef">
1556 1.1.1.8.2.1 martin <p>
1557 1.1.1.8.2.1 martin Free memory used by the parser.
1558 1.1.1.8.2.1 martin </p>
1559 1.1.1.8.2.1 martin
1560 1.1.1.8.2.1 martin <p>
1561 1.1.1.8.2.1 martin <strong>Note:</strong> Your application is responsible for freeing any memory
1562 1.1.1.8.2.1 martin associated with <a href="#userdata">user data</a>.
1563 1.1.1.8.2.1 martin </p>
1564 1.1.1.8.2.1 martin
1565 1.1.1.8.2.1 martin <p>
1566 1.1.1.8.2.1 martin <strong>Note:</strong> Please be sure to free subparsers created by
1567 1.1.1.8.2.1 martin <code><a href=
1568 1.1.1.8.2.1 martin "#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></code>
1569 1.1.1.8.2.1 martin <em>prior to</em> freeing their related parent parser, as subparsers reference
1570 1.1.1.8.2.1 martin and use parts of their respective parent parser, internally. Parent parsers
1571 1.1.1.8.2.1 martin must outlive subparsers.
1572 1.1.1.8.2.1 martin </p>
1573 1.1.1.8.2.1 martin </div>
1574 1.1.1.8.2.1 martin
1575 1.1.1.8.2.1 martin <h4 id="XML_ParserReset">
1576 1.1.1.8.2.1 martin XML_ParserReset
1577 1.1.1.8.2.1 martin </h4>
1578 1.1 tron
1579 1.1.1.8.2.1 martin <pre class="fcndec">
1580 1.1 tron XML_Bool XMLCALL
1581 1.1 tron XML_ParserReset(XML_Parser p,
1582 1.1 tron const XML_Char *encoding);
1583 1.1 tron </pre>
1584 1.1.1.8.2.1 martin <div class="fcndef">
1585 1.1.1.8.2.1 martin Clean up the memory structures maintained by the parser so that it may be used
1586 1.1.1.8.2.1 martin again. After this has been called, <code>parser</code> is ready to start parsing
1587 1.1.1.8.2.1 martin a new document. All handlers are cleared from the parser, except for the
1588 1.1.1.8.2.1 martin unknownEncodingHandler. The parser's external state is re-initialized except for
1589 1.1.1.8.2.1 martin the values of ns and ns_triplets. This function may not be used on a parser
1590 1.1.1.8.2.1 martin created using <code><a href=
1591 1.1.1.8.2.1 martin "#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></code>; it
1592 1.1.1.8.2.1 martin will return <code>XML_FALSE</code> in that case. Returns <code>XML_TRUE</code> on
1593 1.1.1.8.2.1 martin success. Your application is responsible for dealing with any memory associated
1594 1.1.1.8.2.1 martin with <a href="#userdata">user data</a>.
1595 1.1.1.8.2.1 martin </div>
1596 1.1.1.8.2.1 martin
1597 1.1.1.8.2.1 martin <h3>
1598 1.1.1.8.2.1 martin <a id="parsing" name="parsing">Parsing</a>
1599 1.1.1.8.2.1 martin </h3>
1600 1.1.1.8.2.1 martin
1601 1.1.1.8.2.1 martin <p>
1602 1.1.1.8.2.1 martin To state the obvious: the three parsing functions <code><a href=
1603 1.1.1.8.2.1 martin "#XML_Parse">XML_Parse</a></code>, <code><a href=
1604 1.1.1.8.2.1 martin "#XML_ParseBuffer">XML_ParseBuffer</a></code> and <code><a href=
1605 1.1.1.8.2.2 martin "#XML_GetBuffer">XML_GetBuffer</a></code> as well as the two cleanup functions
1606 1.1.1.8.2.2 martin <code><a href="#XML_ParserFree">XML_ParserFree</a></code> and <code><a href=
1607 1.1.1.8.2.2 martin "#XML_ParserReset">XML_ParserReset</a></code> must not be called from within a
1608 1.1.1.8.2.1 martin handler unless they operate on a separate parser instance, that is, one that did
1609 1.1.1.8.2.1 martin not call the handler. For example, it is OK to call the parsing functions from
1610 1.1.1.8.2.1 martin within an <code>XML_ExternalEntityRefHandler</code>, if they apply to the parser
1611 1.1.1.8.2.1 martin created by <code><a href=
1612 1.1.1.8.2.1 martin "#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></code>.
1613 1.1.1.8.2.1 martin </p>
1614 1.1.1.8.2.1 martin
1615 1.1.1.8.2.1 martin <p>
1616 1.1.1.8.2.1 martin Note: The <code>len</code> argument passed to these functions should be
1617 1.1.1.8.2.1 martin considerably less than the maximum value for an integer, as it could create an
1618 1.1.1.8.2.1 martin integer overflow situation if the added lengths of a buffer and the unprocessed
1619 1.1.1.8.2.1 martin portion of the previous buffer exceed the maximum integer value. Input data at
1620 1.1.1.8.2.1 martin the end of a buffer will remain unprocessed if it is part of an XML token for
1621 1.1.1.8.2.1 martin which the end is not part of that buffer.
1622 1.1.1.8.2.1 martin </p>
1623 1.1.1.8.2.1 martin
1624 1.1.1.8.2.1 martin <p>
1625 1.1.1.8.2.1 martin <a id="isFinal" name="isFinal"></a>The application <em>must</em> make a
1626 1.1.1.8.2.1 martin concluding <code><a href="#XML_Parse">XML_Parse</a></code> or <code><a href=
1627 1.1.1.8.2.1 martin "#XML_ParseBuffer">XML_ParseBuffer</a></code> call with <code>isFinal</code> set
1628 1.1.1.8.2.1 martin to <code>XML_TRUE</code>.
1629 1.1.1.8.2.1 martin </p>
1630 1.1.1.8.2.1 martin
1631 1.1.1.8.2.1 martin <h4 id="XML_Parse">
1632 1.1.1.8.2.1 martin XML_Parse
1633 1.1.1.8.2.1 martin </h4>
1634 1.1.1.7 wiz
1635 1.1.1.8.2.1 martin <pre class="fcndec">
1636 1.1 tron enum XML_Status XMLCALL
1637 1.1 tron XML_Parse(XML_Parser p,
1638 1.1 tron const char *s,
1639 1.1 tron int len,
1640 1.1 tron int isFinal);
1641 1.1 tron </pre>
1642 1.1.1.8.2.1 martin
1643 1.1.1.8.2.1 martin <pre class="signature">
1644 1.1 tron enum XML_Status {
1645 1.1 tron XML_STATUS_ERROR = 0,
1646 1.1 tron XML_STATUS_OK = 1
1647 1.1 tron };
1648 1.1 tron </pre>
1649 1.1.1.8.2.1 martin <div class="fcndef">
1650 1.1.1.8.2.1 martin <p>
1651 1.1.1.8.2.1 martin Parse some more of the document. The string <code>s</code> is a buffer
1652 1.1.1.8.2.1 martin containing part (or perhaps all) of the document. The number of bytes of s that
1653 1.1.1.8.2.1 martin are part of the document is indicated by <code>len</code>. This means that
1654 1.1.1.8.2.1 martin <code>s</code> doesn't have to be null-terminated. It also means that if
1655 1.1.1.8.2.1 martin <code>len</code> is larger than the number of bytes in the block of memory that
1656 1.1.1.8.2.1 martin <code>s</code> points at, then a memory fault is likely. Negative values for
1657 1.1.1.8.2.1 martin <code>len</code> are rejected since Expat 2.2.1. The <code>isFinal</code>
1658 1.1.1.8.2.1 martin parameter informs the parser that this is the last piece of the document.
1659 1.1.1.8.2.1 martin Frequently, the last piece is empty (i.e. <code>len</code> is zero.)
1660 1.1.1.8.2.1 martin </p>
1661 1.1.1.8.2.1 martin
1662 1.1.1.8.2.1 martin <p>
1663 1.1.1.8.2.1 martin If a parse error occurred, it returns <code>XML_STATUS_ERROR</code>. Otherwise
1664 1.1.1.8.2.1 martin it returns <code>XML_STATUS_OK</code> value. Note that regardless of the return
1665 1.1.1.8.2.1 martin value, there is no guarantee that all provided input has been parsed; only
1666 1.1.1.8.2.1 martin after <a href="#isFinal">the concluding call</a> will all handler callbacks and
1667 1.1.1.8.2.1 martin parsing errors have happened.
1668 1.1.1.8.2.1 martin </p>
1669 1.1.1.8.2.1 martin
1670 1.1.1.8.2.1 martin <p>
1671 1.1.1.8.2.1 martin Simplified, <code>XML_Parse</code> can be considered a convenience wrapper that
1672 1.1.1.8.2.1 martin is pairing calls to <code><a href="#XML_GetBuffer">XML_GetBuffer</a></code> and
1673 1.1.1.8.2.1 martin <code><a href="#XML_ParseBuffer">XML_ParseBuffer</a></code> (when Expat is
1674 1.1.1.8.2.1 martin built with macro <code>XML_CONTEXT_BYTES</code> defined to a positive value,
1675 1.1.1.8.2.1 martin which is both common and default). <code>XML_Parse</code> is then functionally
1676 1.1.1.8.2.1 martin equivalent to calling <code><a href="#XML_GetBuffer">XML_GetBuffer</a></code>,
1677 1.1.1.8.2.1 martin <code>memcpy</code>, and <code><a href=
1678 1.1.1.8.2.1 martin "#XML_ParseBuffer">XML_ParseBuffer</a></code>.
1679 1.1.1.8.2.1 martin </p>
1680 1.1.1.8.2.1 martin
1681 1.1.1.8.2.1 martin <p>
1682 1.1.1.8.2.1 martin To avoid double copying of the input, direct use of functions <code><a href=
1683 1.1.1.8.2.1 martin "#XML_GetBuffer">XML_GetBuffer</a></code> and <code><a href=
1684 1.1.1.8.2.1 martin "#XML_ParseBuffer">XML_ParseBuffer</a></code> is advised for most production
1685 1.1.1.8.2.1 martin use, e.g. if you're using <code>read</code> or similar functionality to fill
1686 1.1.1.8.2.1 martin your buffers, fill directly into the buffer from <code><a href=
1687 1.1.1.8.2.1 martin "#XML_GetBuffer">XML_GetBuffer</a></code>, then parse with <code><a href=
1688 1.1.1.8.2.1 martin "#XML_ParseBuffer">XML_ParseBuffer</a></code>.
1689 1.1.1.8.2.1 martin </p>
1690 1.1.1.8.2.1 martin </div>
1691 1.1.1.8.2.1 martin
1692 1.1.1.8.2.1 martin <h4 id="XML_ParseBuffer">
1693 1.1.1.8.2.1 martin XML_ParseBuffer
1694 1.1.1.8.2.1 martin </h4>
1695 1.1 tron
1696 1.1.1.8.2.1 martin <pre class="fcndec">
1697 1.1 tron enum XML_Status XMLCALL
1698 1.1 tron XML_ParseBuffer(XML_Parser p,
1699 1.1 tron int len,
1700 1.1 tron int isFinal);
1701 1.1 tron </pre>
1702 1.1.1.8.2.1 martin <div class="fcndef">
1703 1.1.1.8.2.1 martin <p>
1704 1.1.1.8.2.1 martin This is just like <code><a href="#XML_Parse">XML_Parse</a></code>, except in
1705 1.1.1.8.2.1 martin this case Expat provides the buffer. By obtaining the buffer from Expat with
1706 1.1.1.8.2.1 martin the <code><a href="#XML_GetBuffer">XML_GetBuffer</a></code> function, the
1707 1.1.1.8.2.1 martin application can avoid double copying of the input.
1708 1.1.1.8.2.1 martin </p>
1709 1.1.1.8.2.1 martin
1710 1.1.1.8.2.1 martin <p>
1711 1.1.1.8.2.1 martin Negative values for <code>len</code> are rejected since Expat 2.6.3.
1712 1.1.1.8.2.1 martin </p>
1713 1.1.1.8.2.1 martin </div>
1714 1.1.1.8.2.1 martin
1715 1.1.1.8.2.1 martin <h4 id="XML_GetBuffer">
1716 1.1.1.8.2.1 martin XML_GetBuffer
1717 1.1.1.8.2.1 martin </h4>
1718 1.1 tron
1719 1.1.1.8.2.1 martin <pre class="fcndec">
1720 1.1 tron void * XMLCALL
1721 1.1 tron XML_GetBuffer(XML_Parser p,
1722 1.1 tron int len);
1723 1.1 tron </pre>
1724 1.1.1.8.2.1 martin <div class="fcndef">
1725 1.1.1.8.2.1 martin Obtain a buffer of size <code>len</code> to read a piece of the document into. A
1726 1.1.1.8.2.1 martin <code>NULL</code> value is returned if Expat can't allocate enough memory for
1727 1.1.1.8.2.1 martin this buffer. A <code>NULL</code> value may also be returned if <code>len</code>
1728 1.1.1.8.2.1 martin is zero. This has to be called prior to every call to <code><a href=
1729 1.1.1.8.2.1 martin "#XML_ParseBuffer">XML_ParseBuffer</a></code>. A typical use would look like
1730 1.1.1.8.2.1 martin this:
1731 1.1 tron
1732 1.1.1.8.2.1 martin <pre class="eg">
1733 1.1 tron for (;;) {
1734 1.1 tron int bytes_read;
1735 1.1 tron void *buff = XML_GetBuffer(p, BUFF_SIZE);
1736 1.1 tron if (buff == NULL) {
1737 1.1 tron /* handle error */
1738 1.1 tron }
1739 1.1 tron
1740 1.1 tron bytes_read = read(docfd, buff, BUFF_SIZE);
1741 1.1 tron if (bytes_read < 0) {
1742 1.1 tron /* handle error */
1743 1.1 tron }
1744 1.1 tron
1745 1.1 tron if (! XML_ParseBuffer(p, bytes_read, bytes_read == 0)) {
1746 1.1 tron /* handle parse error */
1747 1.1 tron }
1748 1.1 tron
1749 1.1 tron if (bytes_read == 0)
1750 1.1 tron break;
1751 1.1 tron }
1752 1.1 tron </pre>
1753 1.1.1.8.2.1 martin </div>
1754 1.1 tron
1755 1.1.1.8.2.1 martin <h4 id="XML_StopParser">
1756 1.1.1.8.2.1 martin XML_StopParser
1757 1.1.1.8.2.1 martin </h4>
1758 1.1.1.8.2.1 martin
1759 1.1.1.8.2.1 martin <pre class="fcndec">
1760 1.1 tron enum XML_Status XMLCALL
1761 1.1 tron XML_StopParser(XML_Parser p,
1762 1.1 tron XML_Bool resumable);
1763 1.1 tron </pre>
1764 1.1.1.8.2.1 martin <div class="fcndef">
1765 1.1.1.8.2.1 martin <p>
1766 1.1.1.8.2.1 martin Stops parsing, causing <code><a href="#XML_Parse">XML_Parse</a></code> or
1767 1.1.1.8.2.1 martin <code><a href="#XML_ParseBuffer">XML_ParseBuffer</a></code> to return. Must be
1768 1.1.1.8.2.1 martin called from within a call-back handler, except when aborting (when
1769 1.1.1.8.2.1 martin <code>resumable</code> is <code>XML_FALSE</code>) an already suspended parser.
1770 1.1.1.8.2.1 martin Some call-backs may still follow because they would otherwise get lost,
1771 1.1.1.8.2.1 martin including
1772 1.1.1.8.2.1 martin </p>
1773 1.1.1.8.2.1 martin
1774 1.1.1.8.2.1 martin <ul>
1775 1.1.1.8.2.1 martin <li>the end element handler for empty elements when stopped in the start
1776 1.1.1.8.2.1 martin element handler,
1777 1.1.1.8.2.1 martin </li>
1778 1.1.1.8.2.1 martin
1779 1.1.1.8.2.1 martin <li>the end namespace declaration handler when stopped in the end element
1780 1.1.1.8.2.1 martin handler,
1781 1.1.1.8.2.1 martin </li>
1782 1.1.1.8.2.1 martin
1783 1.1.1.8.2.1 martin <li>the character data handler when stopped in the character data handler while
1784 1.1.1.8.2.1 martin making multiple call-backs on a contiguous chunk of characters,
1785 1.1.1.8.2.1 martin </li>
1786 1.1.1.8.2.1 martin </ul>
1787 1.1.1.8.2.1 martin
1788 1.1.1.8.2.1 martin <p>
1789 1.1.1.8.2.1 martin and possibly others.
1790 1.1.1.8.2.1 martin </p>
1791 1.1.1.8.2.1 martin
1792 1.1.1.8.2.1 martin <p>
1793 1.1.1.8.2.1 martin This can be called from most handlers, including DTD related call-backs, except
1794 1.1.1.8.2.1 martin when parsing an external parameter entity and <code>resumable</code> is
1795 1.1.1.8.2.1 martin <code>XML_TRUE</code>. Returns <code>XML_STATUS_OK</code> when successful,
1796 1.1.1.8.2.1 martin <code>XML_STATUS_ERROR</code> otherwise. The possible error codes are:
1797 1.1.1.8.2.1 martin </p>
1798 1.1.1.8.2.1 martin
1799 1.1.1.8.2.1 martin <dl>
1800 1.1.1.8.2.1 martin <dt>
1801 1.1.1.8.2.1 martin <code>XML_ERROR_NOT_STARTED</code>
1802 1.1.1.8.2.1 martin </dt>
1803 1.1.1.8.2.1 martin
1804 1.1.1.8.2.1 martin <dd>
1805 1.1.1.8.2.1 martin when stopping or suspending a parser before it has started, added in Expat
1806 1.1.1.8.2.1 martin 2.6.4.
1807 1.1.1.8.2.1 martin </dd>
1808 1.1.1.8.2.1 martin
1809 1.1.1.8.2.1 martin <dt>
1810 1.1.1.8.2.1 martin <code>XML_ERROR_SUSPENDED</code>
1811 1.1.1.8.2.1 martin </dt>
1812 1.1.1.8.2.1 martin
1813 1.1.1.8.2.1 martin <dd>
1814 1.1.1.8.2.1 martin when suspending an already suspended parser.
1815 1.1.1.8.2.1 martin </dd>
1816 1.1.1.8.2.1 martin
1817 1.1.1.8.2.1 martin <dt>
1818 1.1.1.8.2.1 martin <code>XML_ERROR_FINISHED</code>
1819 1.1.1.8.2.1 martin </dt>
1820 1.1.1.8.2.1 martin
1821 1.1.1.8.2.1 martin <dd>
1822 1.1.1.8.2.1 martin when the parser has already finished.
1823 1.1.1.8.2.1 martin </dd>
1824 1.1.1.8.2.1 martin
1825 1.1.1.8.2.1 martin <dt>
1826 1.1.1.8.2.1 martin <code>XML_ERROR_SUSPEND_PE</code>
1827 1.1.1.8.2.1 martin </dt>
1828 1.1.1.8.2.1 martin
1829 1.1.1.8.2.1 martin <dd>
1830 1.1.1.8.2.1 martin when suspending while parsing an external PE.
1831 1.1.1.8.2.1 martin </dd>
1832 1.1.1.8.2.1 martin </dl>
1833 1.1.1.8.2.1 martin
1834 1.1.1.8.2.1 martin <p>
1835 1.1.1.8.2.1 martin Since the stop/resume feature requires application support in the outer parsing
1836 1.1.1.8.2.1 martin loop, it is an error to call this function for a parser not being handled
1837 1.1.1.8.2.1 martin appropriately; see <a href="#stop-resume">Temporarily Stopping Parsing</a> for
1838 1.1.1.8.2.1 martin more information.
1839 1.1.1.8.2.1 martin </p>
1840 1.1.1.8.2.1 martin
1841 1.1.1.8.2.1 martin <p>
1842 1.1.1.8.2.1 martin When <code>resumable</code> is <code>XML_TRUE</code> then parsing is
1843 1.1.1.8.2.1 martin <em>suspended</em>, that is, <code><a href="#XML_Parse">XML_Parse</a></code>
1844 1.1.1.8.2.1 martin and <code><a href="#XML_ParseBuffer">XML_ParseBuffer</a></code> return
1845 1.1.1.8.2.1 martin <code>XML_STATUS_SUSPENDED</code>. Otherwise, parsing is <em>aborted</em>, that
1846 1.1.1.8.2.1 martin is, <code><a href="#XML_Parse">XML_Parse</a></code> and <code><a href=
1847 1.1.1.8.2.1 martin "#XML_ParseBuffer">XML_ParseBuffer</a></code> return
1848 1.1.1.8.2.1 martin <code>XML_STATUS_ERROR</code> with error code <code>XML_ERROR_ABORTED</code>.
1849 1.1.1.8.2.1 martin </p>
1850 1.1.1.8.2.1 martin
1851 1.1.1.8.2.1 martin <p>
1852 1.1.1.8.2.1 martin <strong>Note:</strong> This will be applied to the current parser instance
1853 1.1.1.8.2.1 martin only, that is, if there is a parent parser then it will continue parsing when
1854 1.1.1.8.2.1 martin the external entity reference handler returns. It is up to the implementation
1855 1.1.1.8.2.1 martin of that handler to call <code><a href=
1856 1.1.1.8.2.1 martin "#XML_StopParser">XML_StopParser</a></code> on the parent parser (recursively),
1857 1.1.1.8.2.1 martin if one wants to stop parsing altogether.
1858 1.1.1.8.2.1 martin </p>
1859 1.1.1.8.2.1 martin
1860 1.1.1.8.2.1 martin <p>
1861 1.1.1.8.2.1 martin When suspended, parsing can be resumed by calling <code><a href=
1862 1.1.1.8.2.1 martin "#XML_ResumeParser">XML_ResumeParser</a></code>.
1863 1.1.1.8.2.1 martin </p>
1864 1.1.1.8.2.1 martin
1865 1.1.1.8.2.1 martin <p>
1866 1.1.1.8.2.1 martin New in Expat 1.95.8.
1867 1.1.1.8.2.1 martin </p>
1868 1.1.1.8.2.1 martin </div>
1869 1.1.1.8.2.1 martin
1870 1.1.1.8.2.1 martin <h4 id="XML_ResumeParser">
1871 1.1.1.8.2.1 martin XML_ResumeParser
1872 1.1.1.8.2.1 martin </h4>
1873 1.1 tron
1874 1.1.1.8.2.1 martin <pre class="fcndec">
1875 1.1 tron enum XML_Status XMLCALL
1876 1.1 tron XML_ResumeParser(XML_Parser p);
1877 1.1 tron </pre>
1878 1.1.1.8.2.1 martin <div class="fcndef">
1879 1.1.1.8.2.1 martin <p>
1880 1.1.1.8.2.1 martin Resumes parsing after it has been suspended with <code><a href=
1881 1.1.1.8.2.1 martin "#XML_StopParser">XML_StopParser</a></code>. Must not be called from within a
1882 1.1.1.8.2.1 martin handler call-back. Returns same status codes as <code><a href=
1883 1.1.1.8.2.1 martin "#XML_Parse">XML_Parse</a></code> or <code><a href=
1884 1.1.1.8.2.1 martin "#XML_ParseBuffer">XML_ParseBuffer</a></code>. An additional error code,
1885 1.1.1.8.2.1 martin <code>XML_ERROR_NOT_SUSPENDED</code>, will be returned if the parser was not
1886 1.1.1.8.2.1 martin currently suspended.
1887 1.1.1.8.2.1 martin </p>
1888 1.1.1.8.2.1 martin
1889 1.1.1.8.2.1 martin <p>
1890 1.1.1.8.2.1 martin <strong>Note:</strong> This must be called on the most deeply nested child
1891 1.1.1.8.2.1 martin parser instance first, and on its parent parser only after the child parser has
1892 1.1.1.8.2.1 martin finished, to be applied recursively until the document entity's parser is
1893 1.1.1.8.2.1 martin restarted. That is, the parent parser will not resume by itself and it is up to
1894 1.1.1.8.2.1 martin the application to call <code><a href=
1895 1.1.1.8.2.1 martin "#XML_ResumeParser">XML_ResumeParser</a></code> on it at the appropriate
1896 1.1.1.8.2.1 martin moment.
1897 1.1.1.8.2.1 martin </p>
1898 1.1.1.8.2.1 martin
1899 1.1.1.8.2.1 martin <p>
1900 1.1.1.8.2.1 martin New in Expat 1.95.8.
1901 1.1.1.8.2.1 martin </p>
1902 1.1.1.8.2.1 martin </div>
1903 1.1.1.8.2.1 martin
1904 1.1.1.8.2.1 martin <h4 id="XML_GetParsingStatus">
1905 1.1.1.8.2.1 martin XML_GetParsingStatus
1906 1.1.1.8.2.1 martin </h4>
1907 1.1 tron
1908 1.1.1.8.2.1 martin <pre class="fcndec">
1909 1.1 tron void XMLCALL
1910 1.1 tron XML_GetParsingStatus(XML_Parser p,
1911 1.1 tron XML_ParsingStatus *status);
1912 1.1 tron </pre>
1913 1.1.1.8.2.1 martin
1914 1.1.1.8.2.1 martin <pre class="signature">
1915 1.1 tron enum XML_Parsing {
1916 1.1 tron XML_INITIALIZED,
1917 1.1 tron XML_PARSING,
1918 1.1 tron XML_FINISHED,
1919 1.1 tron XML_SUSPENDED
1920 1.1 tron };
1921 1.1 tron
1922 1.1 tron typedef struct {
1923 1.1 tron enum XML_Parsing parsing;
1924 1.1 tron XML_Bool finalBuffer;
1925 1.1 tron } XML_ParsingStatus;
1926 1.1 tron </pre>
1927 1.1.1.8.2.1 martin <div class="fcndef">
1928 1.1.1.8.2.1 martin <p>
1929 1.1.1.8.2.1 martin Returns status of parser with respect to being initialized, parsing, finished,
1930 1.1.1.8.2.1 martin or suspended, and whether the final buffer is being processed. The
1931 1.1.1.8.2.1 martin <code>status</code> parameter <em>must not</em> be <code>NULL</code>.
1932 1.1.1.8.2.1 martin </p>
1933 1.1.1.8.2.1 martin
1934 1.1.1.8.2.1 martin <p>
1935 1.1.1.8.2.1 martin New in Expat 1.95.8.
1936 1.1.1.8.2.1 martin </p>
1937 1.1.1.8.2.1 martin </div>
1938 1.1.1.8.2.1 martin
1939 1.1.1.8.2.1 martin <h3>
1940 1.1.1.8.2.1 martin <a id="setting" name="setting">Handler Setting</a>
1941 1.1.1.8.2.1 martin </h3>
1942 1.1.1.8.2.1 martin
1943 1.1.1.8.2.1 martin <p>
1944 1.1.1.8.2.1 martin Although handlers are typically set prior to parsing and left alone, an
1945 1.1.1.8.2.1 martin application may choose to set or change the handler for a parsing event while the
1946 1.1.1.8.2.1 martin parse is in progress. For instance, your application may choose to ignore all
1947 1.1.1.8.2.1 martin text not descended from a <code>para</code> element. One way it could do this is
1948 1.1.1.8.2.1 martin to set the character handler when a para start tag is seen, and unset it for the
1949 1.1.1.8.2.1 martin corresponding end tag.
1950 1.1.1.8.2.1 martin </p>
1951 1.1.1.8.2.1 martin
1952 1.1.1.8.2.1 martin <p>
1953 1.1.1.8.2.1 martin A handler may be <em>unset</em> by providing a <code>NULL</code> pointer to the
1954 1.1.1.8.2.1 martin appropriate handler setter. None of the handler setting functions have a return
1955 1.1.1.8.2.1 martin value.
1956 1.1.1.8.2.1 martin </p>
1957 1.1.1.8.2.1 martin
1958 1.1.1.8.2.1 martin <p>
1959 1.1.1.8.2.1 martin Your handlers will be receiving strings in arrays of type <code>XML_Char</code>.
1960 1.1.1.8.2.1 martin This type is conditionally defined in expat.h as either <code>char</code>,
1961 1.1.1.8.2.1 martin <code>wchar_t</code> or <code>unsigned short</code>. The former implies UTF-8
1962 1.1.1.8.2.1 martin encoding, the latter two imply UTF-16 encoding. Note that you'll receive them in
1963 1.1.1.8.2.1 martin this form independent of the original encoding of the document.
1964 1.1.1.8.2.1 martin </p>
1965 1.1.1.8.2.1 martin
1966 1.1.1.8.2.1 martin <div class="handler">
1967 1.1.1.8.2.1 martin <h4 id="XML_SetStartElementHandler">
1968 1.1.1.8.2.1 martin XML_SetStartElementHandler
1969 1.1.1.8.2.1 martin </h4>
1970 1.1.1.8.2.1 martin
1971 1.1.1.8.2.1 martin <pre class="setter">
1972 1.1 tron void XMLCALL
1973 1.1 tron XML_SetStartElementHandler(XML_Parser p,
1974 1.1 tron XML_StartElementHandler start);
1975 1.1 tron </pre>
1976 1.1.1.8.2.1 martin
1977 1.1.1.8.2.1 martin <pre class="signature">
1978 1.1 tron typedef void
1979 1.1 tron (XMLCALL *XML_StartElementHandler)(void *userData,
1980 1.1 tron const XML_Char *name,
1981 1.1 tron const XML_Char **atts);
1982 1.1 tron </pre>
1983 1.1.1.8.2.1 martin <p>
1984 1.1.1.8.2.1 martin Set handler for start (and empty) tags. Attributes are passed to the start
1985 1.1.1.8.2.1 martin handler as a pointer to a vector of char pointers. Each attribute seen in a
1986 1.1.1.8.2.1 martin start (or empty) tag occupies 2 consecutive places in this vector: the
1987 1.1.1.8.2.1 martin attribute name followed by the attribute value. These pairs are terminated by a
1988 1.1.1.8.2.1 martin <code>NULL</code> pointer.
1989 1.1.1.8.2.1 martin </p>
1990 1.1.1.8.2.1 martin
1991 1.1.1.8.2.1 martin <p>
1992 1.1.1.8.2.1 martin Note that an empty tag generates a call to both start and end handlers (in that
1993 1.1.1.8.2.1 martin order).
1994 1.1.1.8.2.1 martin </p>
1995 1.1.1.8.2.1 martin </div>
1996 1.1.1.8.2.1 martin
1997 1.1.1.8.2.1 martin <div class="handler">
1998 1.1.1.8.2.1 martin <h4 id="XML_SetEndElementHandler">
1999 1.1.1.8.2.1 martin XML_SetEndElementHandler
2000 1.1.1.8.2.1 martin </h4>
2001 1.1.1.8.2.1 martin
2002 1.1.1.8.2.1 martin <pre class="setter">
2003 1.1 tron void XMLCALL
2004 1.1 tron XML_SetEndElementHandler(XML_Parser p,
2005 1.1 tron XML_EndElementHandler);
2006 1.1 tron </pre>
2007 1.1.1.8.2.1 martin
2008 1.1.1.8.2.1 martin <pre class="signature">
2009 1.1 tron typedef void
2010 1.1 tron (XMLCALL *XML_EndElementHandler)(void *userData,
2011 1.1 tron const XML_Char *name);
2012 1.1 tron </pre>
2013 1.1.1.8.2.1 martin <p>
2014 1.1.1.8.2.1 martin Set handler for end (and empty) tags. As noted above, an empty tag generates a
2015 1.1.1.8.2.1 martin call to both start and end handlers.
2016 1.1.1.8.2.1 martin </p>
2017 1.1.1.8.2.1 martin </div>
2018 1.1.1.8.2.1 martin
2019 1.1.1.8.2.1 martin <div class="handler">
2020 1.1.1.8.2.1 martin <h4 id="XML_SetElementHandler">
2021 1.1.1.8.2.1 martin XML_SetElementHandler
2022 1.1.1.8.2.1 martin </h4>
2023 1.1.1.8.2.1 martin
2024 1.1.1.8.2.1 martin <pre class="setter">
2025 1.1 tron void XMLCALL
2026 1.1 tron XML_SetElementHandler(XML_Parser p,
2027 1.1 tron XML_StartElementHandler start,
2028 1.1 tron XML_EndElementHandler end);
2029 1.1 tron </pre>
2030 1.1.1.8.2.1 martin <p>
2031 1.1.1.8.2.1 martin Set handlers for start and end tags with one call.
2032 1.1.1.8.2.1 martin </p>
2033 1.1.1.8.2.1 martin </div>
2034 1.1.1.8.2.1 martin
2035 1.1.1.8.2.1 martin <div class="handler">
2036 1.1.1.8.2.1 martin <h4 id="XML_SetCharacterDataHandler">
2037 1.1.1.8.2.1 martin XML_SetCharacterDataHandler
2038 1.1.1.8.2.1 martin </h4>
2039 1.1 tron
2040 1.1.1.8.2.1 martin <pre class="setter">
2041 1.1 tron void XMLCALL
2042 1.1 tron XML_SetCharacterDataHandler(XML_Parser p,
2043 1.1 tron XML_CharacterDataHandler charhndl)
2044 1.1 tron </pre>
2045 1.1.1.8.2.1 martin
2046 1.1.1.8.2.1 martin <pre class="signature">
2047 1.1 tron typedef void
2048 1.1 tron (XMLCALL *XML_CharacterDataHandler)(void *userData,
2049 1.1 tron const XML_Char *s,
2050 1.1 tron int len);
2051 1.1 tron </pre>
2052 1.1.1.8.2.1 martin <p>
2053 1.1.1.8.2.1 martin Set a text handler. The string your handler receives is <em>NOT
2054 1.1.1.8.2.1 martin null-terminated</em>. You have to use the length argument to deal with the end
2055 1.1.1.8.2.1 martin of the string. A single block of contiguous text free of markup may still
2056 1.1.1.8.2.1 martin result in a sequence of calls to this handler. In other words, if you're
2057 1.1.1.8.2.1 martin searching for a pattern in the text, it may be split across calls to this
2058 1.1.1.8.2.1 martin handler. Note: Setting this handler to <code>NULL</code> may <em>NOT
2059 1.1.1.8.2.1 martin immediately</em> terminate call-backs if the parser is currently processing
2060 1.1.1.8.2.1 martin such a single block of contiguous markup-free text, as the parser will continue
2061 1.1.1.8.2.1 martin calling back until the end of the block is reached.
2062 1.1.1.8.2.1 martin </p>
2063 1.1.1.8.2.1 martin </div>
2064 1.1.1.8.2.1 martin
2065 1.1.1.8.2.1 martin <div class="handler">
2066 1.1.1.8.2.1 martin <h4 id="XML_SetProcessingInstructionHandler">
2067 1.1.1.8.2.1 martin XML_SetProcessingInstructionHandler
2068 1.1.1.8.2.1 martin </h4>
2069 1.1.1.8.2.1 martin
2070 1.1.1.8.2.1 martin <pre class="setter">
2071 1.1 tron void XMLCALL
2072 1.1 tron XML_SetProcessingInstructionHandler(XML_Parser p,
2073 1.1 tron XML_ProcessingInstructionHandler proc)
2074 1.1 tron </pre>
2075 1.1.1.8.2.1 martin
2076 1.1.1.8.2.1 martin <pre class="signature">
2077 1.1 tron typedef void
2078 1.1 tron (XMLCALL *XML_ProcessingInstructionHandler)(void *userData,
2079 1.1 tron const XML_Char *target,
2080 1.1 tron const XML_Char *data);
2081 1.1 tron
2082 1.1 tron </pre>
2083 1.1.1.8.2.1 martin <p>
2084 1.1.1.8.2.1 martin Set a handler for processing instructions. The target is the first word in the
2085 1.1.1.8.2.1 martin processing instruction. The data is the rest of the characters in it after
2086 1.1.1.8.2.1 martin skipping all whitespace after the initial word.
2087 1.1.1.8.2.1 martin </p>
2088 1.1.1.8.2.1 martin </div>
2089 1.1.1.8.2.1 martin
2090 1.1.1.8.2.1 martin <div class="handler">
2091 1.1.1.8.2.1 martin <h4 id="XML_SetCommentHandler">
2092 1.1.1.8.2.1 martin XML_SetCommentHandler
2093 1.1.1.8.2.1 martin </h4>
2094 1.1.1.8.2.1 martin
2095 1.1.1.8.2.1 martin <pre class="setter">
2096 1.1 tron void XMLCALL
2097 1.1 tron XML_SetCommentHandler(XML_Parser p,
2098 1.1 tron XML_CommentHandler cmnt)
2099 1.1 tron </pre>
2100 1.1.1.8.2.1 martin
2101 1.1.1.8.2.1 martin <pre class="signature">
2102 1.1 tron typedef void
2103 1.1 tron (XMLCALL *XML_CommentHandler)(void *userData,
2104 1.1 tron const XML_Char *data);
2105 1.1 tron </pre>
2106 1.1.1.8.2.1 martin <p>
2107 1.1.1.8.2.1 martin Set a handler for comments. The data is all text inside the comment delimiters.
2108 1.1.1.8.2.1 martin </p>
2109 1.1.1.8.2.1 martin </div>
2110 1.1.1.8.2.1 martin
2111 1.1.1.8.2.1 martin <div class="handler">
2112 1.1.1.8.2.1 martin <h4 id="XML_SetStartCdataSectionHandler">
2113 1.1.1.8.2.1 martin XML_SetStartCdataSectionHandler
2114 1.1.1.8.2.1 martin </h4>
2115 1.1.1.8.2.1 martin
2116 1.1.1.8.2.1 martin <pre class="setter">
2117 1.1 tron void XMLCALL
2118 1.1 tron XML_SetStartCdataSectionHandler(XML_Parser p,
2119 1.1 tron XML_StartCdataSectionHandler start);
2120 1.1 tron </pre>
2121 1.1.1.8.2.1 martin
2122 1.1.1.8.2.1 martin <pre class="signature">
2123 1.1 tron typedef void
2124 1.1 tron (XMLCALL *XML_StartCdataSectionHandler)(void *userData);
2125 1.1 tron </pre>
2126 1.1.1.8.2.1 martin <p>
2127 1.1.1.8.2.1 martin Set a handler that gets called at the beginning of a CDATA section.
2128 1.1.1.8.2.1 martin </p>
2129 1.1.1.8.2.1 martin </div>
2130 1.1.1.8.2.1 martin
2131 1.1.1.8.2.1 martin <div class="handler">
2132 1.1.1.8.2.1 martin <h4 id="XML_SetEndCdataSectionHandler">
2133 1.1.1.8.2.1 martin XML_SetEndCdataSectionHandler
2134 1.1.1.8.2.1 martin </h4>
2135 1.1 tron
2136 1.1.1.8.2.1 martin <pre class="setter">
2137 1.1 tron void XMLCALL
2138 1.1 tron XML_SetEndCdataSectionHandler(XML_Parser p,
2139 1.1 tron XML_EndCdataSectionHandler end);
2140 1.1 tron </pre>
2141 1.1.1.8.2.1 martin
2142 1.1.1.8.2.1 martin <pre class="signature">
2143 1.1 tron typedef void
2144 1.1 tron (XMLCALL *XML_EndCdataSectionHandler)(void *userData);
2145 1.1 tron </pre>
2146 1.1.1.8.2.1 martin <p>
2147 1.1.1.8.2.1 martin Set a handler that gets called at the end of a CDATA section.
2148 1.1.1.8.2.1 martin </p>
2149 1.1.1.8.2.1 martin </div>
2150 1.1.1.8.2.1 martin
2151 1.1.1.8.2.1 martin <div class="handler">
2152 1.1.1.8.2.1 martin <h4 id="XML_SetCdataSectionHandler">
2153 1.1.1.8.2.1 martin XML_SetCdataSectionHandler
2154 1.1.1.8.2.1 martin </h4>
2155 1.1 tron
2156 1.1.1.8.2.1 martin <pre class="setter">
2157 1.1 tron void XMLCALL
2158 1.1 tron XML_SetCdataSectionHandler(XML_Parser p,
2159 1.1 tron XML_StartCdataSectionHandler start,
2160 1.1 tron XML_EndCdataSectionHandler end)
2161 1.1 tron </pre>
2162 1.1.1.8.2.1 martin <p>
2163 1.1.1.8.2.1 martin Sets both CDATA section handlers with one call.
2164 1.1.1.8.2.1 martin </p>
2165 1.1.1.8.2.1 martin </div>
2166 1.1.1.8.2.1 martin
2167 1.1.1.8.2.1 martin <div class="handler">
2168 1.1.1.8.2.1 martin <h4 id="XML_SetDefaultHandler">
2169 1.1.1.8.2.1 martin XML_SetDefaultHandler
2170 1.1.1.8.2.1 martin </h4>
2171 1.1 tron
2172 1.1.1.8.2.1 martin <pre class="setter">
2173 1.1 tron void XMLCALL
2174 1.1 tron XML_SetDefaultHandler(XML_Parser p,
2175 1.1 tron XML_DefaultHandler hndl)
2176 1.1 tron </pre>
2177 1.1.1.8.2.1 martin
2178 1.1.1.8.2.1 martin <pre class="signature">
2179 1.1 tron typedef void
2180 1.1 tron (XMLCALL *XML_DefaultHandler)(void *userData,
2181 1.1 tron const XML_Char *s,
2182 1.1 tron int len);
2183 1.1 tron </pre>
2184 1.1.1.8.2.1 martin <p>
2185 1.1.1.8.2.1 martin Sets a handler for any characters in the document which wouldn't otherwise be
2186 1.1.1.8.2.1 martin handled. This includes both data for which no handlers can be set (like some
2187 1.1.1.8.2.1 martin kinds of DTD declarations) and data which could be reported but which currently
2188 1.1.1.8.2.1 martin has no handler set. The characters are passed exactly as they were present in
2189 1.1.1.8.2.1 martin the XML document except that they will be encoded in UTF-8 or UTF-16. Line
2190 1.1.1.8.2.1 martin boundaries are not normalized. Note that a byte order mark character is not
2191 1.1.1.8.2.1 martin passed to the default handler. There are no guarantees about how characters are
2192 1.1.1.8.2.1 martin divided between calls to the default handler: for example, a comment might be
2193 1.1.1.8.2.1 martin split between multiple calls. Setting the handler with this call has the side
2194 1.1.1.8.2.1 martin effect of turning off expansion of references to internally defined general
2195 1.1.1.8.2.1 martin entities. Instead these references are passed to the default handler.
2196 1.1.1.8.2.1 martin </p>
2197 1.1.1.8.2.1 martin
2198 1.1.1.8.2.1 martin <p>
2199 1.1.1.8.2.1 martin See also <code><a href="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.
2200 1.1.1.8.2.1 martin </p>
2201 1.1.1.8.2.1 martin </div>
2202 1.1.1.8.2.1 martin
2203 1.1.1.8.2.1 martin <div class="handler">
2204 1.1.1.8.2.1 martin <h4 id="XML_SetDefaultHandlerExpand">
2205 1.1.1.8.2.1 martin XML_SetDefaultHandlerExpand
2206 1.1.1.8.2.1 martin </h4>
2207 1.1 tron
2208 1.1.1.8.2.1 martin <pre class="setter">
2209 1.1 tron void XMLCALL
2210 1.1 tron XML_SetDefaultHandlerExpand(XML_Parser p,
2211 1.1 tron XML_DefaultHandler hndl)
2212 1.1 tron </pre>
2213 1.1.1.8.2.1 martin
2214 1.1.1.8.2.1 martin <pre class="signature">
2215 1.1 tron typedef void
2216 1.1 tron (XMLCALL *XML_DefaultHandler)(void *userData,
2217 1.1 tron const XML_Char *s,
2218 1.1 tron int len);
2219 1.1 tron </pre>
2220 1.1.1.8.2.1 martin <p>
2221 1.1.1.8.2.1 martin This sets a default handler, but doesn't inhibit the expansion of internal
2222 1.1.1.8.2.1 martin entity references. The entity reference will not be passed to the default
2223 1.1.1.8.2.1 martin handler.
2224 1.1.1.8.2.1 martin </p>
2225 1.1.1.8.2.1 martin
2226 1.1.1.8.2.1 martin <p>
2227 1.1.1.8.2.1 martin See also <code><a href="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.
2228 1.1.1.8.2.1 martin </p>
2229 1.1.1.8.2.1 martin </div>
2230 1.1.1.8.2.1 martin
2231 1.1.1.8.2.1 martin <div class="handler">
2232 1.1.1.8.2.1 martin <h4 id="XML_SetExternalEntityRefHandler">
2233 1.1.1.8.2.1 martin XML_SetExternalEntityRefHandler
2234 1.1.1.8.2.1 martin </h4>
2235 1.1.1.8.2.1 martin
2236 1.1.1.8.2.1 martin <pre class="setter">
2237 1.1 tron void XMLCALL
2238 1.1 tron XML_SetExternalEntityRefHandler(XML_Parser p,
2239 1.1 tron XML_ExternalEntityRefHandler hndl)
2240 1.1 tron </pre>
2241 1.1.1.8.2.1 martin
2242 1.1.1.8.2.1 martin <pre class="signature">
2243 1.1 tron typedef int
2244 1.1 tron (XMLCALL *XML_ExternalEntityRefHandler)(XML_Parser p,
2245 1.1 tron const XML_Char *context,
2246 1.1 tron const XML_Char *base,
2247 1.1 tron const XML_Char *systemId,
2248 1.1 tron const XML_Char *publicId);
2249 1.1 tron </pre>
2250 1.1.1.8.2.1 martin <p>
2251 1.1.1.8.2.1 martin Set an external entity reference handler. This handler is also called for
2252 1.1.1.8.2.1 martin processing an external DTD subset if parameter entity parsing is in effect.
2253 1.1.1.8.2.1 martin (See <a href=
2254 1.1.1.8.2.1 martin "#XML_SetParamEntityParsing"><code>XML_SetParamEntityParsing</code></a>.)
2255 1.1.1.8.2.1 martin </p>
2256 1.1.1.8.2.1 martin
2257 1.1.1.8.2.1 martin <p>
2258 1.1.1.8.2.1 martin <strong>Warning:</strong> Using an external entity reference handler can lead
2259 1.1.1.8.2.1 martin to <a href="https://libexpat.github.io/doc/xml-security/#external-entities">XXE
2260 1.1.1.8.2.1 martin vulnerabilities</a>. It should only be used in applications that do not parse
2261 1.1.1.8.2.1 martin untrusted XML input.
2262 1.1.1.8.2.1 martin </p>
2263 1.1.1.8.2.1 martin
2264 1.1.1.8.2.1 martin <p>
2265 1.1.1.8.2.1 martin The <code>context</code> parameter specifies the parsing context in the format
2266 1.1.1.8.2.1 martin expected by the <code>context</code> argument to <code><a href=
2267 1.1.1.8.2.1 martin "#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></code>.
2268 1.1.1.8.2.1 martin <code>code</code> is valid only until the handler returns, so if the referenced
2269 1.1.1.8.2.1 martin entity is to be parsed later, it must be copied. <code>context</code> is
2270 1.1.1.8.2.1 martin <code>NULL</code> only when the entity is a parameter entity, which is how one
2271 1.1.1.8.2.1 martin can differentiate between general and parameter entities.
2272 1.1.1.8.2.1 martin </p>
2273 1.1.1.8.2.1 martin
2274 1.1.1.8.2.1 martin <p>
2275 1.1.1.8.2.1 martin The <code>base</code> parameter is the base to use for relative system
2276 1.1.1.8.2.1 martin identifiers. It is set by <code><a href="#XML_SetBase">XML_SetBase</a></code>
2277 1.1.1.8.2.1 martin and may be <code>NULL</code>. The <code>publicId</code> parameter is the public
2278 1.1.1.8.2.1 martin id given in the entity declaration and may be <code>NULL</code>.
2279 1.1.1.8.2.1 martin <code>systemId</code> is the system identifier specified in the entity
2280 1.1.1.8.2.1 martin declaration and is never <code>NULL</code>.
2281 1.1.1.8.2.1 martin </p>
2282 1.1.1.8.2.1 martin
2283 1.1.1.8.2.1 martin <p>
2284 1.1.1.8.2.1 martin There are a couple of ways in which this handler differs from others. First,
2285 1.1.1.8.2.1 martin this handler returns a status indicator (an integer).
2286 1.1.1.8.2.1 martin <code>XML_STATUS_OK</code> should be returned for successful handling of the
2287 1.1.1.8.2.1 martin external entity reference. Returning <code>XML_STATUS_ERROR</code> indicates
2288 1.1.1.8.2.1 martin failure, and causes the calling parser to return an
2289 1.1.1.8.2.1 martin <code>XML_ERROR_EXTERNAL_ENTITY_HANDLING</code> error.
2290 1.1.1.8.2.1 martin </p>
2291 1.1.1.8.2.1 martin
2292 1.1.1.8.2.1 martin <p>
2293 1.1.1.8.2.1 martin Second, instead of having the user data as its first argument, it receives the
2294 1.1.1.8.2.1 martin parser that encountered the entity reference. This, along with the context
2295 1.1.1.8.2.1 martin parameter, may be used as arguments to a call to <code><a href=
2296 1.1.1.8.2.1 martin "#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></code>.
2297 1.1.1.8.2.1 martin Using the returned parser, the body of the external entity can be recursively
2298 1.1.1.8.2.1 martin parsed.
2299 1.1.1.8.2.1 martin </p>
2300 1.1.1.8.2.1 martin
2301 1.1.1.8.2.1 martin <p>
2302 1.1.1.8.2.1 martin Since this handler may be called recursively, it should not be saving
2303 1.1.1.8.2.1 martin information into global or static variables.
2304 1.1.1.8.2.1 martin </p>
2305 1.1.1.8.2.1 martin </div>
2306 1.1.1.8.2.1 martin
2307 1.1.1.8.2.1 martin <h4 id="XML_SetExternalEntityRefHandlerArg">
2308 1.1.1.8.2.1 martin XML_SetExternalEntityRefHandlerArg
2309 1.1.1.8.2.1 martin </h4>
2310 1.1 tron
2311 1.1.1.8.2.1 martin <pre class="fcndec">
2312 1.1 tron void XMLCALL
2313 1.1 tron XML_SetExternalEntityRefHandlerArg(XML_Parser p,
2314 1.1 tron void *arg)
2315 1.1 tron </pre>
2316 1.1.1.8.2.1 martin <div class="fcndef">
2317 1.1.1.8.2.1 martin <p>
2318 1.1.1.8.2.1 martin Set the argument passed to the ExternalEntityRefHandler. If <code>arg</code> is
2319 1.1.1.8.2.1 martin not <code>NULL</code>, it is the new value passed to the handler set using
2320 1.1.1.8.2.1 martin <code><a href=
2321 1.1.1.8.2.1 martin "#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a></code>;
2322 1.1.1.8.2.1 martin if <code>arg</code> is <code>NULL</code>, the argument passed to the handler
2323 1.1.1.8.2.1 martin function will be the parser object itself.
2324 1.1.1.8.2.1 martin </p>
2325 1.1.1.8.2.1 martin
2326 1.1.1.8.2.1 martin <p>
2327 1.1.1.8.2.1 martin <strong>Note:</strong> The type of <code>arg</code> and the type of the first
2328 1.1.1.8.2.1 martin argument to the ExternalEntityRefHandler do not match. This function takes a
2329 1.1.1.8.2.1 martin <code>void *</code> to be passed to the handler, while the handler accepts an
2330 1.1.1.8.2.1 martin <code>XML_Parser</code>. This is a historical accident, but will not be
2331 1.1.1.8.2.1 martin corrected before Expat 2.0 (at the earliest) to avoid causing compiler warnings
2332 1.1.1.8.2.1 martin for code that's known to work with this API. It is the responsibility of the
2333 1.1.1.8.2.1 martin application code to know the actual type of the argument passed to the handler
2334 1.1.1.8.2.1 martin and to manage it properly.
2335 1.1.1.8.2.1 martin </p>
2336 1.1.1.8.2.1 martin </div>
2337 1.1.1.8.2.1 martin
2338 1.1.1.8.2.1 martin <div class="handler">
2339 1.1.1.8.2.1 martin <h4 id="XML_SetSkippedEntityHandler">
2340 1.1.1.8.2.1 martin XML_SetSkippedEntityHandler
2341 1.1.1.8.2.1 martin </h4>
2342 1.1.1.8.2.1 martin
2343 1.1.1.8.2.1 martin <pre class="setter">
2344 1.1 tron void XMLCALL
2345 1.1 tron XML_SetSkippedEntityHandler(XML_Parser p,
2346 1.1 tron XML_SkippedEntityHandler handler)
2347 1.1 tron </pre>
2348 1.1.1.8.2.1 martin
2349 1.1.1.8.2.1 martin <pre class="signature">
2350 1.1 tron typedef void
2351 1.1 tron (XMLCALL *XML_SkippedEntityHandler)(void *userData,
2352 1.1 tron const XML_Char *entityName,
2353 1.1 tron int is_parameter_entity);
2354 1.1 tron </pre>
2355 1.1.1.8.2.1 martin <p>
2356 1.1.1.8.2.1 martin Set a skipped entity handler. This is called in two situations:
2357 1.1.1.8.2.1 martin </p>
2358 1.1.1.8.2.1 martin
2359 1.1.1.8.2.1 martin <ol>
2360 1.1.1.8.2.1 martin <li>An entity reference is encountered for which no declaration has been read
2361 1.1.1.8.2.1 martin <em>and</em> this is not an error.
2362 1.1.1.8.2.1 martin </li>
2363 1.1.1.8.2.1 martin
2364 1.1.1.8.2.1 martin <li>An internal entity reference is read, but not expanded, because <a href=
2365 1.1.1.8.2.1 martin "#XML_SetDefaultHandler"><code>XML_SetDefaultHandler</code></a> has been
2366 1.1.1.8.2.1 martin called.
2367 1.1.1.8.2.1 martin </li>
2368 1.1.1.8.2.1 martin </ol>
2369 1.1.1.8.2.1 martin
2370 1.1.1.8.2.1 martin <p>
2371 1.1.1.8.2.1 martin The <code>is_parameter_entity</code> argument will be non-zero for a parameter
2372 1.1.1.8.2.1 martin entity and zero for a general entity.
2373 1.1.1.8.2.1 martin </p>
2374 1.1.1.8.2.1 martin
2375 1.1.1.8.2.1 martin <p>
2376 1.1.1.8.2.1 martin Note: Skipped parameter entities in declarations and skipped general entities
2377 1.1.1.8.2.1 martin in attribute values cannot be reported, because the event would be out of sync
2378 1.1.1.8.2.1 martin with the reporting of the declarations or attribute values
2379 1.1.1.8.2.1 martin </p>
2380 1.1.1.8.2.1 martin </div>
2381 1.1.1.8.2.1 martin
2382 1.1.1.8.2.1 martin <div class="handler">
2383 1.1.1.8.2.1 martin <h4 id="XML_SetUnknownEncodingHandler">
2384 1.1.1.8.2.1 martin XML_SetUnknownEncodingHandler
2385 1.1.1.8.2.1 martin </h4>
2386 1.1.1.8.2.1 martin
2387 1.1.1.8.2.1 martin <pre class="setter">
2388 1.1 tron void XMLCALL
2389 1.1 tron XML_SetUnknownEncodingHandler(XML_Parser p,
2390 1.1 tron XML_UnknownEncodingHandler enchandler,
2391 1.1.1.8.2.1 martin void *encodingHandlerData)
2392 1.1 tron </pre>
2393 1.1.1.8.2.1 martin
2394 1.1.1.8.2.1 martin <pre class="signature">
2395 1.1 tron typedef int
2396 1.1 tron (XMLCALL *XML_UnknownEncodingHandler)(void *encodingHandlerData,
2397 1.1 tron const XML_Char *name,
2398 1.1 tron XML_Encoding *info);
2399 1.1 tron
2400 1.1 tron typedef struct {
2401 1.1 tron int map[256];
2402 1.1 tron void *data;
2403 1.1 tron int (XMLCALL *convert)(void *data, const char *s);
2404 1.1 tron void (XMLCALL *release)(void *data);
2405 1.1 tron } XML_Encoding;
2406 1.1 tron </pre>
2407 1.1.1.8.2.1 martin <p>
2408 1.1.1.8.2.1 martin Set a handler to deal with encodings other than the <a href=
2409 1.1.1.8.2.1 martin "#builtin_encodings">built in set</a>. This should be done before
2410 1.1.1.8.2.1 martin <code><a href="#XML_Parse">XML_Parse</a></code> or <code><a href=
2411 1.1.1.8.2.1 martin "#XML_ParseBuffer">XML_ParseBuffer</a></code> have been called on the given
2412 1.1.1.8.2.1 martin parser.
2413 1.1.1.8.2.1 martin </p>
2414 1.1.1.8.2.1 martin
2415 1.1.1.8.2.1 martin <p>
2416 1.1.1.8.2.1 martin If the handler knows how to deal with an encoding with the given name, it
2417 1.1.1.8.2.1 martin should fill in the <code>info</code> data structure and return
2418 1.1.1.8.2.1 martin <code>XML_STATUS_OK</code>. Otherwise it should return
2419 1.1.1.8.2.1 martin <code>XML_STATUS_ERROR</code>. The handler will be called at most once per
2420 1.1.1.8.2.1 martin parsed (external) entity. The optional application data pointer
2421 1.1.1.8.2.1 martin <code>encodingHandlerData</code> will be passed back to the handler.
2422 1.1.1.8.2.1 martin </p>
2423 1.1.1.8.2.1 martin
2424 1.1.1.8.2.1 martin <p>
2425 1.1.1.8.2.1 martin The map array contains information for every possible leading byte in a byte
2426 1.1.1.8.2.1 martin sequence. If the corresponding value is >= 0, then it's a single byte
2427 1.1.1.8.2.1 martin sequence and the byte encodes that Unicode value. If the value is -1, then that
2428 1.1.1.8.2.1 martin byte is invalid as the initial byte in a sequence. If the value is -n, where n
2429 1.1.1.8.2.1 martin is an integer > 1, then n is the number of bytes in the sequence and the
2430 1.1.1.8.2.1 martin actual conversion is accomplished by a call to the function pointed at by
2431 1.1.1.8.2.1 martin convert. This function may return -1 if the sequence itself is invalid. The
2432 1.1.1.8.2.1 martin convert pointer may be <code>NULL</code> if there are only single byte codes.
2433 1.1.1.8.2.1 martin The data parameter passed to the convert function is the data pointer from
2434 1.1.1.8.2.1 martin <code>XML_Encoding</code>. The string s is <em>NOT</em> null-terminated and
2435 1.1.1.8.2.1 martin points at the sequence of bytes to be converted.
2436 1.1.1.8.2.1 martin </p>
2437 1.1.1.8.2.1 martin
2438 1.1.1.8.2.1 martin <p>
2439 1.1.1.8.2.1 martin The function pointed at by <code>release</code> is called by the parser when it
2440 1.1.1.8.2.1 martin is finished with the encoding. It may be <code>NULL</code>.
2441 1.1.1.8.2.1 martin </p>
2442 1.1.1.8.2.1 martin </div>
2443 1.1.1.8.2.1 martin
2444 1.1.1.8.2.1 martin <div class="handler">
2445 1.1.1.8.2.1 martin <h4 id="XML_SetStartNamespaceDeclHandler">
2446 1.1.1.8.2.1 martin XML_SetStartNamespaceDeclHandler
2447 1.1.1.8.2.1 martin </h4>
2448 1.1.1.8.2.1 martin
2449 1.1.1.8.2.1 martin <pre class="setter">
2450 1.1 tron void XMLCALL
2451 1.1 tron XML_SetStartNamespaceDeclHandler(XML_Parser p,
2452 1.1.1.8.2.1 martin XML_StartNamespaceDeclHandler start);
2453 1.1 tron </pre>
2454 1.1.1.8.2.1 martin
2455 1.1.1.8.2.1 martin <pre class="signature">
2456 1.1 tron typedef void
2457 1.1 tron (XMLCALL *XML_StartNamespaceDeclHandler)(void *userData,
2458 1.1 tron const XML_Char *prefix,
2459 1.1 tron const XML_Char *uri);
2460 1.1 tron </pre>
2461 1.1.1.8.2.1 martin <p>
2462 1.1.1.8.2.1 martin Set a handler to be called when a namespace is declared. Namespace declarations
2463 1.1.1.8.2.1 martin occur inside start tags. But the namespace declaration start handler is called
2464 1.1.1.8.2.1 martin before the start tag handler for each namespace declared in that start tag.
2465 1.1.1.8.2.1 martin </p>
2466 1.1.1.8.2.1 martin </div>
2467 1.1.1.8.2.1 martin
2468 1.1.1.8.2.1 martin <div class="handler">
2469 1.1.1.8.2.1 martin <h4 id="XML_SetEndNamespaceDeclHandler">
2470 1.1.1.8.2.1 martin XML_SetEndNamespaceDeclHandler
2471 1.1.1.8.2.1 martin </h4>
2472 1.1.1.8.2.1 martin
2473 1.1.1.8.2.1 martin <pre class="setter">
2474 1.1 tron void XMLCALL
2475 1.1 tron XML_SetEndNamespaceDeclHandler(XML_Parser p,
2476 1.1.1.8.2.1 martin XML_EndNamespaceDeclHandler end);
2477 1.1 tron </pre>
2478 1.1.1.8.2.1 martin
2479 1.1.1.8.2.1 martin <pre class="signature">
2480 1.1 tron typedef void
2481 1.1 tron (XMLCALL *XML_EndNamespaceDeclHandler)(void *userData,
2482 1.1 tron const XML_Char *prefix);
2483 1.1 tron </pre>
2484 1.1.1.8.2.1 martin <p>
2485 1.1.1.8.2.1 martin Set a handler to be called when leaving the scope of a namespace declaration.
2486 1.1.1.8.2.1 martin This will be called, for each namespace declaration, after the handler for the
2487 1.1.1.8.2.1 martin end tag of the element in which the namespace was declared.
2488 1.1.1.8.2.1 martin </p>
2489 1.1.1.8.2.1 martin </div>
2490 1.1.1.8.2.1 martin
2491 1.1.1.8.2.1 martin <div class="handler">
2492 1.1.1.8.2.1 martin <h4 id="XML_SetNamespaceDeclHandler">
2493 1.1.1.8.2.1 martin XML_SetNamespaceDeclHandler
2494 1.1.1.8.2.1 martin </h4>
2495 1.1.1.8.2.1 martin
2496 1.1.1.8.2.1 martin <pre class="setter">
2497 1.1 tron void XMLCALL
2498 1.1 tron XML_SetNamespaceDeclHandler(XML_Parser p,
2499 1.1 tron XML_StartNamespaceDeclHandler start,
2500 1.1 tron XML_EndNamespaceDeclHandler end)
2501 1.1 tron </pre>
2502 1.1.1.8.2.1 martin <p>
2503 1.1.1.8.2.1 martin Sets both namespace declaration handlers with a single call.
2504 1.1.1.8.2.1 martin </p>
2505 1.1.1.8.2.1 martin </div>
2506 1.1.1.8.2.1 martin
2507 1.1.1.8.2.1 martin <div class="handler">
2508 1.1.1.8.2.1 martin <h4 id="XML_SetXmlDeclHandler">
2509 1.1.1.8.2.1 martin XML_SetXmlDeclHandler
2510 1.1.1.8.2.1 martin </h4>
2511 1.1 tron
2512 1.1.1.8.2.1 martin <pre class="setter">
2513 1.1 tron void XMLCALL
2514 1.1 tron XML_SetXmlDeclHandler(XML_Parser p,
2515 1.1.1.8.2.1 martin XML_XmlDeclHandler xmldecl);
2516 1.1 tron </pre>
2517 1.1.1.8.2.1 martin
2518 1.1.1.8.2.1 martin <pre class="signature">
2519 1.1 tron typedef void
2520 1.1 tron (XMLCALL *XML_XmlDeclHandler)(void *userData,
2521 1.1 tron const XML_Char *version,
2522 1.1 tron const XML_Char *encoding,
2523 1.1 tron int standalone);
2524 1.1 tron </pre>
2525 1.1.1.8.2.1 martin <p>
2526 1.1.1.8.2.1 martin Sets a handler that is called for XML declarations and also for text
2527 1.1.1.8.2.1 martin declarations discovered in external entities. The way to distinguish is that
2528 1.1.1.8.2.1 martin the <code>version</code> parameter will be <code>NULL</code> for text
2529 1.1.1.8.2.1 martin declarations. The <code>encoding</code> parameter may be <code>NULL</code> for
2530 1.1.1.8.2.1 martin an XML declaration. The <code>standalone</code> argument will contain -1, 0, or
2531 1.1.1.8.2.1 martin 1 indicating respectively that there was no standalone parameter in the
2532 1.1.1.8.2.1 martin declaration, that it was given as no, or that it was given as yes.
2533 1.1.1.8.2.1 martin </p>
2534 1.1.1.8.2.1 martin </div>
2535 1.1.1.8.2.1 martin
2536 1.1.1.8.2.1 martin <div class="handler">
2537 1.1.1.8.2.1 martin <h4 id="XML_SetStartDoctypeDeclHandler">
2538 1.1.1.8.2.1 martin XML_SetStartDoctypeDeclHandler
2539 1.1.1.8.2.1 martin </h4>
2540 1.1.1.8.2.1 martin
2541 1.1.1.8.2.1 martin <pre class="setter">
2542 1.1 tron void XMLCALL
2543 1.1 tron XML_SetStartDoctypeDeclHandler(XML_Parser p,
2544 1.1.1.8.2.1 martin XML_StartDoctypeDeclHandler start);
2545 1.1 tron </pre>
2546 1.1.1.8.2.1 martin
2547 1.1.1.8.2.1 martin <pre class="signature">
2548 1.1 tron typedef void
2549 1.1 tron (XMLCALL *XML_StartDoctypeDeclHandler)(void *userData,
2550 1.1 tron const XML_Char *doctypeName,
2551 1.1 tron const XML_Char *sysid,
2552 1.1 tron const XML_Char *pubid,
2553 1.1 tron int has_internal_subset);
2554 1.1 tron </pre>
2555 1.1.1.8.2.1 martin <p>
2556 1.1.1.8.2.1 martin Set a handler that is called at the start of a DOCTYPE declaration, before any
2557 1.1.1.8.2.1 martin external or internal subset is parsed. Both <code>sysid</code> and
2558 1.1.1.8.2.1 martin <code>pubid</code> may be <code>NULL</code>. The
2559 1.1.1.8.2.1 martin <code>has_internal_subset</code> will be non-zero if the DOCTYPE declaration
2560 1.1.1.8.2.1 martin has an internal subset.
2561 1.1.1.8.2.1 martin </p>
2562 1.1.1.8.2.1 martin </div>
2563 1.1.1.8.2.1 martin
2564 1.1.1.8.2.1 martin <div class="handler">
2565 1.1.1.8.2.1 martin <h4 id="XML_SetEndDoctypeDeclHandler">
2566 1.1.1.8.2.1 martin XML_SetEndDoctypeDeclHandler
2567 1.1.1.8.2.1 martin </h4>
2568 1.1.1.8.2.1 martin
2569 1.1.1.8.2.1 martin <pre class="setter">
2570 1.1 tron void XMLCALL
2571 1.1 tron XML_SetEndDoctypeDeclHandler(XML_Parser p,
2572 1.1.1.8.2.1 martin XML_EndDoctypeDeclHandler end);
2573 1.1 tron </pre>
2574 1.1.1.8.2.1 martin
2575 1.1.1.8.2.1 martin <pre class="signature">
2576 1.1 tron typedef void
2577 1.1 tron (XMLCALL *XML_EndDoctypeDeclHandler)(void *userData);
2578 1.1 tron </pre>
2579 1.1.1.8.2.1 martin <p>
2580 1.1.1.8.2.1 martin Set a handler that is called at the end of a DOCTYPE declaration, after parsing
2581 1.1.1.8.2.1 martin any external subset.
2582 1.1.1.8.2.1 martin </p>
2583 1.1.1.8.2.1 martin </div>
2584 1.1.1.8.2.1 martin
2585 1.1.1.8.2.1 martin <div class="handler">
2586 1.1.1.8.2.1 martin <h4 id="XML_SetDoctypeDeclHandler">
2587 1.1.1.8.2.1 martin XML_SetDoctypeDeclHandler
2588 1.1.1.8.2.1 martin </h4>
2589 1.1.1.8.2.1 martin
2590 1.1.1.8.2.1 martin <pre class="setter">
2591 1.1 tron void XMLCALL
2592 1.1 tron XML_SetDoctypeDeclHandler(XML_Parser p,
2593 1.1.1.8.2.1 martin XML_StartDoctypeDeclHandler start,
2594 1.1.1.8.2.1 martin XML_EndDoctypeDeclHandler end);
2595 1.1 tron </pre>
2596 1.1.1.8.2.1 martin <p>
2597 1.1.1.8.2.1 martin Set both doctype handlers with one call.
2598 1.1.1.8.2.1 martin </p>
2599 1.1.1.8.2.1 martin </div>
2600 1.1.1.8.2.1 martin
2601 1.1.1.8.2.1 martin <div class="handler">
2602 1.1.1.8.2.1 martin <h4 id="XML_SetElementDeclHandler">
2603 1.1.1.8.2.1 martin XML_SetElementDeclHandler
2604 1.1.1.8.2.1 martin </h4>
2605 1.1 tron
2606 1.1.1.8.2.1 martin <pre class="setter">
2607 1.1 tron void XMLCALL
2608 1.1 tron XML_SetElementDeclHandler(XML_Parser p,
2609 1.1.1.8.2.1 martin XML_ElementDeclHandler eldecl);
2610 1.1 tron </pre>
2611 1.1.1.8.2.1 martin
2612 1.1.1.8.2.1 martin <pre class="signature">
2613 1.1 tron typedef void
2614 1.1 tron (XMLCALL *XML_ElementDeclHandler)(void *userData,
2615 1.1 tron const XML_Char *name,
2616 1.1 tron XML_Content *model);
2617 1.1 tron </pre>
2618 1.1.1.8.2.1 martin
2619 1.1.1.8.2.1 martin <pre class="signature">
2620 1.1 tron enum XML_Content_Type {
2621 1.1 tron XML_CTYPE_EMPTY = 1,
2622 1.1 tron XML_CTYPE_ANY,
2623 1.1 tron XML_CTYPE_MIXED,
2624 1.1 tron XML_CTYPE_NAME,
2625 1.1 tron XML_CTYPE_CHOICE,
2626 1.1 tron XML_CTYPE_SEQ
2627 1.1 tron };
2628 1.1 tron
2629 1.1 tron enum XML_Content_Quant {
2630 1.1 tron XML_CQUANT_NONE,
2631 1.1 tron XML_CQUANT_OPT,
2632 1.1 tron XML_CQUANT_REP,
2633 1.1 tron XML_CQUANT_PLUS
2634 1.1 tron };
2635 1.1 tron
2636 1.1 tron typedef struct XML_cp XML_Content;
2637 1.1 tron
2638 1.1 tron struct XML_cp {
2639 1.1.1.8.2.1 martin enum XML_Content_Type type;
2640 1.1.1.8.2.1 martin enum XML_Content_Quant quant;
2641 1.1.1.8.2.1 martin const XML_Char * name;
2642 1.1.1.8.2.1 martin unsigned int numchildren;
2643 1.1.1.8.2.1 martin XML_Content * children;
2644 1.1 tron };
2645 1.1 tron </pre>
2646 1.1.1.8.2.1 martin <p>
2647 1.1.1.8.2.1 martin Sets a handler for element declarations in a DTD. The handler gets called with
2648 1.1.1.8.2.1 martin the name of the element in the declaration and a pointer to a structure that
2649 1.1.1.8.2.1 martin contains the element model. It's the user code's responsibility to free model
2650 1.1.1.8.2.1 martin when finished with via a call to <code><a href=
2651 1.1.1.8.2.1 martin "#XML_FreeContentModel">XML_FreeContentModel</a></code>. There is no need to
2652 1.1.1.8.2.1 martin free the model from the handler, it can be kept around and freed at a later
2653 1.1.1.8.2.1 martin stage.
2654 1.1.1.8.2.1 martin </p>
2655 1.1.1.8.2.1 martin
2656 1.1.1.8.2.1 martin <p>
2657 1.1.1.8.2.1 martin The <code>model</code> argument is the root of a tree of
2658 1.1.1.8.2.1 martin <code>XML_Content</code> nodes. If <code>type</code> equals
2659 1.1.1.8.2.1 martin <code>XML_CTYPE_EMPTY</code> or <code>XML_CTYPE_ANY</code>, then
2660 1.1.1.8.2.1 martin <code>quant</code> will be <code>XML_CQUANT_NONE</code>, and the other fields
2661 1.1.1.8.2.1 martin will be zero or <code>NULL</code>. If <code>type</code> is
2662 1.1.1.8.2.1 martin <code>XML_CTYPE_MIXED</code>, then <code>quant</code> will be
2663 1.1.1.8.2.1 martin <code>XML_CQUANT_NONE</code> or <code>XML_CQUANT_REP</code> and
2664 1.1.1.8.2.1 martin <code>numchildren</code> will contain the number of elements that are allowed
2665 1.1.1.8.2.1 martin to be mixed in and <code>children</code> points to an array of
2666 1.1.1.8.2.1 martin <code>XML_Content</code> structures that will all have type XML_CTYPE_NAME with
2667 1.1.1.8.2.1 martin no quantification. Only the root node can be type <code>XML_CTYPE_EMPTY</code>,
2668 1.1.1.8.2.1 martin <code>XML_CTYPE_ANY</code>, or <code>XML_CTYPE_MIXED</code>.
2669 1.1.1.8.2.1 martin </p>
2670 1.1.1.8.2.1 martin
2671 1.1.1.8.2.1 martin <p>
2672 1.1.1.8.2.1 martin For type <code>XML_CTYPE_NAME</code>, the <code>name</code> field points to the
2673 1.1.1.8.2.1 martin name and the <code>numchildren</code> and <code>children</code> fields will be
2674 1.1.1.8.2.1 martin zero and <code>NULL</code>. The <code>quant</code> field will indicate any
2675 1.1.1.8.2.1 martin quantifiers placed on the name.
2676 1.1.1.8.2.1 martin </p>
2677 1.1.1.8.2.1 martin
2678 1.1.1.8.2.1 martin <p>
2679 1.1.1.8.2.1 martin Types <code>XML_CTYPE_CHOICE</code> and <code>XML_CTYPE_SEQ</code> indicate a
2680 1.1.1.8.2.1 martin choice or sequence respectively. The <code>numchildren</code> field indicates
2681 1.1.1.8.2.1 martin how many nodes in the choice or sequence and <code>children</code> points to
2682 1.1.1.8.2.1 martin the nodes.
2683 1.1.1.8.2.1 martin </p>
2684 1.1.1.8.2.1 martin </div>
2685 1.1.1.8.2.1 martin
2686 1.1.1.8.2.1 martin <div class="handler">
2687 1.1.1.8.2.1 martin <h4 id="XML_SetAttlistDeclHandler">
2688 1.1.1.8.2.1 martin XML_SetAttlistDeclHandler
2689 1.1.1.8.2.1 martin </h4>
2690 1.1.1.8.2.1 martin
2691 1.1.1.8.2.1 martin <pre class="setter">
2692 1.1 tron void XMLCALL
2693 1.1 tron XML_SetAttlistDeclHandler(XML_Parser p,
2694 1.1 tron XML_AttlistDeclHandler attdecl);
2695 1.1 tron </pre>
2696 1.1.1.8.2.1 martin
2697 1.1.1.8.2.1 martin <pre class="signature">
2698 1.1 tron typedef void
2699 1.1 tron (XMLCALL *XML_AttlistDeclHandler)(void *userData,
2700 1.1 tron const XML_Char *elname,
2701 1.1 tron const XML_Char *attname,
2702 1.1 tron const XML_Char *att_type,
2703 1.1 tron const XML_Char *dflt,
2704 1.1 tron int isrequired);
2705 1.1 tron </pre>
2706 1.1.1.8.2.1 martin <p>
2707 1.1.1.8.2.1 martin Set a handler for attlist declarations in the DTD. This handler is called for
2708 1.1.1.8.2.1 martin <em>each</em> attribute. So a single attlist declaration with multiple
2709 1.1.1.8.2.1 martin attributes declared will generate multiple calls to this handler. The
2710 1.1.1.8.2.1 martin <code>elname</code> parameter returns the name of the element for which the
2711 1.1.1.8.2.1 martin attribute is being declared. The attribute name is in the <code>attname</code>
2712 1.1.1.8.2.1 martin parameter. The attribute type is in the <code>att_type</code> parameter. It is
2713 1.1.1.8.2.1 martin the string representing the type in the declaration with whitespace removed.
2714 1.1.1.8.2.1 martin </p>
2715 1.1.1.8.2.1 martin
2716 1.1.1.8.2.1 martin <p>
2717 1.1.1.8.2.1 martin The <code>dflt</code> parameter holds the default value. It will be
2718 1.1.1.8.2.1 martin <code>NULL</code> in the case of "#IMPLIED" or "#REQUIRED" attributes. You can
2719 1.1.1.8.2.1 martin distinguish these two cases by checking the <code>isrequired</code> parameter,
2720 1.1.1.8.2.1 martin which will be true in the case of "#REQUIRED" attributes. Attributes which are
2721 1.1.1.8.2.1 martin "#FIXED" will have also have a true <code>isrequired</code>, but they will have
2722 1.1.1.8.2.1 martin the non-<code>NULL</code> fixed value in the <code>dflt</code> parameter.
2723 1.1.1.8.2.1 martin </p>
2724 1.1.1.8.2.1 martin </div>
2725 1.1.1.8.2.1 martin
2726 1.1.1.8.2.1 martin <div class="handler">
2727 1.1.1.8.2.1 martin <h4 id="XML_SetEntityDeclHandler">
2728 1.1.1.8.2.1 martin XML_SetEntityDeclHandler
2729 1.1.1.8.2.1 martin </h4>
2730 1.1.1.8.2.1 martin
2731 1.1.1.8.2.1 martin <pre class="setter">
2732 1.1 tron void XMLCALL
2733 1.1 tron XML_SetEntityDeclHandler(XML_Parser p,
2734 1.1.1.8.2.1 martin XML_EntityDeclHandler handler);
2735 1.1 tron </pre>
2736 1.1.1.8.2.1 martin
2737 1.1.1.8.2.1 martin <pre class="signature">
2738 1.1 tron typedef void
2739 1.1 tron (XMLCALL *XML_EntityDeclHandler)(void *userData,
2740 1.1 tron const XML_Char *entityName,
2741 1.1 tron int is_parameter_entity,
2742 1.1 tron const XML_Char *value,
2743 1.1.1.8.2.1 martin int value_length,
2744 1.1 tron const XML_Char *base,
2745 1.1 tron const XML_Char *systemId,
2746 1.1 tron const XML_Char *publicId,
2747 1.1 tron const XML_Char *notationName);
2748 1.1 tron </pre>
2749 1.1.1.8.2.1 martin <p>
2750 1.1.1.8.2.1 martin Sets a handler that will be called for all entity declarations. The
2751 1.1.1.8.2.1 martin <code>is_parameter_entity</code> argument will be non-zero in the case of
2752 1.1.1.8.2.1 martin parameter entities and zero otherwise.
2753 1.1.1.8.2.1 martin </p>
2754 1.1.1.8.2.1 martin
2755 1.1.1.8.2.1 martin <p>
2756 1.1.1.8.2.1 martin For internal entities (<code><!ENTITY foo "bar"></code>),
2757 1.1.1.8.2.1 martin <code>value</code> will be non-<code>NULL</code> and <code>systemId</code>,
2758 1.1.1.8.2.1 martin <code>publicId</code>, and <code>notationName</code> will all be
2759 1.1.1.8.2.1 martin <code>NULL</code>. The value string is <em>not</em> null-terminated; the length
2760 1.1.1.8.2.1 martin is provided in the <code>value_length</code> parameter. Do not use
2761 1.1.1.8.2.1 martin <code>value_length</code> to test for internal entities, since it is legal to
2762 1.1.1.8.2.1 martin have zero-length values. Instead check for whether or not <code>value</code> is
2763 1.1.1.8.2.1 martin <code>NULL</code>.
2764 1.1.1.8.2.1 martin </p>
2765 1.1.1.8.2.1 martin
2766 1.1.1.8.2.1 martin <p>
2767 1.1.1.8.2.1 martin The <code>notationName</code> argument will have a non-<code>NULL</code> value
2768 1.1.1.8.2.1 martin only for unparsed entity declarations.
2769 1.1.1.8.2.1 martin </p>
2770 1.1.1.8.2.1 martin </div>
2771 1.1.1.8.2.1 martin
2772 1.1.1.8.2.1 martin <div class="handler">
2773 1.1.1.8.2.1 martin <h4 id="XML_SetUnparsedEntityDeclHandler">
2774 1.1.1.8.2.1 martin XML_SetUnparsedEntityDeclHandler
2775 1.1.1.8.2.1 martin </h4>
2776 1.1.1.8.2.1 martin
2777 1.1.1.8.2.1 martin <pre class="setter">
2778 1.1 tron void XMLCALL
2779 1.1 tron XML_SetUnparsedEntityDeclHandler(XML_Parser p,
2780 1.1 tron XML_UnparsedEntityDeclHandler h)
2781 1.1 tron </pre>
2782 1.1.1.8.2.1 martin
2783 1.1.1.8.2.1 martin <pre class="signature">
2784 1.1 tron typedef void
2785 1.1 tron (XMLCALL *XML_UnparsedEntityDeclHandler)(void *userData,
2786 1.1.1.8.2.1 martin const XML_Char *entityName,
2787 1.1 tron const XML_Char *base,
2788 1.1 tron const XML_Char *systemId,
2789 1.1 tron const XML_Char *publicId,
2790 1.1 tron const XML_Char *notationName);
2791 1.1 tron </pre>
2792 1.1.1.8.2.1 martin <p>
2793 1.1.1.8.2.1 martin Set a handler that receives declarations of unparsed entities. These are entity
2794 1.1.1.8.2.1 martin declarations that have a notation (NDATA) field:
2795 1.1.1.8.2.1 martin </p>
2796 1.1 tron
2797 1.1.1.8.2.1 martin <div id="eg">
2798 1.1.1.8.2.1 martin <pre>
2799 1.1 tron <!ENTITY logo SYSTEM "images/logo.gif" NDATA gif>
2800 1.1.1.8.2.1 martin </pre>
2801 1.1.1.8.2.1 martin </div>
2802 1.1.1.8.2.1 martin
2803 1.1.1.8.2.1 martin <p>
2804 1.1.1.8.2.1 martin This handler is obsolete and is provided for backwards compatibility. Use
2805 1.1.1.8.2.1 martin instead <a href="#XML_SetEntityDeclHandler">XML_SetEntityDeclHandler</a>.
2806 1.1.1.8.2.1 martin </p>
2807 1.1.1.8.2.1 martin </div>
2808 1.1.1.8.2.1 martin
2809 1.1.1.8.2.1 martin <div class="handler">
2810 1.1.1.8.2.1 martin <h4 id="XML_SetNotationDeclHandler">
2811 1.1.1.8.2.1 martin XML_SetNotationDeclHandler
2812 1.1.1.8.2.1 martin </h4>
2813 1.1.1.8.2.1 martin
2814 1.1.1.8.2.1 martin <pre class="setter">
2815 1.1 tron void XMLCALL
2816 1.1 tron XML_SetNotationDeclHandler(XML_Parser p,
2817 1.1 tron XML_NotationDeclHandler h)
2818 1.1 tron </pre>
2819 1.1.1.8.2.1 martin
2820 1.1.1.8.2.1 martin <pre class="signature">
2821 1.1 tron typedef void
2822 1.1.1.8.2.1 martin (XMLCALL *XML_NotationDeclHandler)(void *userData,
2823 1.1 tron const XML_Char *notationName,
2824 1.1 tron const XML_Char *base,
2825 1.1 tron const XML_Char *systemId,
2826 1.1 tron const XML_Char *publicId);
2827 1.1 tron </pre>
2828 1.1.1.8.2.1 martin <p>
2829 1.1.1.8.2.1 martin Set a handler that receives notation declarations.
2830 1.1.1.8.2.1 martin </p>
2831 1.1.1.8.2.1 martin </div>
2832 1.1.1.8.2.1 martin
2833 1.1.1.8.2.1 martin <div class="handler">
2834 1.1.1.8.2.1 martin <h4 id="XML_SetNotStandaloneHandler">
2835 1.1.1.8.2.1 martin XML_SetNotStandaloneHandler
2836 1.1.1.8.2.1 martin </h4>
2837 1.1 tron
2838 1.1.1.8.2.1 martin <pre class="setter">
2839 1.1 tron void XMLCALL
2840 1.1 tron XML_SetNotStandaloneHandler(XML_Parser p,
2841 1.1 tron XML_NotStandaloneHandler h)
2842 1.1 tron </pre>
2843 1.1.1.8.2.1 martin
2844 1.1.1.8.2.1 martin <pre class="signature">
2845 1.1.1.8.2.1 martin typedef int
2846 1.1 tron (XMLCALL *XML_NotStandaloneHandler)(void *userData);
2847 1.1 tron </pre>
2848 1.1.1.8.2.1 martin <p>
2849 1.1.1.8.2.1 martin Set a handler that is called if the document is not "standalone". This happens
2850 1.1.1.8.2.1 martin when there is an external subset or a reference to a parameter entity, but does
2851 1.1.1.8.2.1 martin not have standalone set to "yes" in an XML declaration. If this handler returns
2852 1.1.1.8.2.1 martin <code>XML_STATUS_ERROR</code>, then the parser will throw an
2853 1.1.1.8.2.1 martin <code>XML_ERROR_NOT_STANDALONE</code> error.
2854 1.1.1.8.2.1 martin </p>
2855 1.1.1.8.2.1 martin </div>
2856 1.1.1.8.2.1 martin
2857 1.1.1.8.2.1 martin <h3>
2858 1.1.1.8.2.1 martin <a id="position" name="position">Parse position and error reporting functions</a>
2859 1.1.1.8.2.1 martin </h3>
2860 1.1.1.8.2.1 martin
2861 1.1.1.8.2.1 martin <p>
2862 1.1.1.8.2.1 martin These are the functions you'll want to call when the parse functions return
2863 1.1.1.8.2.1 martin <code>XML_STATUS_ERROR</code> (a parse error has occurred), although the position
2864 1.1.1.8.2.1 martin reporting functions are useful outside of errors. The position reported is the
2865 1.1.1.8.2.1 martin byte position (in the original document or entity encoding) of the first of the
2866 1.1.1.8.2.1 martin sequence of characters that generated the current event (or the error that caused
2867 1.1.1.8.2.1 martin the parse functions to return <code>XML_STATUS_ERROR</code>.) The exceptions are
2868 1.1.1.8.2.1 martin callbacks triggered by declarations in the document prologue, in which case they
2869 1.1.1.8.2.1 martin exact position reported is somewhere in the relevant markup, but not necessarily
2870 1.1.1.8.2.1 martin as meaningful as for other events.
2871 1.1.1.8.2.1 martin </p>
2872 1.1.1.8.2.1 martin
2873 1.1.1.8.2.1 martin <p>
2874 1.1.1.8.2.1 martin The position reporting functions are accurate only outside of the DTD. In other
2875 1.1.1.8.2.1 martin words, they usually return bogus information when called from within a DTD
2876 1.1.1.8.2.1 martin declaration handler.
2877 1.1.1.8.2.1 martin </p>
2878 1.1.1.8.2.1 martin
2879 1.1.1.8.2.1 martin <h4 id="XML_GetErrorCode">
2880 1.1.1.8.2.1 martin XML_GetErrorCode
2881 1.1.1.8.2.1 martin </h4>
2882 1.1 tron
2883 1.1.1.8.2.1 martin <pre class="fcndec">
2884 1.1 tron enum XML_Error XMLCALL
2885 1.1 tron XML_GetErrorCode(XML_Parser p);
2886 1.1 tron </pre>
2887 1.1.1.8.2.1 martin <div class="fcndef">
2888 1.1.1.8.2.1 martin Return what type of error has occurred.
2889 1.1.1.8.2.1 martin </div>
2890 1.1.1.8.2.1 martin
2891 1.1.1.8.2.1 martin <h4 id="XML_ErrorString">
2892 1.1.1.8.2.1 martin XML_ErrorString
2893 1.1.1.8.2.1 martin </h4>
2894 1.1 tron
2895 1.1.1.8.2.1 martin <pre class="fcndec">
2896 1.1 tron const XML_LChar * XMLCALL
2897 1.1 tron XML_ErrorString(enum XML_Error code);
2898 1.1 tron </pre>
2899 1.1.1.8.2.1 martin <div class="fcndef">
2900 1.1.1.8.2.1 martin Return a string describing the error corresponding to code. The code should be
2901 1.1.1.8.2.1 martin one of the enums that can be returned from <code><a href=
2902 1.1.1.8.2.1 martin "#XML_GetErrorCode">XML_GetErrorCode</a></code>.
2903 1.1.1.8.2.1 martin </div>
2904 1.1.1.8.2.1 martin
2905 1.1.1.8.2.1 martin <h4 id="XML_GetCurrentByteIndex">
2906 1.1.1.8.2.1 martin XML_GetCurrentByteIndex
2907 1.1.1.8.2.1 martin </h4>
2908 1.1 tron
2909 1.1.1.8.2.1 martin <pre class="fcndec">
2910 1.1 tron XML_Index XMLCALL
2911 1.1 tron XML_GetCurrentByteIndex(XML_Parser p);
2912 1.1 tron </pre>
2913 1.1.1.8.2.1 martin <div class="fcndef">
2914 1.1.1.8.2.1 martin Return the byte offset of the position. This always corresponds to the values
2915 1.1.1.8.2.1 martin returned by <code><a href=
2916 1.1.1.8.2.1 martin "#XML_GetCurrentLineNumber">XML_GetCurrentLineNumber</a></code> and
2917 1.1.1.8.2.1 martin <code><a href="#XML_GetCurrentColumnNumber">XML_GetCurrentColumnNumber</a></code>.
2918 1.1.1.8.2.1 martin </div>
2919 1.1.1.8.2.1 martin
2920 1.1.1.8.2.1 martin <h4 id="XML_GetCurrentLineNumber">
2921 1.1.1.8.2.1 martin XML_GetCurrentLineNumber
2922 1.1.1.8.2.1 martin </h4>
2923 1.1 tron
2924 1.1.1.8.2.1 martin <pre class="fcndec">
2925 1.1 tron XML_Size XMLCALL
2926 1.1 tron XML_GetCurrentLineNumber(XML_Parser p);
2927 1.1 tron </pre>
2928 1.1.1.8.2.1 martin <div class="fcndef">
2929 1.1.1.8.2.1 martin Return the line number of the position. The first line is reported as
2930 1.1.1.8.2.1 martin <code>1</code>.
2931 1.1.1.8.2.1 martin </div>
2932 1.1.1.8.2.1 martin
2933 1.1.1.8.2.1 martin <h4 id="XML_GetCurrentColumnNumber">
2934 1.1.1.8.2.1 martin XML_GetCurrentColumnNumber
2935 1.1.1.8.2.1 martin </h4>
2936 1.1 tron
2937 1.1.1.8.2.1 martin <pre class="fcndec">
2938 1.1 tron XML_Size XMLCALL
2939 1.1 tron XML_GetCurrentColumnNumber(XML_Parser p);
2940 1.1 tron </pre>
2941 1.1.1.8.2.1 martin <div class="fcndef">
2942 1.1.1.8.2.1 martin Return the <em>offset</em>, from the beginning of the current line, of the
2943 1.1.1.8.2.1 martin position. The first column is reported as <code>0</code>.
2944 1.1.1.8.2.1 martin </div>
2945 1.1.1.8.2.1 martin
2946 1.1.1.8.2.1 martin <h4 id="XML_GetCurrentByteCount">
2947 1.1.1.8.2.1 martin XML_GetCurrentByteCount
2948 1.1.1.8.2.1 martin </h4>
2949 1.1 tron
2950 1.1.1.8.2.1 martin <pre class="fcndec">
2951 1.1 tron int XMLCALL
2952 1.1 tron XML_GetCurrentByteCount(XML_Parser p);
2953 1.1 tron </pre>
2954 1.1.1.8.2.1 martin <div class="fcndef">
2955 1.1.1.8.2.1 martin Return the number of bytes in the current event. Returns <code>0</code> if the
2956 1.1.1.8.2.1 martin event is inside a reference to an internal entity and for the end-tag event for
2957 1.1.1.8.2.1 martin empty element tags (the later can be used to distinguish empty-element tags from
2958 1.1.1.8.2.1 martin empty elements using separate start and end tags).
2959 1.1.1.8.2.1 martin </div>
2960 1.1.1.8.2.1 martin
2961 1.1.1.8.2.1 martin <h4 id="XML_GetInputContext">
2962 1.1.1.8.2.1 martin XML_GetInputContext
2963 1.1.1.8.2.1 martin </h4>
2964 1.1 tron
2965 1.1.1.8.2.1 martin <pre class="fcndec">
2966 1.1 tron const char * XMLCALL
2967 1.1 tron XML_GetInputContext(XML_Parser p,
2968 1.1 tron int *offset,
2969 1.1 tron int *size);
2970 1.1 tron </pre>
2971 1.1.1.8.2.1 martin <div class="fcndef">
2972 1.1.1.8.2.1 martin <p>
2973 1.1.1.8.2.1 martin Returns the parser's input buffer, sets the integer pointed at by
2974 1.1.1.8.2.1 martin <code>offset</code> to the offset within this buffer of the current parse
2975 1.1.1.8.2.1 martin position, and set the integer pointed at by <code>size</code> to the size of
2976 1.1.1.8.2.1 martin the returned buffer.
2977 1.1.1.8.2.1 martin </p>
2978 1.1.1.8.2.1 martin
2979 1.1.1.8.2.1 martin <p>
2980 1.1.1.8.2.1 martin This should only be called from within a handler during an active parse and the
2981 1.1.1.8.2.1 martin returned buffer should only be referred to from within the handler that made
2982 1.1.1.8.2.1 martin the call. This input buffer contains the untranslated bytes of the input.
2983 1.1.1.8.2.1 martin </p>
2984 1.1.1.8.2.1 martin
2985 1.1.1.8.2.1 martin <p>
2986 1.1.1.8.2.1 martin Only a limited amount of context is kept, so if the event triggering a call
2987 1.1.1.8.2.1 martin spans over a very large amount of input, the actual parse position may be
2988 1.1.1.8.2.1 martin before the beginning of the buffer.
2989 1.1.1.8.2.1 martin </p>
2990 1.1.1.8.2.1 martin
2991 1.1.1.8.2.1 martin <p>
2992 1.1.1.8.2.1 martin If <code>XML_CONTEXT_BYTES</code> is zero, this will always return
2993 1.1.1.8.2.1 martin <code>NULL</code>.
2994 1.1.1.8.2.1 martin </p>
2995 1.1.1.8.2.1 martin </div>
2996 1.1.1.8.2.1 martin
2997 1.1.1.8.2.1 martin <h3>
2998 1.1.1.8.2.1 martin <a id="attack-protection" name="attack-protection">Attack Protection</a><a id=
2999 1.1.1.8.2.1 martin "billion-laughs" name="billion-laughs"></a>
3000 1.1.1.8.2.1 martin </h3>
3001 1.1.1.8.2.1 martin
3002 1.1.1.8.2.1 martin <h4 id="XML_SetBillionLaughsAttackProtectionMaximumAmplification">
3003 1.1.1.8.2.1 martin XML_SetBillionLaughsAttackProtectionMaximumAmplification
3004 1.1.1.8.2.1 martin </h4>
3005 1.1.1.6 christos
3006 1.1.1.8.2.1 martin <pre class="fcndec">
3007 1.1.1.6 christos /* Added in Expat 2.4.0. */
3008 1.1.1.6 christos XML_Bool XMLCALL
3009 1.1.1.6 christos XML_SetBillionLaughsAttackProtectionMaximumAmplification(XML_Parser p,
3010 1.1.1.6 christos float maximumAmplificationFactor);
3011 1.1.1.6 christos </pre>
3012 1.1.1.8.2.1 martin <div class="fcndef">
3013 1.1.1.8.2.1 martin <p>
3014 1.1.1.8.2.1 martin Sets the maximum tolerated amplification factor for protection against <a href=
3015 1.1.1.8.2.1 martin "https://en.wikipedia.org/wiki/Billion_laughs_attack">billion laughs
3016 1.1.1.8.2.1 martin attacks</a> (default: <code>100.0</code>) of parser <code>p</code> to
3017 1.1.1.8.2.1 martin <code>maximumAmplificationFactor</code>, and returns <code>XML_TRUE</code> upon
3018 1.1.1.8.2.1 martin success and <code>XML_FALSE</code> upon error.
3019 1.1.1.8.2.1 martin </p>
3020 1.1.1.8.2.1 martin
3021 1.1.1.8.2.1 martin <p>
3022 1.1.1.8.2.1 martin Once the <a href=
3023 1.1.1.8.2.1 martin "#XML_SetBillionLaughsAttackProtectionActivationThreshold">threshold for
3024 1.1.1.8.2.1 martin activation</a> is reached, the amplification factor is calculated as ..
3025 1.1.1.8.2.1 martin </p>
3026 1.1.1.8.2.1 martin
3027 1.1.1.8.2.1 martin <pre>amplification := (direct + indirect) / direct</pre>
3028 1.1.1.8.2.1 martin <p>
3029 1.1.1.8.2.1 martin .. while parsing, whereas <code>direct</code> is the number of bytes read from
3030 1.1.1.8.2.1 martin the primary document in parsing and <code>indirect</code> is the number of
3031 1.1.1.8.2.1 martin bytes added by expanding entities and reading of external DTD files, combined.
3032 1.1.1.8.2.1 martin </p>
3033 1.1.1.8.2.1 martin
3034 1.1.1.8.2.1 martin <p>
3035 1.1.1.8.2.1 martin For a call to
3036 1.1.1.8.2.1 martin <code>XML_SetBillionLaughsAttackProtectionMaximumAmplification</code> to
3037 1.1.1.8.2.1 martin succeed:
3038 1.1.1.8.2.1 martin </p>
3039 1.1.1.8.2.1 martin
3040 1.1.1.8.2.1 martin <ul>
3041 1.1.1.8.2.1 martin <li>parser <code>p</code> must be a non-<code>NULL</code> root parser (without
3042 1.1.1.8.2.1 martin any parent parsers) and
3043 1.1.1.8.2.1 martin </li>
3044 1.1.1.8.2.1 martin
3045 1.1.1.8.2.1 martin <li>
3046 1.1.1.8.2.1 martin <code>maximumAmplificationFactor</code> must be non-<code>NaN</code> and
3047 1.1.1.8.2.1 martin greater than or equal to <code>1.0</code>.
3048 1.1.1.8.2.1 martin </li>
3049 1.1.1.8.2.1 martin </ul>
3050 1.1.1.8.2.1 martin
3051 1.1.1.8.2.1 martin <p>
3052 1.1.1.8.2.1 martin <strong>Note:</strong> If you ever need to increase this value for non-attack
3053 1.1.1.8.2.1 martin payload, please <a href="https://github.com/libexpat/libexpat/issues">file a
3054 1.1.1.8.2.1 martin bug report</a>.
3055 1.1.1.8.2.1 martin </p>
3056 1.1.1.8.2.1 martin
3057 1.1.1.8.2.1 martin <p>
3058 1.1.1.8.2.1 martin <strong>Note:</strong> Peak amplifications of factor 15,000 for the entire
3059 1.1.1.8.2.1 martin payload and of factor 30,000 in the middle of parsing have been observed with
3060 1.1.1.8.2.1 martin small benign files in practice. So if you do reduce the maximum allowed
3061 1.1.1.8.2.1 martin amplification, please make sure that the activation threshold is still big
3062 1.1.1.8.2.1 martin enough to not end up with undesired false positives (i.e. benign files being
3063 1.1.1.8.2.1 martin rejected).
3064 1.1.1.8.2.1 martin </p>
3065 1.1.1.8.2.1 martin </div>
3066 1.1.1.8.2.1 martin
3067 1.1.1.8.2.1 martin <h4 id="XML_SetBillionLaughsAttackProtectionActivationThreshold">
3068 1.1.1.8.2.1 martin XML_SetBillionLaughsAttackProtectionActivationThreshold
3069 1.1.1.8.2.1 martin </h4>
3070 1.1.1.6 christos
3071 1.1.1.8.2.1 martin <pre class="fcndec">
3072 1.1.1.6 christos /* Added in Expat 2.4.0. */
3073 1.1.1.6 christos XML_Bool XMLCALL
3074 1.1.1.6 christos XML_SetBillionLaughsAttackProtectionActivationThreshold(XML_Parser p,
3075 1.1.1.6 christos unsigned long long activationThresholdBytes);
3076 1.1.1.6 christos </pre>
3077 1.1.1.8.2.1 martin <div class="fcndef">
3078 1.1.1.8.2.1 martin <p>
3079 1.1.1.8.2.1 martin Sets number of output bytes (including amplification from entity expansion and
3080 1.1.1.8.2.1 martin reading DTD files) needed to activate protection against <a href=
3081 1.1.1.8.2.1 martin "https://en.wikipedia.org/wiki/Billion_laughs_attack">billion laughs
3082 1.1.1.8.2.1 martin attacks</a> (default: <code>8 MiB</code>) of parser <code>p</code> to
3083 1.1.1.8.2.1 martin <code>activationThresholdBytes</code>, and returns <code>XML_TRUE</code> upon
3084 1.1.1.8.2.1 martin success and <code>XML_FALSE</code> upon error.
3085 1.1.1.8.2.1 martin </p>
3086 1.1.1.8.2.1 martin
3087 1.1.1.8.2.1 martin <p>
3088 1.1.1.8.2.1 martin For a call to
3089 1.1.1.8.2.1 martin <code>XML_SetBillionLaughsAttackProtectionActivationThreshold</code> to
3090 1.1.1.8.2.1 martin succeed:
3091 1.1.1.8.2.1 martin </p>
3092 1.1.1.8.2.1 martin
3093 1.1.1.8.2.1 martin <ul>
3094 1.1.1.8.2.1 martin <li>parser <code>p</code> must be a non-<code>NULL</code> root parser (without
3095 1.1.1.8.2.1 martin any parent parsers).
3096 1.1.1.8.2.1 martin </li>
3097 1.1.1.8.2.1 martin </ul>
3098 1.1.1.8.2.1 martin
3099 1.1.1.8.2.1 martin <p>
3100 1.1.1.8.2.1 martin <strong>Note:</strong> If you ever need to increase this value for non-attack
3101 1.1.1.8.2.1 martin payload, please <a href="https://github.com/libexpat/libexpat/issues">file a
3102 1.1.1.8.2.1 martin bug report</a>.
3103 1.1.1.8.2.1 martin </p>
3104 1.1.1.8.2.1 martin
3105 1.1.1.8.2.1 martin <p>
3106 1.1.1.8.2.1 martin <strong>Note:</strong> Activation thresholds below 4 MiB are known to break
3107 1.1.1.8.2.1 martin support for <a href=
3108 1.1.1.8.2.1 martin "https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture">DITA</a>
3109 1.1.1.8.2.1 martin 1.3 payload and are hence not recommended.
3110 1.1.1.8.2.1 martin </p>
3111 1.1.1.8.2.1 martin </div>
3112 1.1.1.8.2.1 martin
3113 1.1.1.8.2.1 martin <h4 id="XML_SetAllocTrackerMaximumAmplification">
3114 1.1.1.8.2.1 martin XML_SetAllocTrackerMaximumAmplification
3115 1.1.1.8.2.1 martin </h4>
3116 1.1.1.8.2.1 martin
3117 1.1.1.8.2.1 martin <pre class="fcndec">
3118 1.1.1.8.2.1 martin /* Added in Expat 2.7.2. */
3119 1.1.1.8.2.1 martin XML_Bool
3120 1.1.1.8.2.1 martin XML_SetAllocTrackerMaximumAmplification(XML_Parser p,
3121 1.1.1.8.2.1 martin float maximumAmplificationFactor);
3122 1.1.1.8.2.1 martin </pre>
3123 1.1.1.8.2.1 martin <div class="fcndef">
3124 1.1.1.8.2.1 martin <p>
3125 1.1.1.8.2.1 martin Sets the maximum tolerated amplification factor between direct input and bytes
3126 1.1.1.8.2.1 martin of dynamic memory allocated (default: <code>100.0</code>) of parser
3127 1.1.1.8.2.1 martin <code>p</code> to <code>maximumAmplificationFactor</code>, and returns
3128 1.1.1.8.2.1 martin <code>XML_TRUE</code> upon success and <code>XML_FALSE</code> upon error.
3129 1.1.1.8.2.1 martin </p>
3130 1.1.1.8.2.1 martin
3131 1.1.1.8.2.1 martin <p>
3132 1.1.1.8.2.1 martin <strong>Note:</strong> There are three types of allocations that intentionally
3133 1.1.1.8.2.1 martin bypass tracking and limiting:
3134 1.1.1.8.2.1 martin </p>
3135 1.1.1.8.2.1 martin
3136 1.1.1.8.2.1 martin <ul>
3137 1.1.1.8.2.1 martin <li>application calls to functions <code><a href=
3138 1.1.1.8.2.1 martin "#XML_MemMalloc">XML_MemMalloc</a></code> and <code><a href="#XML_MemRealloc">
3139 1.1.1.8.2.1 martin XML_MemRealloc</a></code> <em>healthy</em> use of these two functions
3140 1.1.1.8.2.1 martin continues to be a responsibility of the application using Expat ,
3141 1.1.1.8.2.1 martin </li>
3142 1.1.1.8.2.1 martin
3143 1.1.1.8.2.1 martin <li>the main character buffer used by functions <code><a href="#XML_GetBuffer">
3144 1.1.1.8.2.1 martin XML_GetBuffer</a></code> and <code><a href=
3145 1.1.1.8.2.1 martin "#XML_ParseBuffer">XML_ParseBuffer</a></code> (and thus also by plain
3146 1.1.1.8.2.1 martin <code><a href="#XML_Parse">XML_Parse</a></code>), and
3147 1.1.1.8.2.1 martin </li>
3148 1.1.1.8.2.1 martin
3149 1.1.1.8.2.1 martin <li>the <a href="#XML_SetElementDeclHandler">content model memory</a> (that is
3150 1.1.1.8.2.1 martin passed to the <a href="#XML_SetElementDeclHandler">element declaration
3151 1.1.1.8.2.1 martin handler</a> and freed by a call to <code><a href=
3152 1.1.1.8.2.1 martin "#XML_FreeContentModel">XML_FreeContentModel</a></code>).
3153 1.1.1.8.2.1 martin </li>
3154 1.1.1.8.2.1 martin </ul>
3155 1.1.1.8.2.1 martin
3156 1.1.1.8.2.1 martin <p>
3157 1.1.1.8.2.1 martin Once the <a href="#XML_SetAllocTrackerActivationThreshold">threshold for
3158 1.1.1.8.2.1 martin activation</a> is reached, the amplification factor is calculated as ..
3159 1.1.1.8.2.1 martin </p>
3160 1.1.1.8.2.1 martin
3161 1.1.1.8.2.1 martin <pre>amplification := allocated / direct</pre>
3162 1.1.1.8.2.1 martin <p>
3163 1.1.1.8.2.1 martin .. while parsing, whereas <code>direct</code> is the number of bytes read from
3164 1.1.1.8.2.1 martin the primary document in parsing and <code>allocated</code> is the number of
3165 1.1.1.8.2.1 martin bytes of dynamic memory allocated in the parser hierarchy.
3166 1.1.1.8.2.1 martin </p>
3167 1.1.1.8.2.1 martin
3168 1.1.1.8.2.1 martin <p>
3169 1.1.1.8.2.1 martin For a call to <code>XML_SetAllocTrackerMaximumAmplification</code> to succeed:
3170 1.1.1.8.2.1 martin </p>
3171 1.1.1.8.2.1 martin
3172 1.1.1.8.2.1 martin <ul>
3173 1.1.1.8.2.1 martin <li>parser <code>p</code> must be a non-<code>NULL</code> root parser (without
3174 1.1.1.8.2.1 martin any parent parsers) and
3175 1.1.1.8.2.1 martin </li>
3176 1.1.1.8.2.1 martin
3177 1.1.1.8.2.1 martin <li>
3178 1.1.1.8.2.1 martin <code>maximumAmplificationFactor</code> must be non-<code>NaN</code> and
3179 1.1.1.8.2.1 martin greater than or equal to <code>1.0</code>.
3180 1.1.1.8.2.1 martin </li>
3181 1.1.1.8.2.1 martin </ul>
3182 1.1.1.8.2.1 martin
3183 1.1.1.8.2.1 martin <p>
3184 1.1.1.8.2.1 martin <strong>Note:</strong> If you ever need to increase this value for non-attack
3185 1.1.1.8.2.1 martin payload, please <a href="https://github.com/libexpat/libexpat/issues">file a
3186 1.1.1.8.2.1 martin bug report</a>.
3187 1.1.1.8.2.1 martin </p>
3188 1.1.1.8.2.1 martin
3189 1.1.1.8.2.1 martin <p>
3190 1.1.1.8.2.1 martin <strong>Note:</strong> Amplifications factors greater than <code>100.0</code>
3191 1.1.1.8.2.1 martin can been observed near the start of parsing even with benign files in practice.
3192 1.1.1.8.2.1 martin So if you do reduce the maximum allowed amplification, please make sure that
3193 1.1.1.8.2.1 martin the activation threshold is still big enough to not end up with undesired false
3194 1.1.1.8.2.1 martin positives (i.e. benign files being rejected).
3195 1.1.1.8.2.1 martin </p>
3196 1.1.1.8.2.1 martin </div>
3197 1.1.1.8.2.1 martin
3198 1.1.1.8.2.1 martin <h4 id="XML_SetAllocTrackerActivationThreshold">
3199 1.1.1.8.2.1 martin XML_SetAllocTrackerActivationThreshold
3200 1.1.1.8.2.1 martin </h4>
3201 1.1.1.8.2.1 martin
3202 1.1.1.8.2.1 martin <pre class="fcndec">
3203 1.1.1.8.2.1 martin /* Added in Expat 2.7.2. */
3204 1.1.1.8.2.1 martin XML_Bool
3205 1.1.1.8.2.1 martin XML_SetAllocTrackerActivationThreshold(XML_Parser p,
3206 1.1.1.8.2.1 martin unsigned long long activationThresholdBytes);
3207 1.1.1.8.2.1 martin </pre>
3208 1.1.1.8.2.1 martin <div class="fcndef">
3209 1.1.1.8.2.1 martin <p>
3210 1.1.1.8.2.1 martin Sets number of allocated bytes of dynamic memory needed to activate protection
3211 1.1.1.8.2.1 martin against disproportionate use of RAM (default: <code>64 MiB</code>) of parser
3212 1.1.1.8.2.1 martin <code>p</code> to <code>activationThresholdBytes</code>, and returns
3213 1.1.1.8.2.1 martin <code>XML_TRUE</code> upon success and <code>XML_FALSE</code> upon error.
3214 1.1.1.8.2.1 martin </p>
3215 1.1.1.8.2.1 martin
3216 1.1.1.8.2.1 martin <p>
3217 1.1.1.8.2.1 martin <strong>Note:</strong> For types of allocations that intentionally bypass
3218 1.1.1.8.2.1 martin tracking and limiting, please see <code><a href=
3219 1.1.1.8.2.1 martin "#XML_SetAllocTrackerMaximumAmplification">XML_SetAllocTrackerMaximumAmplification</a></code>
3220 1.1.1.8.2.1 martin above.
3221 1.1.1.8.2.1 martin </p>
3222 1.1.1.8.2.1 martin
3223 1.1.1.8.2.1 martin <p>
3224 1.1.1.8.2.1 martin For a call to <code>XML_SetAllocTrackerActivationThreshold</code> to succeed:
3225 1.1.1.8.2.1 martin </p>
3226 1.1.1.8.2.1 martin
3227 1.1.1.8.2.1 martin <ul>
3228 1.1.1.8.2.1 martin <li>parser <code>p</code> must be a non-<code>NULL</code> root parser (without
3229 1.1.1.8.2.1 martin any parent parsers).
3230 1.1.1.8.2.1 martin </li>
3231 1.1.1.8.2.1 martin </ul>
3232 1.1.1.8.2.1 martin
3233 1.1.1.8.2.1 martin <p>
3234 1.1.1.8.2.1 martin <strong>Note:</strong> If you ever need to increase this value for non-attack
3235 1.1.1.8.2.1 martin payload, please <a href="https://github.com/libexpat/libexpat/issues">file a
3236 1.1.1.8.2.1 martin bug report</a>.
3237 1.1.1.8.2.1 martin </p>
3238 1.1.1.8.2.1 martin </div>
3239 1.1.1.8.2.1 martin
3240 1.1.1.8.2.1 martin <h4 id="XML_SetReparseDeferralEnabled">
3241 1.1.1.8.2.1 martin XML_SetReparseDeferralEnabled
3242 1.1.1.8.2.1 martin </h4>
3243 1.1.1.6 christos
3244 1.1.1.8.2.1 martin <pre class="fcndec">
3245 1.1.1.7 wiz /* Added in Expat 2.6.0. */
3246 1.1.1.7 wiz XML_Bool XMLCALL
3247 1.1.1.7 wiz XML_SetReparseDeferralEnabled(XML_Parser parser, XML_Bool enabled);
3248 1.1.1.7 wiz </pre>
3249 1.1.1.8.2.1 martin <div class="fcndef">
3250 1.1.1.8.2.1 martin <p>
3251 1.1.1.8.2.1 martin Large tokens may require many parse calls before enough data is available for
3252 1.1.1.8.2.1 martin Expat to parse it in full. If Expat retried parsing the token on every parse
3253 1.1.1.8.2.1 martin call, parsing could take quadratic time. To avoid this, Expat only retries once
3254 1.1.1.8.2.1 martin a significant amount of new data is available. This function allows disabling
3255 1.1.1.8.2.1 martin this behavior.
3256 1.1.1.8.2.1 martin </p>
3257 1.1.1.8.2.1 martin
3258 1.1.1.8.2.1 martin <p>
3259 1.1.1.8.2.1 martin The <code>enabled</code> argument should be <code>XML_TRUE</code> or
3260 1.1.1.8.2.1 martin <code>XML_FALSE</code>.
3261 1.1.1.8.2.1 martin </p>
3262 1.1.1.8.2.1 martin
3263 1.1.1.8.2.1 martin <p>
3264 1.1.1.8.2.1 martin Returns <code>XML_TRUE</code> on success, and <code>XML_FALSE</code> on error.
3265 1.1.1.8.2.1 martin </p>
3266 1.1.1.8.2.1 martin </div>
3267 1.1.1.8.2.1 martin
3268 1.1.1.8.2.1 martin <h3>
3269 1.1.1.8.2.1 martin <a id="miscellaneous" name="miscellaneous">Miscellaneous functions</a>
3270 1.1.1.8.2.1 martin </h3>
3271 1.1.1.8.2.1 martin
3272 1.1.1.8.2.1 martin <p>
3273 1.1.1.8.2.1 martin The functions in this section either obtain state information from the parser or
3274 1.1.1.8.2.1 martin can be used to dynamically set parser options.
3275 1.1.1.8.2.1 martin </p>
3276 1.1.1.8.2.1 martin
3277 1.1.1.8.2.1 martin <h4 id="XML_SetUserData">
3278 1.1.1.8.2.1 martin XML_SetUserData
3279 1.1.1.8.2.1 martin </h4>
3280 1.1.1.7 wiz
3281 1.1.1.8.2.1 martin <pre class="fcndec">
3282 1.1 tron void XMLCALL
3283 1.1 tron XML_SetUserData(XML_Parser p,
3284 1.1 tron void *userData);
3285 1.1 tron </pre>
3286 1.1.1.8.2.1 martin <div class="fcndef">
3287 1.1.1.8.2.1 martin This sets the user data pointer that gets passed to handlers. It overwrites any
3288 1.1.1.8.2.1 martin previous value for this pointer. Note that the application is responsible for
3289 1.1.1.8.2.1 martin freeing the memory associated with <code>userData</code> when it is finished with
3290 1.1.1.8.2.1 martin the parser. So if you call this when there's already a pointer there, and you
3291 1.1.1.8.2.1 martin haven't freed the memory associated with it, then you've probably just leaked
3292 1.1.1.8.2.1 martin memory.
3293 1.1.1.8.2.1 martin </div>
3294 1.1.1.8.2.1 martin
3295 1.1.1.8.2.1 martin <h4 id="XML_GetUserData">
3296 1.1.1.8.2.1 martin XML_GetUserData
3297 1.1.1.8.2.1 martin </h4>
3298 1.1 tron
3299 1.1.1.8.2.1 martin <pre class="fcndec">
3300 1.1 tron void * XMLCALL
3301 1.1 tron XML_GetUserData(XML_Parser p);
3302 1.1 tron </pre>
3303 1.1.1.8.2.1 martin <div class="fcndef">
3304 1.1.1.8.2.1 martin This returns the user data pointer that gets passed to handlers. It is actually
3305 1.1.1.8.2.1 martin implemented as a macro.
3306 1.1.1.8.2.1 martin </div>
3307 1.1.1.8.2.1 martin
3308 1.1.1.8.2.1 martin <h4 id="XML_UseParserAsHandlerArg">
3309 1.1.1.8.2.1 martin XML_UseParserAsHandlerArg
3310 1.1.1.8.2.1 martin </h4>
3311 1.1 tron
3312 1.1.1.8.2.1 martin <pre class="fcndec">
3313 1.1 tron void XMLCALL
3314 1.1 tron XML_UseParserAsHandlerArg(XML_Parser p);
3315 1.1 tron </pre>
3316 1.1.1.8.2.1 martin <div class="fcndef">
3317 1.1.1.8.2.1 martin After this is called, handlers receive the parser in their <code>userData</code>
3318 1.1.1.8.2.1 martin arguments. The user data can still be obtained using the <code><a href=
3319 1.1.1.8.2.1 martin "#XML_GetUserData">XML_GetUserData</a></code> function.
3320 1.1.1.8.2.1 martin </div>
3321 1.1.1.8.2.1 martin
3322 1.1.1.8.2.1 martin <h4 id="XML_SetBase">
3323 1.1.1.8.2.1 martin XML_SetBase
3324 1.1.1.8.2.1 martin </h4>
3325 1.1 tron
3326 1.1.1.8.2.1 martin <pre class="fcndec">
3327 1.1 tron enum XML_Status XMLCALL
3328 1.1 tron XML_SetBase(XML_Parser p,
3329 1.1 tron const XML_Char *base);
3330 1.1 tron </pre>
3331 1.1.1.8.2.1 martin <div class="fcndef">
3332 1.1.1.8.2.1 martin Set the base to be used for resolving relative URIs in system identifiers. The
3333 1.1.1.8.2.1 martin return value is <code>XML_STATUS_ERROR</code> if there's no memory to store base,
3334 1.1.1.8.2.1 martin otherwise it's <code>XML_STATUS_OK</code>.
3335 1.1.1.8.2.1 martin </div>
3336 1.1.1.8.2.1 martin
3337 1.1.1.8.2.1 martin <h4 id="XML_GetBase">
3338 1.1.1.8.2.1 martin XML_GetBase
3339 1.1.1.8.2.1 martin </h4>
3340 1.1 tron
3341 1.1.1.8.2.1 martin <pre class="fcndec">
3342 1.1 tron const XML_Char * XMLCALL
3343 1.1 tron XML_GetBase(XML_Parser p);
3344 1.1 tron </pre>
3345 1.1.1.8.2.1 martin <div class="fcndef">
3346 1.1.1.8.2.1 martin Return the base for resolving relative URIs.
3347 1.1.1.8.2.1 martin </div>
3348 1.1.1.8.2.1 martin
3349 1.1.1.8.2.1 martin <h4 id="XML_GetSpecifiedAttributeCount">
3350 1.1.1.8.2.1 martin XML_GetSpecifiedAttributeCount
3351 1.1.1.8.2.1 martin </h4>
3352 1.1 tron
3353 1.1.1.8.2.1 martin <pre class="fcndec">
3354 1.1 tron int XMLCALL
3355 1.1 tron XML_GetSpecifiedAttributeCount(XML_Parser p);
3356 1.1 tron </pre>
3357 1.1.1.8.2.1 martin <div class="fcndef">
3358 1.1.1.8.2.1 martin When attributes are reported to the start handler in the atts vector, attributes
3359 1.1.1.8.2.1 martin that were explicitly set in the element occur before any attributes that receive
3360 1.1.1.8.2.1 martin their value from default information in an ATTLIST declaration. This function
3361 1.1.1.8.2.1 martin returns the number of attributes that were explicitly set times two, thus giving
3362 1.1.1.8.2.1 martin the offset in the <code>atts</code> array passed to the start tag handler of the
3363 1.1.1.8.2.1 martin first attribute set due to defaults. It supplies information for the last call to
3364 1.1.1.8.2.1 martin a start handler. If called inside a start handler, then that means the current
3365 1.1.1.8.2.1 martin call.
3366 1.1.1.8.2.1 martin </div>
3367 1.1.1.8.2.1 martin
3368 1.1.1.8.2.1 martin <h4 id="XML_GetIdAttributeIndex">
3369 1.1.1.8.2.1 martin XML_GetIdAttributeIndex
3370 1.1.1.8.2.1 martin </h4>
3371 1.1 tron
3372 1.1.1.8.2.1 martin <pre class="fcndec">
3373 1.1 tron int XMLCALL
3374 1.1 tron XML_GetIdAttributeIndex(XML_Parser p);
3375 1.1 tron </pre>
3376 1.1.1.8.2.1 martin <div class="fcndef">
3377 1.1.1.8.2.1 martin Returns the index of the ID attribute passed in the atts array in the last call
3378 1.1.1.8.2.1 martin to <code><a href="#XML_StartElementHandler">XML_StartElementHandler</a></code>,
3379 1.1.1.8.2.1 martin or -1 if there is no ID attribute. If called inside a start handler, then that
3380 1.1.1.8.2.1 martin means the current call.
3381 1.1.1.8.2.1 martin </div>
3382 1.1.1.8.2.1 martin
3383 1.1.1.8.2.1 martin <h4 id="XML_GetAttributeInfo">
3384 1.1.1.8.2.1 martin XML_GetAttributeInfo
3385 1.1.1.8.2.1 martin </h4>
3386 1.1 tron
3387 1.1.1.8.2.1 martin <pre class="fcndec">
3388 1.1.1.2 spz const XML_AttrInfo * XMLCALL
3389 1.1.1.2 spz XML_GetAttributeInfo(XML_Parser parser);
3390 1.1.1.2 spz </pre>
3391 1.1.1.8.2.1 martin
3392 1.1.1.8.2.1 martin <pre class="signature">
3393 1.1.1.2 spz typedef struct {
3394 1.1.1.2 spz XML_Index nameStart; /* Offset to beginning of the attribute name. */
3395 1.1.1.2 spz XML_Index nameEnd; /* Offset after the attribute name's last byte. */
3396 1.1.1.2 spz XML_Index valueStart; /* Offset to beginning of the attribute value. */
3397 1.1.1.2 spz XML_Index valueEnd; /* Offset after the attribute value's last byte. */
3398 1.1.1.2 spz } XML_AttrInfo;
3399 1.1.1.2 spz </pre>
3400 1.1.1.8.2.1 martin <div class="fcndef">
3401 1.1.1.8.2.1 martin Returns an array of <code>XML_AttrInfo</code> structures for the attribute/value
3402 1.1.1.8.2.1 martin pairs passed in the last call to the <code>XML_StartElementHandler</code> that
3403 1.1.1.8.2.1 martin were specified in the start-tag rather than defaulted. Each attribute/value pair
3404 1.1.1.8.2.1 martin counts as 1; thus the number of entries in the array is
3405 1.1.1.8.2.1 martin <code>XML_GetSpecifiedAttributeCount(parser) / 2</code>.
3406 1.1.1.8.2.1 martin </div>
3407 1.1.1.8.2.1 martin
3408 1.1.1.8.2.1 martin <h4 id="XML_SetEncoding">
3409 1.1.1.8.2.1 martin XML_SetEncoding
3410 1.1.1.8.2.1 martin </h4>
3411 1.1.1.2 spz
3412 1.1.1.8.2.1 martin <pre class="fcndec">
3413 1.1 tron enum XML_Status XMLCALL
3414 1.1 tron XML_SetEncoding(XML_Parser p,
3415 1.1 tron const XML_Char *encoding);
3416 1.1 tron </pre>
3417 1.1.1.8.2.1 martin <div class="fcndef">
3418 1.1.1.8.2.1 martin Set the encoding to be used by the parser. It is equivalent to passing a
3419 1.1.1.8.2.1 martin non-<code>NULL</code> encoding argument to the parser creation functions. It must
3420 1.1.1.8.2.1 martin not be called after <code><a href="#XML_Parse">XML_Parse</a></code> or
3421 1.1.1.8.2.1 martin <code><a href="#XML_ParseBuffer">XML_ParseBuffer</a></code> have been called on
3422 1.1.1.8.2.1 martin the given parser. Returns <code>XML_STATUS_OK</code> on success or
3423 1.1.1.8.2.1 martin <code>XML_STATUS_ERROR</code> on error.
3424 1.1.1.8.2.1 martin </div>
3425 1.1.1.8.2.1 martin
3426 1.1.1.8.2.1 martin <h4 id="XML_SetParamEntityParsing">
3427 1.1.1.8.2.1 martin XML_SetParamEntityParsing
3428 1.1.1.8.2.1 martin </h4>
3429 1.1 tron
3430 1.1.1.8.2.1 martin <pre class="fcndec">
3431 1.1 tron int XMLCALL
3432 1.1 tron XML_SetParamEntityParsing(XML_Parser p,
3433 1.1 tron enum XML_ParamEntityParsing code);
3434 1.1 tron </pre>
3435 1.1.1.8.2.1 martin <div class="fcndef">
3436 1.1.1.8.2.1 martin This enables parsing of parameter entities, including the external parameter
3437 1.1.1.8.2.1 martin entity that is the external DTD subset, according to <code>code</code>. The
3438 1.1.1.8.2.1 martin choices for <code>code</code> are:
3439 1.1.1.8.2.1 martin <ul>
3440 1.1.1.8.2.1 martin <li>
3441 1.1.1.8.2.1 martin <code>XML_PARAM_ENTITY_PARSING_NEVER</code>
3442 1.1.1.8.2.1 martin </li>
3443 1.1.1.8.2.1 martin
3444 1.1.1.8.2.1 martin <li>
3445 1.1.1.8.2.1 martin <code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code>
3446 1.1.1.8.2.1 martin </li>
3447 1.1.1.8.2.1 martin
3448 1.1.1.8.2.1 martin <li>
3449 1.1.1.8.2.1 martin <code>XML_PARAM_ENTITY_PARSING_ALWAYS</code>
3450 1.1.1.8.2.1 martin </li>
3451 1.1.1.8.2.1 martin </ul>
3452 1.1.1.8.2.1 martin <b>Note:</b> If <code>XML_SetParamEntityParsing</code> is called after
3453 1.1.1.8.2.1 martin <code>XML_Parse</code> or <code>XML_ParseBuffer</code>, then it has no effect and
3454 1.1.1.8.2.1 martin will always return 0.
3455 1.1.1.8.2.1 martin </div>
3456 1.1.1.8.2.1 martin
3457 1.1.1.8.2.1 martin <h4 id="XML_SetHashSalt">
3458 1.1.1.8.2.1 martin XML_SetHashSalt (deprecated)
3459 1.1.1.8.2.1 martin </h4>
3460 1.1.1.2 spz
3461 1.1.1.8.2.1 martin <pre class="fcndec">
3462 1.1.1.2 spz int XMLCALL
3463 1.1.1.8.2.1 martin XML_SetHashSalt(XML_Parser parser,
3464 1.1.1.2 spz unsigned long hash_salt);
3465 1.1.1.2 spz </pre>
3466 1.1.1.8.2.1 martin <div class="fcndef">
3467 1.1.1.8.2.1 martin Sets the hash salt to use for internal hash calculations. Helps in preventing DoS
3468 1.1.1.8.2.1 martin attacks based on predicting hash function behavior. In order to have an effect
3469 1.1.1.8.2.1 martin this must be called before parsing has started. Returns 1 if successful, 0 when
3470 1.1.1.8.2.1 martin called after <code>XML_Parse</code> or <code>XML_ParseBuffer</code> or when
3471 1.1.1.8.2.1 martin <code>parser</code> is <code>NULL</code>.
3472 1.1.1.8.2.1 martin <p>
3473 1.1.1.8.2.1 martin <b>Note:</b> Function <code>XML_SetHashSalt</code> is
3474 1.1.1.8.2.1 martin <strong>deprecated</strong>. Please use function <code><a href=
3475 1.1.1.8.2.1 martin "#XML_SetHashSalt16Bytes">XML_SetHashSalt16Bytes</a></code> instead for better
3476 1.1.1.8.2.1 martin security. <code>XML_SetHashSalt</code> only provides 4 to 8 bytes of entropy
3477 1.1.1.8.2.1 martin (depending on the size of type <code>unsigned long</code>) while the SipHash
3478 1.1.1.8.2.1 martin implementation used by Expat can leverage up to 16 bytes of entropy at least
3479 1.1.1.8.2.1 martin twice as much. Function <code><a href=
3480 1.1.1.8.2.1 martin "#XML_SetHashSalt16Bytes">XML_SetHashSalt16Bytes</a></code> of Expat >=2.8.0
3481 1.1.1.8.2.1 martin (and where backported) matches the amount of entropy supported by SipHash.
3482 1.1.1.8.2.1 martin </p>
3483 1.1.1.8.2.1 martin
3484 1.1.1.8.2.1 martin <p>
3485 1.1.1.8.2.1 martin <b>Note:</b> This call is optional, as the parser will auto-generate a new
3486 1.1.1.8.2.1 martin random salt value internally if no value has been set by the start of parsing.
3487 1.1.1.8.2.1 martin </p>
3488 1.1.1.8.2.1 martin
3489 1.1.1.8.2.1 martin <p>
3490 1.1.1.8.2.1 martin <b>Note:</b> One should not call <code>XML_SetHashSalt</code> with a hash salt
3491 1.1.1.8.2.1 martin value of 0, as this value is used as sentinel value to indicate that
3492 1.1.1.8.2.1 martin <code>XML_SetHashSalt</code> has <b>not</b> been called. Consequently such a
3493 1.1.1.8.2.1 martin call will have no effect, even if it returns 1.
3494 1.1.1.8.2.1 martin </p>
3495 1.1.1.8.2.1 martin </div>
3496 1.1.1.8.2.1 martin
3497 1.1.1.8.2.1 martin <h4 id="XML_SetHashSalt16Bytes">
3498 1.1.1.8.2.1 martin XML_SetHashSalt16Bytes
3499 1.1.1.8.2.1 martin </h4>
3500 1.1 tron
3501 1.1.1.8.2.1 martin <pre class="fcndec">
3502 1.1.1.8.2.1 martin /* Added in Expat 2.8.0. */
3503 1.1.1.8.2.1 martin XML_Bool XMLCALL
3504 1.1.1.8.2.1 martin XML_SetHashSalt16Bytes(XML_Parser parser,
3505 1.1.1.8.2.1 martin const uint8_t entropy[16]);
3506 1.1.1.8.2.1 martin </pre>
3507 1.1.1.8.2.1 martin <div class="fcndef">
3508 1.1.1.8.2.1 martin Sets the hash salt to use for internal hash calculations. Helps in preventing DoS
3509 1.1.1.8.2.1 martin attacks based on predicting hash function behavior. In order to have an effect
3510 1.1.1.8.2.1 martin this must be called before parsing has started. Returns <code>XML_TRUE</code> if
3511 1.1.1.8.2.1 martin successful, <code>XML_FALSE</code> when called after <code>XML_Parse</code> or
3512 1.1.1.8.2.1 martin <code>XML_ParseBuffer</code> or when <code>parser</code> is <code>NULL</code>.
3513 1.1.1.8.2.1 martin <p>
3514 1.1.1.8.2.1 martin <b>Note:</b> Setting a salt that is <em>not</em> from a source of high quality
3515 1.1.1.8.2.1 martin entropy (like <code>getentropy(3)</code>) will make the parser vulnerable to
3516 1.1.1.8.2.1 martin hash flooding attacks.
3517 1.1.1.8.2.1 martin </p>
3518 1.1.1.8.2.1 martin
3519 1.1.1.8.2.1 martin <p>
3520 1.1.1.8.2.1 martin <b>Note:</b> This call is optional, as the parser will auto-generate a new
3521 1.1.1.8.2.1 martin random salt value internally if no value has been set by the start of parsing.
3522 1.1.1.8.2.1 martin </p>
3523 1.1.1.8.2.1 martin </div>
3524 1.1.1.8.2.1 martin
3525 1.1.1.8.2.1 martin <h4 id="XML_UseForeignDTD">
3526 1.1.1.8.2.1 martin XML_UseForeignDTD
3527 1.1.1.8.2.1 martin </h4>
3528 1.1.1.8.2.1 martin
3529 1.1.1.8.2.1 martin <pre class="fcndec">
3530 1.1 tron enum XML_Error XMLCALL
3531 1.1 tron XML_UseForeignDTD(XML_Parser parser, XML_Bool useDTD);
3532 1.1 tron </pre>
3533 1.1.1.8.2.1 martin <div class="fcndef">
3534 1.1.1.8.2.1 martin <p>
3535 1.1.1.8.2.1 martin This function allows an application to provide an external subset for the
3536 1.1.1.8.2.1 martin document type declaration for documents which do not specify an external subset
3537 1.1.1.8.2.1 martin of their own. For documents which specify an external subset in their DOCTYPE
3538 1.1.1.8.2.1 martin declaration, the application-provided subset will be ignored. If the document
3539 1.1.1.8.2.1 martin does not contain a DOCTYPE declaration at all and <code>useDTD</code> is true,
3540 1.1.1.8.2.1 martin the application-provided subset will be parsed, but the
3541 1.1.1.8.2.1 martin <code>startDoctypeDeclHandler</code> and <code>endDoctypeDeclHandler</code>
3542 1.1.1.8.2.1 martin functions, if set, will not be called. The setting of parameter entity parsing,
3543 1.1.1.8.2.1 martin controlled using <code><a href=
3544 1.1.1.8.2.1 martin "#XML_SetParamEntityParsing">XML_SetParamEntityParsing</a></code>, will be
3545 1.1.1.8.2.1 martin honored.
3546 1.1.1.8.2.1 martin </p>
3547 1.1.1.8.2.1 martin
3548 1.1.1.8.2.1 martin <p>
3549 1.1.1.8.2.1 martin The application-provided external subset is read by calling the external entity
3550 1.1.1.8.2.1 martin reference handler set via <code><a href=
3551 1.1.1.8.2.1 martin "#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a></code>
3552 1.1.1.8.2.1 martin with both <code>publicId</code> and <code>systemId</code> set to
3553 1.1.1.8.2.1 martin <code>NULL</code>.
3554 1.1.1.8.2.1 martin </p>
3555 1.1.1.8.2.1 martin
3556 1.1.1.8.2.1 martin <p>
3557 1.1.1.8.2.1 martin If this function is called after parsing has begun, it returns
3558 1.1.1.8.2.1 martin <code>XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING</code> and ignores
3559 1.1.1.8.2.1 martin <code>useDTD</code>. If called when Expat has been compiled without DTD
3560 1.1.1.8.2.1 martin support, it returns <code>XML_ERROR_FEATURE_REQUIRES_XML_DTD</code>. Otherwise,
3561 1.1.1.8.2.1 martin it returns <code>XML_ERROR_NONE</code>.
3562 1.1.1.8.2.1 martin </p>
3563 1.1.1.8.2.1 martin
3564 1.1.1.8.2.1 martin <p>
3565 1.1.1.8.2.1 martin <b>Note:</b> For the purpose of checking WFC: Entity Declared, passing
3566 1.1.1.8.2.1 martin <code>useDTD == XML_TRUE</code> will make the parser behave as if the document
3567 1.1.1.8.2.1 martin had a DTD with an external subset. This holds true even if the external entity
3568 1.1.1.8.2.1 martin reference handler returns without action.
3569 1.1.1.8.2.1 martin </p>
3570 1.1.1.8.2.1 martin </div>
3571 1.1.1.8.2.1 martin
3572 1.1.1.8.2.1 martin <h4 id="XML_SetReturnNSTriplet">
3573 1.1.1.8.2.1 martin XML_SetReturnNSTriplet
3574 1.1.1.8.2.1 martin </h4>
3575 1.1 tron
3576 1.1.1.8.2.1 martin <pre class="fcndec">
3577 1.1 tron void XMLCALL
3578 1.1 tron XML_SetReturnNSTriplet(XML_Parser parser,
3579 1.1 tron int do_nst);
3580 1.1 tron </pre>
3581 1.1.1.8.2.1 martin <div class="fcndef">
3582 1.1.1.8.2.1 martin <p>
3583 1.1.1.8.2.1 martin This function only has an effect when using a parser created with
3584 1.1.1.8.2.1 martin <code><a href="#XML_ParserCreateNS">XML_ParserCreateNS</a></code>, i.e. when
3585 1.1.1.8.2.1 martin namespace processing is in effect. The <code>do_nst</code> sets whether or not
3586 1.1.1.8.2.1 martin prefixes are returned with names qualified with a namespace prefix. If this
3587 1.1.1.8.2.1 martin function is called with <code>do_nst</code> non-zero, then afterwards namespace
3588 1.1.1.8.2.1 martin qualified names (that is qualified with a prefix as opposed to belonging to a
3589 1.1.1.8.2.1 martin default namespace) are returned as a triplet with the three parts separated by
3590 1.1.1.8.2.1 martin the namespace separator specified when the parser was created. The order of
3591 1.1.1.8.2.1 martin returned parts is URI, local name, and prefix.
3592 1.1.1.8.2.1 martin </p>
3593 1.1.1.8.2.1 martin
3594 1.1.1.8.2.1 martin <p>
3595 1.1.1.8.2.1 martin If <code>do_nst</code> is zero, then namespaces are reported in the default
3596 1.1.1.8.2.1 martin manner, URI then local_name separated by the namespace separator.
3597 1.1.1.8.2.1 martin </p>
3598 1.1.1.8.2.1 martin </div>
3599 1.1.1.8.2.1 martin
3600 1.1.1.8.2.1 martin <h4 id="XML_DefaultCurrent">
3601 1.1.1.8.2.1 martin XML_DefaultCurrent
3602 1.1.1.8.2.1 martin </h4>
3603 1.1 tron
3604 1.1.1.8.2.1 martin <pre class="fcndec">
3605 1.1 tron void XMLCALL
3606 1.1 tron XML_DefaultCurrent(XML_Parser parser);
3607 1.1 tron </pre>
3608 1.1.1.8.2.1 martin <div class="fcndef">
3609 1.1.1.8.2.1 martin This can be called within a handler for a start element, end element, processing
3610 1.1.1.8.2.1 martin instruction or character data. It causes the corresponding markup to be passed to
3611 1.1.1.8.2.1 martin the default handler set by <code><a href=
3612 1.1.1.8.2.1 martin "#XML_SetDefaultHandler">XML_SetDefaultHandler</a></code> or <code><a href=
3613 1.1.1.8.2.1 martin "#XML_SetDefaultHandlerExpand">XML_SetDefaultHandlerExpand</a></code>. It does
3614 1.1.1.8.2.1 martin nothing if there is not a default handler.
3615 1.1.1.8.2.1 martin </div>
3616 1.1.1.8.2.1 martin
3617 1.1.1.8.2.1 martin <h4 id="XML_ExpatVersion">
3618 1.1.1.8.2.1 martin XML_ExpatVersion
3619 1.1.1.8.2.1 martin </h4>
3620 1.1 tron
3621 1.1.1.8.2.1 martin <pre class="fcndec">
3622 1.1 tron XML_LChar * XMLCALL
3623 1.1 tron XML_ExpatVersion();
3624 1.1 tron </pre>
3625 1.1.1.8.2.1 martin <div class="fcndef">
3626 1.1.1.8.2.1 martin Return the library version as a string (e.g. <code>"expat_1.95.1"</code>).
3627 1.1.1.8.2.1 martin </div>
3628 1.1.1.8.2.1 martin
3629 1.1.1.8.2.1 martin <h4 id="XML_ExpatVersionInfo">
3630 1.1.1.8.2.1 martin XML_ExpatVersionInfo
3631 1.1.1.8.2.1 martin </h4>
3632 1.1 tron
3633 1.1.1.8.2.1 martin <pre class="fcndec">
3634 1.1 tron struct XML_Expat_Version XMLCALL
3635 1.1 tron XML_ExpatVersionInfo();
3636 1.1 tron </pre>
3637 1.1.1.8.2.1 martin
3638 1.1.1.8.2.1 martin <pre class="signature">
3639 1.1 tron typedef struct {
3640 1.1 tron int major;
3641 1.1 tron int minor;
3642 1.1 tron int micro;
3643 1.1 tron } XML_Expat_Version;
3644 1.1 tron </pre>
3645 1.1.1.8.2.1 martin <div class="fcndef">
3646 1.1.1.8.2.1 martin Return the library version information as a structure. Some macros are also
3647 1.1.1.8.2.1 martin defined that support compile-time tests of the library version:
3648 1.1.1.8.2.1 martin <ul>
3649 1.1.1.8.2.1 martin <li>
3650 1.1.1.8.2.1 martin <code>XML_MAJOR_VERSION</code>
3651 1.1.1.8.2.1 martin </li>
3652 1.1.1.8.2.1 martin
3653 1.1.1.8.2.1 martin <li>
3654 1.1.1.8.2.1 martin <code>XML_MINOR_VERSION</code>
3655 1.1.1.8.2.1 martin </li>
3656 1.1.1.8.2.1 martin
3657 1.1.1.8.2.1 martin <li>
3658 1.1.1.8.2.1 martin <code>XML_MICRO_VERSION</code>
3659 1.1.1.8.2.1 martin </li>
3660 1.1.1.8.2.1 martin </ul>
3661 1.1.1.8.2.1 martin Testing these constants is currently the best way to determine if particular
3662 1.1.1.8.2.1 martin parts of the Expat API are available.
3663 1.1.1.8.2.1 martin </div>
3664 1.1.1.8.2.1 martin
3665 1.1.1.8.2.1 martin <h4 id="XML_GetFeatureList">
3666 1.1.1.8.2.1 martin XML_GetFeatureList
3667 1.1.1.8.2.1 martin </h4>
3668 1.1 tron
3669 1.1.1.8.2.1 martin <pre class="fcndec">
3670 1.1 tron const XML_Feature * XMLCALL
3671 1.1 tron XML_GetFeatureList();
3672 1.1 tron </pre>
3673 1.1.1.8.2.1 martin
3674 1.1.1.8.2.1 martin <pre class="signature">
3675 1.1 tron enum XML_FeatureEnum {
3676 1.1 tron XML_FEATURE_END = 0,
3677 1.1 tron XML_FEATURE_UNICODE,
3678 1.1 tron XML_FEATURE_UNICODE_WCHAR_T,
3679 1.1 tron XML_FEATURE_DTD,
3680 1.1 tron XML_FEATURE_CONTEXT_BYTES,
3681 1.1 tron XML_FEATURE_MIN_SIZE,
3682 1.1 tron XML_FEATURE_SIZEOF_XML_CHAR,
3683 1.1 tron XML_FEATURE_SIZEOF_XML_LCHAR,
3684 1.1 tron XML_FEATURE_NS,
3685 1.1 tron XML_FEATURE_LARGE_SIZE
3686 1.1 tron };
3687 1.1 tron
3688 1.1 tron typedef struct {
3689 1.1 tron enum XML_FeatureEnum feature;
3690 1.1 tron XML_LChar *name;
3691 1.1 tron long int value;
3692 1.1 tron } XML_Feature;
3693 1.1 tron </pre>
3694 1.1.1.8.2.1 martin <div class="fcndef">
3695 1.1.1.8.2.1 martin <p>
3696 1.1.1.8.2.1 martin Returns a list of "feature" records, providing details on how Expat was
3697 1.1.1.8.2.1 martin configured at compile time. Most applications should not need to worry about
3698 1.1.1.8.2.1 martin this, but this information is otherwise not available from Expat. This function
3699 1.1.1.8.2.1 martin allows code that does need to check these features to do so at runtime.
3700 1.1.1.8.2.1 martin </p>
3701 1.1.1.8.2.1 martin
3702 1.1.1.8.2.1 martin <p>
3703 1.1.1.8.2.1 martin The return value is an array of <code>XML_Feature</code>, terminated by a
3704 1.1.1.8.2.1 martin record with a <code>feature</code> of <code>XML_FEATURE_END</code> and
3705 1.1.1.8.2.1 martin <code>name</code> of <code>NULL</code>, identifying the feature-test macros
3706 1.1.1.8.2.1 martin Expat was compiled with. Since an application that requires this kind of
3707 1.1.1.8.2.1 martin information needs to determine the type of character the <code>name</code>
3708 1.1.1.8.2.1 martin points to, records for the <code>XML_FEATURE_SIZEOF_XML_CHAR</code> and
3709 1.1.1.8.2.1 martin <code>XML_FEATURE_SIZEOF_XML_LCHAR</code> will be located at the beginning of
3710 1.1.1.8.2.1 martin the list, followed by <code>XML_FEATURE_UNICODE</code> and
3711 1.1.1.8.2.1 martin <code>XML_FEATURE_UNICODE_WCHAR_T</code>, if they are present at all.
3712 1.1.1.8.2.1 martin </p>
3713 1.1.1.8.2.1 martin
3714 1.1.1.8.2.1 martin <p>
3715 1.1.1.8.2.1 martin Some features have an associated value. If there isn't an associated value, the
3716 1.1.1.8.2.1 martin <code>value</code> field is set to 0. At this time, the following features have
3717 1.1.1.8.2.1 martin been defined to have values:
3718 1.1.1.8.2.1 martin </p>
3719 1.1.1.8.2.1 martin
3720 1.1.1.8.2.1 martin <dl>
3721 1.1.1.8.2.1 martin <dt>
3722 1.1.1.8.2.1 martin <code>XML_FEATURE_SIZEOF_XML_CHAR</code>
3723 1.1.1.8.2.1 martin </dt>
3724 1.1.1.8.2.1 martin
3725 1.1.1.8.2.1 martin <dd>
3726 1.1.1.8.2.1 martin The number of bytes occupied by one <code>XML_Char</code> character.
3727 1.1.1.8.2.1 martin </dd>
3728 1.1.1.8.2.1 martin
3729 1.1.1.8.2.1 martin <dt>
3730 1.1.1.8.2.1 martin <code>XML_FEATURE_SIZEOF_XML_LCHAR</code>
3731 1.1.1.8.2.1 martin </dt>
3732 1.1.1.8.2.1 martin
3733 1.1.1.8.2.1 martin <dd>
3734 1.1.1.8.2.1 martin The number of bytes occupied by one <code>XML_LChar</code> character.
3735 1.1.1.8.2.1 martin </dd>
3736 1.1.1.8.2.1 martin
3737 1.1.1.8.2.1 martin <dt>
3738 1.1.1.8.2.1 martin <code>XML_FEATURE_CONTEXT_BYTES</code>
3739 1.1.1.8.2.1 martin </dt>
3740 1.1.1.8.2.1 martin
3741 1.1.1.8.2.1 martin <dd>
3742 1.1.1.8.2.1 martin The maximum number of characters of context which can be reported by
3743 1.1.1.8.2.1 martin <code><a href="#XML_GetInputContext">XML_GetInputContext</a></code>.
3744 1.1.1.8.2.1 martin </dd>
3745 1.1.1.8.2.1 martin </dl>
3746 1.1.1.8.2.1 martin </div>
3747 1.1.1.8.2.1 martin
3748 1.1.1.8.2.1 martin <h4 id="XML_FreeContentModel">
3749 1.1.1.8.2.1 martin XML_FreeContentModel
3750 1.1.1.8.2.1 martin </h4>
3751 1.1 tron
3752 1.1.1.8.2.1 martin <pre class="fcndec">
3753 1.1 tron void XMLCALL
3754 1.1 tron XML_FreeContentModel(XML_Parser parser, XML_Content *model);
3755 1.1 tron </pre>
3756 1.1.1.8.2.1 martin <div class="fcndef">
3757 1.1.1.8.2.1 martin Function to deallocate the <code>model</code> argument passed to the
3758 1.1.1.8.2.1 martin <code>XML_ElementDeclHandler</code> callback set using <code><a href=
3759 1.1.1.8.2.1 martin "#XML_SetElementDeclHandler">XML_ElementDeclHandler</a></code>. This function
3760 1.1.1.8.2.1 martin should not be used for any other purpose.
3761 1.1.1.8.2.1 martin </div>
3762 1.1.1.8.2.1 martin
3763 1.1.1.8.2.1 martin <p>
3764 1.1.1.8.2.1 martin The following functions allow external code to share the memory allocator an
3765 1.1.1.8.2.1 martin <code>XML_Parser</code> has been configured to use. This is especially useful for
3766 1.1.1.8.2.1 martin third-party libraries that interact with a parser object created by application
3767 1.1.1.8.2.1 martin code, or heavily layered applications. This can be essential when using
3768 1.1.1.8.2.1 martin dynamically loaded libraries which use different C standard libraries (this can
3769 1.1.1.8.2.1 martin happen on Windows, at least).
3770 1.1.1.8.2.1 martin </p>
3771 1.1.1.8.2.1 martin
3772 1.1.1.8.2.1 martin <h4 id="XML_MemMalloc">
3773 1.1.1.8.2.1 martin XML_MemMalloc
3774 1.1.1.8.2.1 martin </h4>
3775 1.1 tron
3776 1.1.1.8.2.1 martin <pre class="fcndec">
3777 1.1 tron void * XMLCALL
3778 1.1 tron XML_MemMalloc(XML_Parser parser, size_t size);
3779 1.1 tron </pre>
3780 1.1.1.8.2.1 martin <div class="fcndef">
3781 1.1.1.8.2.1 martin Allocate <code>size</code> bytes of memory using the allocator the
3782 1.1.1.8.2.1 martin <code>parser</code> object has been configured to use. Returns a pointer to the
3783 1.1.1.8.2.1 martin memory or <code>NULL</code> on failure. Memory allocated in this way must be
3784 1.1.1.8.2.1 martin freed using <code><a href="#XML_MemFree">XML_MemFree</a></code>.
3785 1.1.1.8.2.1 martin </div>
3786 1.1.1.8.2.1 martin
3787 1.1.1.8.2.1 martin <h4 id="XML_MemRealloc">
3788 1.1.1.8.2.1 martin XML_MemRealloc
3789 1.1.1.8.2.1 martin </h4>
3790 1.1 tron
3791 1.1.1.8.2.1 martin <pre class="fcndec">
3792 1.1 tron void * XMLCALL
3793 1.1 tron XML_MemRealloc(XML_Parser parser, void *ptr, size_t size);
3794 1.1 tron </pre>
3795 1.1.1.8.2.1 martin <div class="fcndef">
3796 1.1.1.8.2.1 martin Allocate <code>size</code> bytes of memory using the allocator the
3797 1.1.1.8.2.1 martin <code>parser</code> object has been configured to use. <code>ptr</code> must
3798 1.1.1.8.2.1 martin point to a block of memory allocated by <code><a href=
3799 1.1.1.8.2.1 martin "#XML_MemMalloc">XML_MemMalloc</a></code> or <code>XML_MemRealloc</code>, or be
3800 1.1.1.8.2.1 martin <code>NULL</code>. This function tries to expand the block pointed to by
3801 1.1.1.8.2.1 martin <code>ptr</code> if possible. Returns a pointer to the memory or
3802 1.1.1.8.2.1 martin <code>NULL</code> on failure. On success, the original block has either been
3803 1.1.1.8.2.1 martin expanded or freed. On failure, the original block has not been freed; the caller
3804 1.1.1.8.2.1 martin is responsible for freeing the original block. Memory allocated in this way must
3805 1.1.1.8.2.1 martin be freed using <code><a href="#XML_MemFree">XML_MemFree</a></code>.
3806 1.1.1.8.2.1 martin </div>
3807 1.1.1.8.2.1 martin
3808 1.1.1.8.2.1 martin <h4 id="XML_MemFree">
3809 1.1.1.8.2.1 martin XML_MemFree
3810 1.1.1.8.2.1 martin </h4>
3811 1.1 tron
3812 1.1.1.8.2.1 martin <pre class="fcndec">
3813 1.1 tron void XMLCALL
3814 1.1 tron XML_MemFree(XML_Parser parser, void *ptr);
3815 1.1 tron </pre>
3816 1.1.1.8.2.1 martin <div class="fcndef">
3817 1.1.1.8.2.1 martin Free a block of memory pointed to by <code>ptr</code>. The block must have been
3818 1.1.1.8.2.1 martin allocated by <code><a href="#XML_MemMalloc">XML_MemMalloc</a></code> or
3819 1.1.1.8.2.1 martin <code>XML_MemRealloc</code>, or be <code>NULL</code>.
3820 1.1.1.8.2.1 martin </div>
3821 1.1.1.8.2.1 martin
3822 1.1.1.8.2.1 martin <hr />
3823 1.1.1.8.2.1 martin
3824 1.1.1.8.2.1 martin <div class="footer">
3825 1.1.1.8.2.1 martin Found a bug in the documentation? <a href=
3826 1.1.1.8.2.1 martin "https://github.com/libexpat/libexpat/issues">Please file a bug report.</a>
3827 1.1.1.8.2.1 martin </div>
3828 1.1.1.8.2.1 martin </div>
3829 1.1.1.8.2.1 martin </body>
3830 1.1 tron </html>
3831