-
Notifications
You must be signed in to change notification settings - Fork 428
/
reference.html
2596 lines (2317 loc) · 101 KB
/
reference.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<!--
__ __ _
___\ \/ /_ __ __ _| |_
/ _ \\ /| '_ \ / _` | __|
| __// \| |_) | (_| | |_
\___/_/\_\ .__/ \__,_|\__|
|_| XML parser
Copyright (c) 2000 Clark Cooper <coopercc@users.sourceforge.net>
Copyright (c) 2000-2004 Fred L. Drake, Jr. <fdrake@users.sourceforge.net>
Copyright (c) 2002-2012 Karl Waclawek <karl@waclawek.net>
Copyright (c) 2017-2021 Sebastian Pipping <sebastian@pipping.org>
Copyright (c) 2017 Jakub Wilk <jwilk@jwilk.net>
Copyright (c) 2021 Tomas Korbar <tkorbar@redhat.com>
Copyright (c) 2021 Nicolas Cavallari <nicolas.cavallari@green-communications.fr>
Licensed under the MIT license:
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the
following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.
-->
<title>Expat XML Parser</title>
<meta name="author" content="Clark Cooper, coopercc@netheaven.com" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<link href="ok.min.css" rel="stylesheet" type="text/css" />
<link href="style.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div>
<h1>
The Expat XML Parser
<small>Release 2.4.2</small>
</h1>
</div>
<div class="content">
<p>Expat is a library, written in C, for parsing XML documents. It's
the underlying XML parser for the open source Mozilla project, Perl's
<code>XML::Parser</code>, Python's <code>xml.parsers.expat</code>, and
other open-source XML parsers.</p>
<p>This library is the creation of James Clark, who's also given us
groff (an nroff look-alike), Jade (an implementation of ISO's DSSSL
stylesheet language for SGML), XP (a Java XML parser package), XT (a
Java XSL engine). James was also the technical lead on the XML
Working Group at W3C that produced the XML specification.</p>
<p>This is free software, licensed under the <a
href="../COPYING">MIT/X Consortium license</a>. You may download it
from <a href="http://www.libexpat.org/">the Expat home page</a>.
</p>
<p>The bulk of this document was originally commissioned as an article
by <a href="http://www.xml.com/">XML.com</a>. They graciously allowed
Clark Cooper to retain copyright and to distribute it with Expat.
This version has been substantially extended to include documentation
on features which have been added since the original article was
published, and additional information on using the original
interface.</p>
<hr />
<h2>Table of Contents</h2>
<ul>
<li><a href="#overview">Overview</a></li>
<li><a href="#building">Building and Installing</a></li>
<li><a href="#using">Using Expat</a></li>
<li><a href="#reference">Reference</a>
<ul>
<li><a href="#creation">Parser Creation Functions</a>
<ul>
<li><a href="#XML_ParserCreate">XML_ParserCreate</a></li>
<li><a href="#XML_ParserCreateNS">XML_ParserCreateNS</a></li>
<li><a href="#XML_ParserCreate_MM">XML_ParserCreate_MM</a></li>
<li><a href="#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></li>
<li><a href="#XML_ParserFree">XML_ParserFree</a></li>
<li><a href="#XML_ParserReset">XML_ParserReset</a></li>
</ul>
</li>
<li><a href="#parsing">Parsing Functions</a>
<ul>
<li><a href="#XML_Parse">XML_Parse</a></li>
<li><a href="#XML_ParseBuffer">XML_ParseBuffer</a></li>
<li><a href="#XML_GetBuffer">XML_GetBuffer</a></li>
<li><a href="#XML_StopParser">XML_StopParser</a></li>
<li><a href="#XML_ResumeParser">XML_ResumeParser</a></li>
<li><a href="#XML_GetParsingStatus">XML_GetParsingStatus</a></li>
</ul>
</li>
<li><a href="#setting">Handler Setting Functions</a>
<ul>
<li><a href="#XML_SetStartElementHandler">XML_SetStartElementHandler</a></li>
<li><a href="#XML_SetEndElementHandler">XML_SetEndElementHandler</a></li>
<li><a href="#XML_SetElementHandler">XML_SetElementHandler</a></li>
<li><a href="#XML_SetCharacterDataHandler">XML_SetCharacterDataHandler</a></li>
<li><a href="#XML_SetProcessingInstructionHandler">XML_SetProcessingInstructionHandler</a></li>
<li><a href="#XML_SetCommentHandler">XML_SetCommentHandler</a></li>
<li><a href="#XML_SetStartCdataSectionHandler">XML_SetStartCdataSectionHandler</a></li>
<li><a href="#XML_SetEndCdataSectionHandler">XML_SetEndCdataSectionHandler</a></li>
<li><a href="#XML_SetCdataSectionHandler">XML_SetCdataSectionHandler</a></li>
<li><a href="#XML_SetDefaultHandler">XML_SetDefaultHandler</a></li>
<li><a href="#XML_SetDefaultHandlerExpand">XML_SetDefaultHandlerExpand</a></li>
<li><a href="#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a></li>
<li><a href="#XML_SetExternalEntityRefHandlerArg">XML_SetExternalEntityRefHandlerArg</a></li>
<li><a href="#XML_SetSkippedEntityHandler">XML_SetSkippedEntityHandler</a></li>
<li><a href="#XML_SetUnknownEncodingHandler">XML_SetUnknownEncodingHandler</a></li>
<li><a href="#XML_SetStartNamespaceDeclHandler">XML_SetStartNamespaceDeclHandler</a></li>
<li><a href="#XML_SetEndNamespaceDeclHandler">XML_SetEndNamespaceDeclHandler</a></li>
<li><a href="#XML_SetNamespaceDeclHandler">XML_SetNamespaceDeclHandler</a></li>
<li><a href="#XML_SetXmlDeclHandler">XML_SetXmlDeclHandler</a></li>
<li><a href="#XML_SetStartDoctypeDeclHandler">XML_SetStartDoctypeDeclHandler</a></li>
<li><a href="#XML_SetEndDoctypeDeclHandler">XML_SetEndDoctypeDeclHandler</a></li>
<li><a href="#XML_SetDoctypeDeclHandler">XML_SetDoctypeDeclHandler</a></li>
<li><a href="#XML_SetElementDeclHandler">XML_SetElementDeclHandler</a></li>
<li><a href="#XML_SetAttlistDeclHandler">XML_SetAttlistDeclHandler</a></li>
<li><a href="#XML_SetEntityDeclHandler">XML_SetEntityDeclHandler</a></li>
<li><a href="#XML_SetUnparsedEntityDeclHandler">XML_SetUnparsedEntityDeclHandler</a></li>
<li><a href="#XML_SetNotationDeclHandler">XML_SetNotationDeclHandler</a></li>
<li><a href="#XML_SetNotStandaloneHandler">XML_SetNotStandaloneHandler</a></li>
</ul>
</li>
<li><a href="#position">Parse Position and Error Reporting Functions</a>
<ul>
<li><a href="#XML_GetErrorCode">XML_GetErrorCode</a></li>
<li><a href="#XML_ErrorString">XML_ErrorString</a></li>
<li><a href="#XML_GetCurrentByteIndex">XML_GetCurrentByteIndex</a></li>
<li><a href="#XML_GetCurrentLineNumber">XML_GetCurrentLineNumber</a></li>
<li><a href="#XML_GetCurrentColumnNumber">XML_GetCurrentColumnNumber</a></li>
<li><a href="#XML_GetCurrentByteCount">XML_GetCurrentByteCount</a></li>
<li><a href="#XML_GetInputContext">XML_GetInputContext</a></li>
</ul>
</li>
<li>
<a href="#billion-laughs">Billion Laughs Attack Protection</a>
<ul>
<li><a href="#XML_SetBillionLaughsAttackProtectionMaximumAmplification">XML_SetBillionLaughsAttackProtectionMaximumAmplification</a></li>
<li><a href="#XML_SetBillionLaughsAttackProtectionActivationThreshold">XML_SetBillionLaughsAttackProtectionActivationThreshold</a></li>
</ul>
</li>
<li><a href="#miscellaneous">Miscellaneous Functions</a>
<ul>
<li><a href="#XML_SetUserData">XML_SetUserData</a></li>
<li><a href="#XML_GetUserData">XML_GetUserData</a></li>
<li><a href="#XML_UseParserAsHandlerArg">XML_UseParserAsHandlerArg</a></li>
<li><a href="#XML_SetBase">XML_SetBase</a></li>
<li><a href="#XML_GetBase">XML_GetBase</a></li>
<li><a href="#XML_GetSpecifiedAttributeCount">XML_GetSpecifiedAttributeCount</a></li>
<li><a href="#XML_GetIdAttributeIndex">XML_GetIdAttributeIndex</a></li>
<li><a href="#XML_GetAttributeInfo">XML_GetAttributeInfo</a></li>
<li><a href="#XML_SetEncoding">XML_SetEncoding</a></li>
<li><a href="#XML_SetParamEntityParsing">XML_SetParamEntityParsing</a></li>
<li><a href="#XML_SetHashSalt">XML_SetHashSalt</a></li>
<li><a href="#XML_UseForeignDTD">XML_UseForeignDTD</a></li>
<li><a href="#XML_SetReturnNSTriplet">XML_SetReturnNSTriplet</a></li>
<li><a href="#XML_DefaultCurrent">XML_DefaultCurrent</a></li>
<li><a href="#XML_ExpatVersion">XML_ExpatVersion</a></li>
<li><a href="#XML_ExpatVersionInfo">XML_ExpatVersionInfo</a></li>
<li><a href="#XML_GetFeatureList">XML_GetFeatureList</a></li>
<li><a href="#XML_FreeContentModel">XML_FreeContentModel</a></li>
<li><a href="#XML_MemMalloc">XML_MemMalloc</a></li>
<li><a href="#XML_MemRealloc">XML_MemRealloc</a></li>
<li><a href="#XML_MemFree">XML_MemFree</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<hr />
<h2><a name="overview">Overview</a></h2>
<p>Expat is a stream-oriented parser. You register callback (or
handler) functions with the parser and then start feeding it the
document. As the parser recognizes parts of the document, it will
call the appropriate handler for that part (if you've registered one.)
The document is fed to the parser in pieces, so you can start parsing
before you have all the document. This also allows you to parse really
huge documents that won't fit into memory.</p>
<p>Expat can be intimidating due to the many kinds of handlers and
options you can set. But you only need to learn four functions in
order to do 90% of what you'll want to do with it:</p>
<dl>
<dt><code><a href= "#XML_ParserCreate"
>XML_ParserCreate</a></code></dt>
<dd>Create a new parser object.</dd>
<dt><code><a href= "#XML_SetElementHandler"
>XML_SetElementHandler</a></code></dt>
<dd>Set handlers for start and end tags.</dd>
<dt><code><a href= "#XML_SetCharacterDataHandler"
>XML_SetCharacterDataHandler</a></code></dt>
<dd>Set handler for text.</dd>
<dt><code><a href= "#XML_Parse"
>XML_Parse</a></code></dt>
<dd>Pass a buffer full of document to the parser</dd>
</dl>
<p>These functions and others are described in the <a
href="#reference">reference</a> part of this document. The reference
section also describes in detail the parameters passed to the
different types of handlers.</p>
<p>Let's look at a very simple example program that only uses 3 of the
above functions (it doesn't need to set a character handler.) The
program <a href="../examples/outline.c">outline.c</a> prints an
element outline, indenting child elements to distinguish them from the
parent element that contains them. The start handler does all the
work. It prints two indenting spaces for every level of ancestor
elements, then it prints the element and attribute
information. Finally it increments the global <code>Depth</code>
variable.</p>
<pre class="eg">
int Depth;
void XMLCALL
start(void *data, const char *el, const char **attr) {
int i;
for (i = 0; i < Depth; i++)
printf(" ");
printf("%s", el);
for (i = 0; attr[i]; i += 2) {
printf(" %s='%s'", attr[i], attr[i + 1]);
}
printf("\n");
Depth++;
} /* End of start handler */
</pre>
<p>The end tag simply does the bookkeeping work of decrementing
<code>Depth</code>.</p>
<pre class="eg">
void XMLCALL
end(void *data, const char *el) {
Depth--;
} /* End of end handler */
</pre>
<p>Note the <code>XMLCALL</code> annotation used for the callbacks.
This is used to ensure that the Expat and the callbacks are using the
same calling convention in case the compiler options used for Expat
itself and the client code are different. Expat tries not to care
what the default calling convention is, though it may require that it
be compiled with a default convention of "cdecl" on some platforms.
For code which uses Expat, however, the calling convention is
specified by the <code>XMLCALL</code> annotation on most platforms;
callbacks should be defined using this annotation.</p>
<p>The <code>XMLCALL</code> annotation was added in Expat 1.95.7, but
existing working Expat applications don't need to add it (since they
are already using the "cdecl" calling convention, or they wouldn't be
working). The annotation is only needed if the default calling
convention may be something other than "cdecl". To use the annotation
safely with older versions of Expat, you can conditionally define it
<em>after</em> including Expat's header file:</p>
<pre class="eg">
#include <expat.h>
#ifndef XMLCALL
#if defined(_MSC_EXTENSIONS) && !defined(__BEOS__) && !defined(__CYGWIN__)
#define XMLCALL __cdecl
#elif defined(__GNUC__)
#define XMLCALL __attribute__((cdecl))
#else
#define XMLCALL
#endif
#endif
</pre>
<p>After creating the parser, the main program just has the job of
shoveling the document to the parser so that it can do its work.</p>
<hr />
<h2><a name="building">Building and Installing Expat</a></h2>
<p>The Expat distribution comes as a compressed (with GNU gzip) tar
file. You may download the latest version from <a href=
"http://sourceforge.net/projects/expat/" >Source Forge</a>. After
unpacking this, cd into the directory. Then follow either the Win32
directions or Unix directions below.</p>
<h3>Building under Win32</h3>
<p>If you're using the GNU compiler under cygwin, follow the Unix
directions in the next section. Otherwise if you have Microsoft's
Developer Studio installed,
you can use CMake to generate a <code>.sln</code> file, e.g.
<code>
cmake -G"Visual Studio 15 2017" -DCMAKE_BUILD_TYPE=RelWithDebInfo .
</code>, and build Expat using <code>msbuild /m expat.sln</code> after.</p>
<p>Alternatively, you may download the Win32 binary package that
contains the "expat.h" include file and a pre-built DLL.</p>
<h3>Building under Unix (or GNU)</h3>
<p>First you'll need to run the configure shell script in order to
configure the Makefiles and headers for your system.</p>
<p>If you're happy with all the defaults that configure picks for you,
and you have permission on your system to install into /usr/local, you
can install Expat with this sequence of commands:</p>
<pre class="eg">
./configure
make
make install
</pre>
<p>There are some options that you can provide to this script, but the
only one we'll mention here is the <code>--prefix</code> option. You
can find out all the options available by running configure with just
the <code>--help</code> option.</p>
<p>By default, the configure script sets things up so that the library
gets installed in <code>/usr/local/lib</code> and the associated
header file in <code>/usr/local/include</code>. But if you were to
give the option, <code>--prefix=/home/me/mystuff</code>, then the
library and header would get installed in
<code>/home/me/mystuff/lib</code> and
<code>/home/me/mystuff/include</code> respectively.</p>
<h3>Configuring Expat Using the Pre-Processor</h3>
<p>Expat's feature set can be configured using a small number of
pre-processor definitions. The definition of this symbols does not
affect the set of entry points for Expat, only the behavior of the API
and the definition of character types in the case of
<code>XML_UNICODE_WCHAR_T</code>. The symbols are:</p>
<dl class="cpp-symbols">
<dt>XML_DTD</dt>
<dd>Include support for using and reporting DTD-based content. If
this is defined, default attribute values from an external DTD subset
are reported and attribute value normalization occurs based on the
type of attributes defined in the external subset. Without
this, Expat has a smaller memory footprint and can be faster, but will
not load external entities or process conditional sections. This does
not affect the set of functions available in the API.</dd>
<dt>XML_NS</dt>
<dd>When defined, support for the <cite><a href=
"http://www.w3.org/TR/REC-xml-names/" >Namespaces in XML</a></cite>
specification is included.</dd>
<dt>XML_UNICODE</dt>
<dd>When defined, character data reported to the application is
encoded in UTF-16 using wide characters of the type
<code>XML_Char</code>. This is implied if
<code>XML_UNICODE_WCHAR_T</code> is defined.</dd>
<dt>XML_UNICODE_WCHAR_T</dt>
<dd>If defined, causes the <code>XML_Char</code> character type to be
defined using the <code>wchar_t</code> type; otherwise, <code>unsigned
short</code> is used. Defining this implies
<code>XML_UNICODE</code>.</dd>
<dt>XML_LARGE_SIZE</dt>
<dd>If defined, causes the <code>XML_Size</code> and <code>XML_Index</code>
integer types to be at least 64 bits in size. This is intended to support
processing of very large input streams, where the return values of
<code><a href="#XML_GetCurrentByteIndex" >XML_GetCurrentByteIndex</a></code>,
<code><a href="#XML_GetCurrentLineNumber" >XML_GetCurrentLineNumber</a></code> and
<code><a href="#XML_GetCurrentColumnNumber" >XML_GetCurrentColumnNumber</a></code>
could overflow. It may not be supported by all compilers, and is turned
off by default.</dd>
<dt>XML_CONTEXT_BYTES</dt>
<dd>The number of input bytes of markup context which the parser will
ensure are available for reporting via <code><a href=
"#XML_GetInputContext" >XML_GetInputContext</a></code>. This is
normally set to 1024, and must be set to a positive integer. If this
is not defined, the input context will not be available and <code><a
href= "#XML_GetInputContext" >XML_GetInputContext</a></code> will
always report NULL. Without this, Expat has a smaller memory
footprint and can be faster.</dd>
<dt>XML_STATIC</dt>
<dd>On Windows, this should be set if Expat is going to be linked
statically with the code that calls it; this is required to get all
the right MSVC magic annotations correct. This is ignored on other
platforms.</dd>
<dt>XML_ATTR_INFO</dt>
<dd>If defined, makes the additional function <code><a href=
"#XML_GetAttributeInfo" >XML_GetAttributeInfo</a></code> available
for reporting attribute byte offsets.</dd>
</dl>
<hr />
<h2><a name="using">Using Expat</a></h2>
<h3>Compiling and Linking Against Expat</h3>
<p>Unless you installed Expat in a location not expected by your
compiler and linker, all you have to do to use Expat in your programs
is to include the Expat header (<code>#include <expat.h></code>)
in your files that make calls to it and to tell the linker that it
needs to link against the Expat library. On Unix systems, this would
usually be done with the <code>-lexpat</code> argument. Otherwise,
you'll need to tell the compiler where to look for the Expat header
and the linker where to find the Expat library. You may also need to
take steps to tell the operating system where to find this library at
run time.</p>
<p>On a Unix-based system, here's what a Makefile might look like when
Expat is installed in a standard location:</p>
<pre class="eg">
CC=cc
LDFLAGS=
LIBS= -lexpat
xmlapp: xmlapp.o
$(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS)
</pre>
<p>If you installed Expat in, say, <code>/home/me/mystuff</code>, then
the Makefile would look like this:</p>
<pre class="eg">
CC=cc
CFLAGS= -I/home/me/mystuff/include
LDFLAGS=
LIBS= -L/home/me/mystuff/lib -lexpat
xmlapp: xmlapp.o
$(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS)
</pre>
<p>You'd also have to set the environment variable
<code>LD_LIBRARY_PATH</code> to <code>/home/me/mystuff/lib</code> (or
to <code>${LD_LIBRARY_PATH}:/home/me/mystuff/lib</code> if
LD_LIBRARY_PATH already has some directories in it) in order to run
your application.</p>
<h3>Expat Basics</h3>
<p>As we saw in the example in the overview, the first step in parsing
an XML document with Expat is to create a parser object. There are <a
href="#creation">three functions</a> in the Expat API for creating a
parser object. However, only two of these (<code><a href=
"#XML_ParserCreate" >XML_ParserCreate</a></code> and <code><a href=
"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>) can be used for
constructing a parser for a top-level document. The object returned
by these functions is an opaque pointer (i.e. "expat.h" declares it as
void *) to data with further internal structure. In order to free the
memory associated with this object you must call <code><a href=
"#XML_ParserFree" >XML_ParserFree</a></code>. Note that if you have
provided any <a href="#userdata">user data</a> that gets stored in the
parser, then your application is responsible for freeing it prior to
calling <code>XML_ParserFree</code>.</p>
<p>The objects returned by the parser creation functions are good for
parsing only one XML document or external parsed entity. If your
application needs to parse many XML documents, then it needs to create
a parser object for each one. The best way to deal with this is to
create a higher level object that contains all the default
initialization you want for your parser objects.</p>
<p>Walking through a document hierarchy with a stream oriented parser
will require a good stack mechanism in order to keep track of current
context. For instance, to answer the simple question, "What element
does this text belong to?" requires a stack, since the parser may have
descended into other elements that are children of the current one and
has encountered this text on the way out.</p>
<p>The things you're likely to want to keep on a stack are the
currently opened element and it's attributes. You push this
information onto the stack in the start handler and you pop it off in
the end handler.</p>
<p>For some tasks, it is sufficient to just keep information on what
the depth of the stack is (or would be if you had one.) The outline
program shown above presents one example. Another such task would be
skipping over a complete element. When you see the start tag for the
element you want to skip, you set a skip flag and record the depth at
which the element started. When the end tag handler encounters the
same depth, the skipped element has ended and the flag may be
cleared. If you follow the convention that the root element starts at
1, then you can use the same variable for skip flag and skip
depth.</p>
<pre class="eg">
void
init_info(Parseinfo *info) {
info->skip = 0;
info->depth = 1;
/* Other initializations here */
} /* End of init_info */
void XMLCALL
rawstart(void *data, const char *el, const char **attr) {
Parseinfo *inf = (Parseinfo *) data;
if (! inf->skip) {
if (should_skip(inf, el, attr)) {
inf->skip = inf->depth;
}
else
start(inf, el, attr); /* This does rest of start handling */
}
inf->depth++;
} /* End of rawstart */
void XMLCALL
rawend(void *data, const char *el) {
Parseinfo *inf = (Parseinfo *) data;
inf->depth--;
if (! inf->skip)
end(inf, el); /* This does rest of end handling */
if (inf->skip == inf->depth)
inf->skip = 0;
} /* End rawend */
</pre>
<p>Notice in the above example the difference in how depth is
manipulated in the start and end handlers. The end tag handler should
be the mirror image of the start tag handler. This is necessary to
properly model containment. Since, in the start tag handler, we
incremented depth <em>after</em> the main body of start tag code, then
in the end handler, we need to manipulate it <em>before</em> the main
body. If we'd decided to increment it first thing in the start
handler, then we'd have had to decrement it last thing in the end
handler.</p>
<h3 id="userdata">Communicating between handlers</h3>
<p>In order to be able to pass information between different handlers
without using globals, you'll need to define a data structure to hold
the shared variables. You can then tell Expat (with the <code><a href=
"#XML_SetUserData" >XML_SetUserData</a></code> function) to pass a
pointer to this structure to the handlers. This is the first
argument received by most handlers. In the <a href="#reference"
>reference section</a>, an argument to a callback function is named
<code>userData</code> and have type <code>void *</code> if the user
data is passed; it will have the type <code>XML_Parser</code> if the
parser itself is passed. When the parser is passed, the user data may
be retrieved using <code><a href="#XML_GetUserData"
>XML_GetUserData</a></code>.</p>
<p>One common case where multiple calls to a single handler may need
to communicate using an application data structure is the case when
content passed to the character data handler (set by <code><a href=
"#XML_SetCharacterDataHandler"
>XML_SetCharacterDataHandler</a></code>) needs to be accumulated. A
common first-time mistake with any of the event-oriented interfaces to
an XML parser is to expect all the text contained in an element to be
reported by a single call to the character data handler. Expat, like
many other XML parsers, reports such data as a sequence of calls;
there's no way to know when the end of the sequence is reached until a
different callback is made. A buffer referenced by the user data
structure proves both an effective and convenient place to accumulate
character data.</p>
<!-- XXX example needed here -->
<h3>XML Version</h3>
<p>Expat is an XML 1.0 parser, and as such never complains based on
the value of the <code>version</code> pseudo-attribute in the XML
declaration, if present.</p>
<p>If an application needs to check the version number (to support
alternate processing), it should use the <code><a href=
"#XML_SetXmlDeclHandler" >XML_SetXmlDeclHandler</a></code> function to
set a handler that uses the information in the XML declaration to
determine what to do. This example shows how to check that only a
version number of <code>"1.0"</code> is accepted:</p>
<pre class="eg">
static int wrong_version;
static XML_Parser parser;
static void XMLCALL
xmldecl_handler(void *userData,
const XML_Char *version,
const XML_Char *encoding,
int standalone)
{
static const XML_Char Version_1_0[] = {'1', '.', '0', 0};
int i;
for (i = 0; i < (sizeof(Version_1_0) / sizeof(Version_1_0[0])); ++i) {
if (version[i] != Version_1_0[i]) {
wrong_version = 1;
/* also clear all other handlers: */
XML_SetCharacterDataHandler(parser, NULL);
...
return;
}
}
...
}
</pre>
<h3>Namespace Processing</h3>
<p>When the parser is created using the <code><a href=
"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>, function, Expat
performs namespace processing. Under namespace processing, Expat
consumes <code>xmlns</code> and <code>xmlns:...</code> attributes,
which declare namespaces for the scope of the element in which they
occur. This means that your start handler will not see these
attributes. Your application can still be informed of these
declarations by setting namespace declaration handlers with <a href=
"#XML_SetNamespaceDeclHandler"
><code>XML_SetNamespaceDeclHandler</code></a>.</p>
<p>Element type and attribute names that belong to a given namespace
are passed to the appropriate handler in expanded form. By default
this expanded form is a concatenation of the namespace URI, the
separator character (which is the 2nd argument to <code><a href=
"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>), and the local
name (i.e. the part after the colon). Names with undeclared prefixes
are not well-formed when namespace processing is enabled, and will
trigger an error. Unprefixed attribute names are never expanded,
and unprefixed element names are only expanded when they are in the
scope of a default namespace.</p>
<p>However if <code><a href= "#XML_SetReturnNSTriplet"
>XML_SetReturnNSTriplet</a></code> has been called with a non-zero
<code>do_nst</code> parameter, then the expanded form for names with
an explicit prefix is a concatenation of: URI, separator, local name,
separator, prefix.</p>
<p>You can set handlers for the start of a namespace declaration and
for the end of a scope of a declaration with the <code><a href=
"#XML_SetNamespaceDeclHandler" >XML_SetNamespaceDeclHandler</a></code>
function. The StartNamespaceDeclHandler is called prior to the start
tag handler and the EndNamespaceDeclHandler is called after the
corresponding end tag that ends the namespace's scope. The namespace
start handler gets passed the prefix and URI for the namespace. For a
default namespace declaration (xmlns='...'), the prefix will be null.
The URI will be null for the case where the default namespace is being
unset. The namespace end handler just gets the prefix for the closing
scope.</p>
<p>These handlers are called for each declaration. So if, for
instance, a start tag had three namespace declarations, then the
StartNamespaceDeclHandler would be called three times before the start
tag handler is called, once for each declaration.</p>
<h3>Character Encodings</h3>
<p>While XML is based on Unicode, and every XML processor is required
to recognized UTF-8 and UTF-16 (1 and 2 byte encodings of Unicode),
other encodings may be declared in XML documents or entities. For the
main document, an XML declaration may contain an encoding
declaration:</p>
<pre>
<?xml version="1.0" encoding="ISO-8859-2"?>
</pre>
<p>External parsed entities may begin with a text declaration, which
looks like an XML declaration with just an encoding declaration:</p>
<pre>
<?xml encoding="Big5"?>
</pre>
<p>With Expat, you may also specify an encoding at the time of
creating a parser. This is useful when the encoding information may
come from a source outside the document itself (like a higher level
protocol.)</p>
<p><a name="builtin_encodings"></a>There are four built-in encodings
in Expat:</p>
<ul>
<li>UTF-8</li>
<li>UTF-16</li>
<li>ISO-8859-1</li>
<li>US-ASCII</li>
</ul>
<p>Anything else discovered in an encoding declaration or in the
protocol encoding specified in the parser constructor, triggers a call
to the <code>UnknownEncodingHandler</code>. This handler gets passed
the encoding name and a pointer to an <code>XML_Encoding</code> data
structure. Your handler must fill in this structure and return
<code>XML_STATUS_OK</code> if it knows how to deal with the
encoding. Otherwise the handler should return
<code>XML_STATUS_ERROR</code>. The handler also gets passed a pointer
to an optional application data structure that you may indicate when
you set the handler.</p>
<p>Expat places restrictions on character encodings that it can
support by filling in the <code>XML_Encoding</code> structure.
include file:</p>
<ol>
<li>Every ASCII character that can appear in a well-formed XML document
must be represented by a single byte, and that byte must correspond to
it's ASCII encoding (except for the characters $@\^'{}~)</li>
<li>Characters must be encoded in 4 bytes or less.</li>
<li>All characters encoded must have Unicode scalar values less than or
equal to 65535 (0xFFFF)<em>This does not apply to the built-in support
for UTF-16 and UTF-8</em></li>
<li>No character may be encoded by more that one distinct sequence of
bytes</li>
</ol>
<p><code>XML_Encoding</code> contains an array of integers that
correspond to the 1st byte of an encoding sequence. If the value in
the array for a byte is zero or positive, then the byte is a single
byte encoding that encodes the Unicode scalar value contained in the
array. A -1 in this array indicates a malformed byte. If the value is
-2, -3, or -4, then the byte is the beginning of a 2, 3, or 4 byte
sequence respectively. Multi-byte sequences are sent to the convert
function pointed at in the <code>XML_Encoding</code> structure. This
function should return the Unicode scalar value for the sequence or -1
if the sequence is malformed.</p>
<p>One pitfall that novice Expat users are likely to fall into is that
although Expat may accept input in various encodings, the strings that
it passes to the handlers are always encoded in UTF-8 or UTF-16
(depending on how Expat was compiled). Your application is responsible
for any translation of these strings into other encodings.</p>
<h3>Handling External Entity References</h3>
<p>Expat does not read or parse external entities directly. Note that
any external DTD is a special case of an external entity. If you've
set no <code>ExternalEntityRefHandler</code>, then external entity
references are silently ignored. Otherwise, it calls your handler with
the information needed to read and parse the external entity.</p>
<p>Your handler isn't actually responsible for parsing the entity, but
it is responsible for creating a subsidiary parser with <code><a href=
"#XML_ExternalEntityParserCreate"
>XML_ExternalEntityParserCreate</a></code> that will do the job. This
returns an instance of <code>XML_Parser</code> that has handlers and
other data structures initialized from the parent parser. You may then
use <code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a
href= "#XML_ParseBuffer">XML_ParseBuffer</a></code> calls against this
parser. Since external entities my refer to other external entities,
your handler should be prepared to be called recursively.</p>
<h3>Parsing DTDs</h3>
<p>In order to parse parameter entities, before starting the parse,
you must call <code><a href= "#XML_SetParamEntityParsing"
>XML_SetParamEntityParsing</a></code> with one of the following
arguments:</p>
<dl>
<dt><code>XML_PARAM_ENTITY_PARSING_NEVER</code></dt>
<dd>Don't parse parameter entities or the external subset</dd>
<dt><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></dt>
<dd>Parse parameter entities and the external subset unless
<code>standalone</code> was set to "yes" in the XML declaration.</dd>
<dt><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></dt>
<dd>Always parse parameter entities and the external subset</dd>
</dl>
<p>In order to read an external DTD, you also have to set an external
entity reference handler as described above.</p>
<h3 id="stop-resume">Temporarily Stopping Parsing</h3>
<p>Expat 1.95.8 introduces a new feature: its now possible to stop
parsing temporarily from within a handler function, even if more data
has already been passed into the parser. Applications for this
include</p>
<ul>
<li>Supporting the <a href= "http://www.w3.org/TR/xinclude/"
>XInclude</a> specification.</li>
<li>Delaying further processing until additional information is
available from some other source.</li>
<li>Adjusting processor load as task priorities shift within an
application.</li>
<li>Stopping parsing completely (simply free or reset the parser
instead of resuming in the outer parsing loop). This can be useful
if an application-domain error is found in the XML being parsed or if
the result of the parse is determined not to be useful after
all.</li>
</ul>
<p>To take advantage of this feature, the main parsing loop of an
application needs to support this specifically. It cannot be
supported with a parsing loop compatible with Expat 1.95.7 or
earlier (though existing loops will continue to work without
supporting the stop/resume feature).</p>
<p>An application that uses this feature for a single parser will have
the rough structure (in pseudo-code):</p>
<pre class="pseudocode">
fd = open_input()
p = create_parser()
if parse_xml(p, fd) {
/* suspended */
int suspended = 1;
while (suspended) {
do_something_else()
if ready_to_resume() {
suspended = continue_parsing(p, fd);
}
}
}
</pre>
<p>An application that may resume any of several parsers based on
input (either from the XML being parsed or some other source) will
certainly have more interesting control structures.</p>
<p>This C function could be used for the <code>parse_xml</code>
function mentioned in the pseudo-code above:</p>
<pre class="eg">
#define BUFF_SIZE 10240
/* Parse a document from the open file descriptor 'fd' until the parse
is complete (the document has been completely parsed, or there's
been an error), or the parse is stopped. Return non-zero when
the parse is merely suspended.
*/
int
parse_xml(XML_Parser p, int fd)
{
for (;;) {
int last_chunk;
int bytes_read;
enum XML_Status status;
void *buff = XML_GetBuffer(p, BUFF_SIZE);
if (buff == NULL) {
/* handle error... */
return 0;
}
bytes_read = read(fd, buff, BUFF_SIZE);
if (bytes_read < 0) {
/* handle error... */
return 0;
}
status = XML_ParseBuffer(p, bytes_read, bytes_read == 0);
switch (status) {
case XML_STATUS_ERROR:
/* handle error... */
return 0;
case XML_STATUS_SUSPENDED:
return 1;
}
if (bytes_read == 0)
return 0;
}
}
</pre>
<p>The corresponding <code>continue_parsing</code> function is
somewhat simpler, since it only need deal with the return code from
<code><a href= "#XML_ResumeParser">XML_ResumeParser</a></code>; it can
delegate the input handling to the <code>parse_xml</code>
function:</p>
<pre class="eg">
/* Continue parsing a document which had been suspended. The 'p' and
'fd' arguments are the same as passed to parse_xml(). Return
non-zero when the parse is suspended.
*/
int
continue_parsing(XML_Parser p, int fd)
{
enum XML_Status status = XML_ResumeParser(p);
switch (status) {
case XML_STATUS_ERROR:
/* handle error... */
return 0;
case XML_ERROR_NOT_SUSPENDED:
/* handle error... */
return 0;.
case XML_STATUS_SUSPENDED:
return 1;
}
return parse_xml(p, fd);
}
</pre>
<p>Now that we've seen what a mess the top-level parsing loop can
become, what have we gained? Very simply, we can now use the <code><a
href= "#XML_StopParser" >XML_StopParser</a></code> function to stop
parsing, without having to go to great lengths to avoid additional
processing that we're expecting to ignore. As a bonus, we get to stop
parsing <em>temporarily</em>, and come back to it when we're
ready.</p>
<p>To stop parsing from a handler function, use the <code><a href=
"#XML_StopParser" >XML_StopParser</a></code> function. This function
takes two arguments; the parser being stopped and a flag indicating
whether the parse can be resumed in the future.</p>
<!-- XXX really need more here -->
<hr />
<!-- ================================================================ -->
<h2><a name="reference">Expat Reference</a></h2>
<h3><a name="creation">Parser Creation</a></h3>
<h4 id="XML_ParserCreate">XML_ParserCreate</h4>
<pre class="fcndec">
XML_Parser XMLCALL
XML_ParserCreate(const XML_Char *encoding);
</pre>
<div class="fcndef">
Construct a new parser. If encoding is non-null, it specifies a
character encoding to use for the document. This overrides the document
encoding declaration. There are four built-in encodings:
<ul>
<li>US-ASCII</li>
<li>UTF-8</li>
<li>UTF-16</li>
<li>ISO-8859-1</li>
</ul>
Any other value will invoke a call to the UnknownEncodingHandler.
</div>
<h4 id="XML_ParserCreateNS">XML_ParserCreateNS</h4>
<pre class="fcndec">
XML_Parser XMLCALL
XML_ParserCreateNS(const XML_Char *encoding,
XML_Char sep);
</pre>
<div class="fcndef">
Constructs a new parser that has namespace processing in effect. Namespace
expanded element names and attribute names are returned as a concatenation
of the namespace URI, <em>sep</em>, and the local part of the name. This
means that you should pick a character for <em>sep</em> that can't be part
of an URI. Since Expat does not check namespace URIs for conformance, the
only safe choice for a namespace separator is a character that is illegal
in XML. For instance, <code>'\xFF'</code> is not legal in UTF-8, and
<code>'\xFFFF'</code> is not legal in UTF-16. There is a special case when
<em>sep</em> is the null character <code>'\0'</code>: the namespace URI and
the local part will be concatenated without any separator - this is intended
to support RDF processors. It is a programming error to use the null separator
with <a href= "#XML_SetReturnNSTriplet">namespace triplets</a>.</div>
<h4 id="XML_ParserCreate_MM">XML_ParserCreate_MM</h4>
<pre class="fcndec">
XML_Parser XMLCALL
XML_ParserCreate_MM(const XML_Char *encoding,
const XML_Memory_Handling_Suite *ms,
const XML_Char *sep);
</pre>
<pre class="signature">
typedef struct {
void *(XMLCALL *malloc_fcn)(size_t size);
void *(XMLCALL *realloc_fcn)(void *ptr, size_t size);
void (XMLCALL *free_fcn)(void *ptr);
} XML_Memory_Handling_Suite;
</pre>
<div class="fcndef">
<p>Construct a new parser using the suite of memory handling functions
specified in <code>ms</code>. If <code>ms</code> is NULL, then use the
standard set of memory management functions. If <code>sep</code> is
non NULL, then namespace processing is enabled in the created parser
and the character pointed at by sep is used as the separator between
the namespace URI and the local part of the name.</p>
</div>
<h4 id="XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</h4>