1/*
2                            __  __            _
3                         ___\ \/ /_ __   __ _| |_
4                        / _ \\  /| '_ \ / _` | __|
5                       |  __//  \| |_) | (_| | |_
6                        \___/_/\_\ .__/ \__,_|\__|
7                                 |_| XML parser
8
9   Copyright (c) 1997-2000 Thai Open Source Software Center Ltd
10   Copyright (c) 2000      Clark Cooper <coopercc@users.sourceforge.net>
11   Copyright (c) 2000-2005 Fred L. Drake, Jr. <fdrake@users.sourceforge.net>
12   Copyright (c) 2001-2002 Greg Stein <gstein@users.sourceforge.net>
13   Copyright (c) 2002-2016 Karl Waclawek <karl@waclawek.net>
14   Copyright (c) 2016-2024 Sebastian Pipping <sebastian@pipping.org>
15   Copyright (c) 2016      Cristian Rodr��guez <crrodriguez@opensuse.org>
16   Copyright (c) 2016      Thomas Beutlich <tc@tbeu.de>
17   Copyright (c) 2017      Rhodri James <rhodri@wildebeest.org.uk>
18   Copyright (c) 2022      Thijs Schreijer <thijs@thijsschreijer.nl>
19   Copyright (c) 2023      Hanno B��ck <hanno@gentoo.org>
20   Copyright (c) 2023      Sony Corporation / Snild Dolkow <snild@sony.com>
21   Licensed under the MIT license:
22
23   Permission is  hereby granted,  free of charge,  to any  person obtaining
24   a  copy  of  this  software   and  associated  documentation  files  (the
25   "Software"),  to  deal in  the  Software  without restriction,  including
26   without  limitation the  rights  to use,  copy,  modify, merge,  publish,
27   distribute, sublicense, and/or sell copies of the Software, and to permit
28   persons  to whom  the Software  is  furnished to  do so,  subject to  the
29   following conditions:
30
31   The above copyright  notice and this permission notice  shall be included
32   in all copies or substantial portions of the Software.
33
34   THE  SOFTWARE  IS  PROVIDED  "AS  IS",  WITHOUT  WARRANTY  OF  ANY  KIND,
35   EXPRESS  OR IMPLIED,  INCLUDING  BUT  NOT LIMITED  TO  THE WARRANTIES  OF
36   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
37   NO EVENT SHALL THE AUTHORS OR  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
38   DAMAGES OR  OTHER LIABILITY, WHETHER  IN AN  ACTION OF CONTRACT,  TORT OR
39   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
40   USE OR OTHER DEALINGS IN THE SOFTWARE.
41*/
42
43#ifndef Expat_INCLUDED
44#define Expat_INCLUDED 1
45
46#include <stdlib.h>
47#include "expat_external.h"
48
49#ifdef __cplusplus
50extern "C" {
51#endif
52
53struct XML_ParserStruct;
54typedef struct XML_ParserStruct *XML_Parser;
55
56typedef unsigned char XML_Bool;
57#define XML_TRUE ((XML_Bool)1)
58#define XML_FALSE ((XML_Bool)0)
59
60/* The XML_Status enum gives the possible return values for several
61   API functions.  The preprocessor #defines are included so this
62   stanza can be added to code that still needs to support older
63   versions of Expat 1.95.x:
64
65   #ifndef XML_STATUS_OK
66   #define XML_STATUS_OK    1
67   #define XML_STATUS_ERROR 0
68   #endif
69
70   Otherwise, the #define hackery is quite ugly and would have been
71   dropped.
72*/
73enum XML_Status {
74  XML_STATUS_ERROR = 0,
75#define XML_STATUS_ERROR XML_STATUS_ERROR
76  XML_STATUS_OK = 1,
77#define XML_STATUS_OK XML_STATUS_OK
78  XML_STATUS_SUSPENDED = 2
79#define XML_STATUS_SUSPENDED XML_STATUS_SUSPENDED
80};
81
82enum XML_Error {
83  XML_ERROR_NONE,
84  XML_ERROR_NO_MEMORY,
85  XML_ERROR_SYNTAX,
86  XML_ERROR_NO_ELEMENTS,
87  XML_ERROR_INVALID_TOKEN,
88  XML_ERROR_UNCLOSED_TOKEN,
89  XML_ERROR_PARTIAL_CHAR,
90  XML_ERROR_TAG_MISMATCH,
91  XML_ERROR_DUPLICATE_ATTRIBUTE,
92  XML_ERROR_JUNK_AFTER_DOC_ELEMENT,
93  XML_ERROR_PARAM_ENTITY_REF,
94  XML_ERROR_UNDEFINED_ENTITY,
95  XML_ERROR_RECURSIVE_ENTITY_REF,
96  XML_ERROR_ASYNC_ENTITY,
97  XML_ERROR_BAD_CHAR_REF,
98  XML_ERROR_BINARY_ENTITY_REF,
99  XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF,
100  XML_ERROR_MISPLACED_XML_PI,
101  XML_ERROR_UNKNOWN_ENCODING,
102  XML_ERROR_INCORRECT_ENCODING,
103  XML_ERROR_UNCLOSED_CDATA_SECTION,
104  XML_ERROR_EXTERNAL_ENTITY_HANDLING,
105  XML_ERROR_NOT_STANDALONE,
106  XML_ERROR_UNEXPECTED_STATE,
107  XML_ERROR_ENTITY_DECLARED_IN_PE,
108  XML_ERROR_FEATURE_REQUIRES_XML_DTD,
109  XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING,
110  /* Added in 1.95.7. */
111  XML_ERROR_UNBOUND_PREFIX,
112  /* Added in 1.95.8. */
113  XML_ERROR_UNDECLARING_PREFIX,
114  XML_ERROR_INCOMPLETE_PE,
115  XML_ERROR_XML_DECL,
116  XML_ERROR_TEXT_DECL,
117  XML_ERROR_PUBLICID,
118  XML_ERROR_SUSPENDED,
119  XML_ERROR_NOT_SUSPENDED,
120  XML_ERROR_ABORTED,
121  XML_ERROR_FINISHED,
122  XML_ERROR_SUSPEND_PE,
123  /* Added in 2.0. */
124  XML_ERROR_RESERVED_PREFIX_XML,
125  XML_ERROR_RESERVED_PREFIX_XMLNS,
126  XML_ERROR_RESERVED_NAMESPACE_URI,
127  /* Added in 2.2.1. */
128  XML_ERROR_INVALID_ARGUMENT,
129  /* Added in 2.3.0. */
130  XML_ERROR_NO_BUFFER,
131  /* Added in 2.4.0. */
132  XML_ERROR_AMPLIFICATION_LIMIT_BREACH
133};
134
135enum XML_Content_Type {
136  XML_CTYPE_EMPTY = 1,
137  XML_CTYPE_ANY,
138  XML_CTYPE_MIXED,
139  XML_CTYPE_NAME,
140  XML_CTYPE_CHOICE,
141  XML_CTYPE_SEQ
142};
143
144enum XML_Content_Quant {
145  XML_CQUANT_NONE,
146  XML_CQUANT_OPT,
147  XML_CQUANT_REP,
148  XML_CQUANT_PLUS
149};
150
151/* If type == XML_CTYPE_EMPTY or XML_CTYPE_ANY, then quant will be
152   XML_CQUANT_NONE, and the other fields will be zero or NULL.
153   If type == XML_CTYPE_MIXED, then quant will be NONE or REP and
154   numchildren will contain number of elements that may be mixed in
155   and children point to an array of XML_Content cells that will be
156   all of XML_CTYPE_NAME type with no quantification.
157
158   If type == XML_CTYPE_NAME, then the name points to the name, and
159   the numchildren field will be zero and children will be NULL. The
160   quant fields indicates any quantifiers placed on the name.
161
162   CHOICE and SEQ will have name NULL, the number of children in
163   numchildren and children will point, recursively, to an array
164   of XML_Content cells.
165
166   The EMPTY, ANY, and MIXED types will only occur at top level.
167*/
168
169typedef struct XML_cp XML_Content;
170
171struct XML_cp {
172  enum XML_Content_Type type;
173  enum XML_Content_Quant quant;
174  XML_Char *name;
175  unsigned int numchildren;
176  XML_Content *children;
177};
178
179/* This is called for an element declaration. See above for
180   description of the model argument. It's the user code's responsibility
181   to free model when finished with it. See XML_FreeContentModel.
182   There is no need to free the model from the handler, it can be kept
183   around and freed at a later stage.
184*/
185typedef void(XMLCALL *XML_ElementDeclHandler)(void *userData,
186                                              const XML_Char *name,
187                                              XML_Content *model);
188
189XMLPARSEAPI(void)
190XML_SetElementDeclHandler(XML_Parser parser, XML_ElementDeclHandler eldecl);
191
192/* The Attlist declaration handler is called for *each* attribute. So
193   a single Attlist declaration with multiple attributes declared will
194   generate multiple calls to this handler. The "default" parameter
195   may be NULL in the case of the "#IMPLIED" or "#REQUIRED"
196   keyword. The "isrequired" parameter will be true and the default
197   value will be NULL in the case of "#REQUIRED". If "isrequired" is
198   true and default is non-NULL, then this is a "#FIXED" default.
199*/
200typedef void(XMLCALL *XML_AttlistDeclHandler)(
201    void *userData, const XML_Char *elname, const XML_Char *attname,
202    const XML_Char *att_type, const XML_Char *dflt, int isrequired);
203
204XMLPARSEAPI(void)
205XML_SetAttlistDeclHandler(XML_Parser parser, XML_AttlistDeclHandler attdecl);
206
207/* The XML declaration handler is called for *both* XML declarations
208   and text declarations. The way to distinguish is that the version
209   parameter will be NULL for text declarations. The encoding
210   parameter may be NULL for XML declarations. The standalone
211   parameter will be -1, 0, or 1 indicating respectively that there
212   was no standalone parameter in the declaration, that it was given
213   as no, or that it was given as yes.
214*/
215typedef void(XMLCALL *XML_XmlDeclHandler)(void *userData,
216                                          const XML_Char *version,
217                                          const XML_Char *encoding,
218                                          int standalone);
219
220XMLPARSEAPI(void)
221XML_SetXmlDeclHandler(XML_Parser parser, XML_XmlDeclHandler xmldecl);
222
223typedef struct {
224  void *(*malloc_fcn)(size_t size);
225  void *(*realloc_fcn)(void *ptr, size_t size);
226  void (*free_fcn)(void *ptr);
227} XML_Memory_Handling_Suite;
228
229/* Constructs a new parser; encoding is the encoding specified by the
230   external protocol or NULL if there is none specified.
231*/
232XMLPARSEAPI(XML_Parser)
233XML_ParserCreate(const XML_Char *encoding);
234
235/* Constructs a new parser and namespace processor.  Element type
236   names and attribute names that belong to a namespace will be
237   expanded; unprefixed attribute names are never expanded; unprefixed
238   element type names are expanded only if there is a default
239   namespace. The expanded name is the concatenation of the namespace
240   URI, the namespace separator character, and the local part of the
241   name.  If the namespace separator is '\0' then the namespace URI
242   and the local part will be concatenated without any separator.
243   It is a programming error to use the separator '\0' with namespace
244   triplets (see XML_SetReturnNSTriplet).
245   If a namespace separator is chosen that can be part of a URI or
246   part of an XML name, splitting an expanded name back into its
247   1, 2 or 3 original parts on application level in the element handler
248   may end up vulnerable, so these are advised against;  sane choices for
249   a namespace separator are e.g. '\n' (line feed) and '|' (pipe).
250
251   Note that Expat does not validate namespace URIs (beyond encoding)
252   against RFC 3986 today (and is not required to do so with regard to
253   the XML 1.0 namespaces specification) but it may start doing that
254   in future releases.  Before that, an application using Expat must
255   be ready to receive namespace URIs containing non-URI characters.
256*/
257XMLPARSEAPI(XML_Parser)
258XML_ParserCreateNS(const XML_Char *encoding, XML_Char namespaceSeparator);
259
260/* Constructs a new parser using the memory management suite referred to
261   by memsuite. If memsuite is NULL, then use the standard library memory
262   suite. If namespaceSeparator is non-NULL it creates a parser with
263   namespace processing as described above. The character pointed at
264   will serve as the namespace separator.
265
266   All further memory operations used for the created parser will come from
267   the given suite.
268*/
269XMLPARSEAPI(XML_Parser)
270XML_ParserCreate_MM(const XML_Char *encoding,
271                    const XML_Memory_Handling_Suite *memsuite,
272                    const XML_Char *namespaceSeparator);
273
274/* Prepare a parser object to be reused.  This is particularly
275   valuable when memory allocation overhead is disproportionately high,
276   such as when a large number of small documnents need to be parsed.
277   All handlers are cleared from the parser, except for the
278   unknownEncodingHandler. The parser's external state is re-initialized
279   except for the values of ns and ns_triplets.
280
281   Added in Expat 1.95.3.
282*/
283XMLPARSEAPI(XML_Bool)
284XML_ParserReset(XML_Parser parser, const XML_Char *encoding);
285
286/* atts is array of name/value pairs, terminated by 0;
287   names and values are 0 terminated.
288*/
289typedef void(XMLCALL *XML_StartElementHandler)(void *userData,
290                                               const XML_Char *name,
291                                               const XML_Char **atts);
292
293typedef void(XMLCALL *XML_EndElementHandler)(void *userData,
294                                             const XML_Char *name);
295
296/* s is not 0 terminated. */
297typedef void(XMLCALL *XML_CharacterDataHandler)(void *userData,
298                                                const XML_Char *s, int len);
299
300/* target and data are 0 terminated */
301typedef void(XMLCALL *XML_ProcessingInstructionHandler)(void *userData,
302                                                        const XML_Char *target,
303                                                        const XML_Char *data);
304
305/* data is 0 terminated */
306typedef void(XMLCALL *XML_CommentHandler)(void *userData, const XML_Char *data);
307
308typedef void(XMLCALL *XML_StartCdataSectionHandler)(void *userData);
309typedef void(XMLCALL *XML_EndCdataSectionHandler)(void *userData);
310
311/* This is called for any characters in the XML document for which
312   there is no applicable handler.  This includes both characters that
313   are part of markup which is of a kind that is not reported
314   (comments, markup declarations), or characters that are part of a
315   construct which could be reported but for which no handler has been
316   supplied. The characters are passed exactly as they were in the XML
317   document except that they will be encoded in UTF-8 or UTF-16.
318   Line boundaries are not normalized. Note that a byte order mark
319   character is not passed to the default handler. There are no
320   guarantees about how characters are divided between calls to the
321   default handler: for example, a comment might be split between
322   multiple calls.
323*/
324typedef void(XMLCALL *XML_DefaultHandler)(void *userData, const XML_Char *s,
325                                          int len);
326
327/* This is called for the start of the DOCTYPE declaration, before
328   any DTD or internal subset is parsed.
329*/
330typedef void(XMLCALL *XML_StartDoctypeDeclHandler)(void *userData,
331                                                   const XML_Char *doctypeName,
332                                                   const XML_Char *sysid,
333                                                   const XML_Char *pubid,
334                                                   int has_internal_subset);
335
336/* This is called for the end of the DOCTYPE declaration when the
337   closing > is encountered, but after processing any external
338   subset.
339*/
340typedef void(XMLCALL *XML_EndDoctypeDeclHandler)(void *userData);
341
342/* This is called for entity declarations. The is_parameter_entity
343   argument will be non-zero if the entity is a parameter entity, zero
344   otherwise.
345
346   For internal entities (<!ENTITY foo "bar">), value will
347   be non-NULL and systemId, publicID, and notationName will be NULL.
348   The value string is NOT null-terminated; the length is provided in
349   the value_length argument. Since it is legal to have zero-length
350   values, do not use this argument to test for internal entities.
351
352   For external entities, value will be NULL and systemId will be
353   non-NULL. The publicId argument will be NULL unless a public
354   identifier was provided. The notationName argument will have a
355   non-NULL value only for unparsed entity declarations.
356
357   Note that is_parameter_entity can't be changed to XML_Bool, since
358   that would break binary compatibility.
359*/
360typedef void(XMLCALL *XML_EntityDeclHandler)(
361    void *userData, const XML_Char *entityName, int is_parameter_entity,
362    const XML_Char *value, int value_length, const XML_Char *base,
363    const XML_Char *systemId, const XML_Char *publicId,
364    const XML_Char *notationName);
365
366XMLPARSEAPI(void)
367XML_SetEntityDeclHandler(XML_Parser parser, XML_EntityDeclHandler handler);
368
369/* OBSOLETE -- OBSOLETE -- OBSOLETE
370   This handler has been superseded by the EntityDeclHandler above.
371   It is provided here for backward compatibility.
372
373   This is called for a declaration of an unparsed (NDATA) entity.
374   The base argument is whatever was set by XML_SetBase. The
375   entityName, systemId and notationName arguments will never be
376   NULL. The other arguments may be.
377*/
378typedef void(XMLCALL *XML_UnparsedEntityDeclHandler)(
379    void *userData, const XML_Char *entityName, const XML_Char *base,
380    const XML_Char *systemId, const XML_Char *publicId,
381    const XML_Char *notationName);
382
383/* This is called for a declaration of notation.  The base argument is
384   whatever was set by XML_SetBase. The notationName will never be
385   NULL.  The other arguments can be.
386*/
387typedef void(XMLCALL *XML_NotationDeclHandler)(void *userData,
388                                               const XML_Char *notationName,
389                                               const XML_Char *base,
390                                               const XML_Char *systemId,
391                                               const XML_Char *publicId);
392
393/* When namespace processing is enabled, these are called once for
394   each namespace declaration. The call to the start and end element
395   handlers occur between the calls to the start and end namespace
396   declaration handlers. For an xmlns attribute, prefix will be
397   NULL.  For an xmlns="" attribute, uri will be NULL.
398*/
399typedef void(XMLCALL *XML_StartNamespaceDeclHandler)(void *userData,
400                                                     const XML_Char *prefix,
401                                                     const XML_Char *uri);
402
403typedef void(XMLCALL *XML_EndNamespaceDeclHandler)(void *userData,
404                                                   const XML_Char *prefix);
405
406/* This is called if the document is not standalone, that is, it has an
407   external subset or a reference to a parameter entity, but does not
408   have standalone="yes". If this handler returns XML_STATUS_ERROR,
409   then processing will not continue, and the parser will return a
410   XML_ERROR_NOT_STANDALONE error.
411   If parameter entity parsing is enabled, then in addition to the
412   conditions above this handler will only be called if the referenced
413   entity was actually read.
414*/
415typedef int(XMLCALL *XML_NotStandaloneHandler)(void *userData);
416
417/* This is called for a reference to an external parsed general
418   entity.  The referenced entity is not automatically parsed.  The
419   application can parse it immediately or later using
420   XML_ExternalEntityParserCreate.
421
422   The parser argument is the parser parsing the entity containing the
423   reference; it can be passed as the parser argument to
424   XML_ExternalEntityParserCreate.  The systemId argument is the
425   system identifier as specified in the entity declaration; it will
426   not be NULL.
427
428   The base argument is the system identifier that should be used as
429   the base for resolving systemId if systemId was relative; this is
430   set by XML_SetBase; it may be NULL.
431
432   The publicId argument is the public identifier as specified in the
433   entity declaration, or NULL if none was specified; the whitespace
434   in the public identifier will have been normalized as required by
435   the XML spec.
436
437   The context argument specifies the parsing context in the format
438   expected by the context argument to XML_ExternalEntityParserCreate;
439   context is valid only until the handler returns, so if the
440   referenced entity is to be parsed later, it must be copied.
441   context is NULL only when the entity is a parameter entity.
442
443   The handler should return XML_STATUS_ERROR if processing should not
444   continue because of a fatal error in the handling of the external
445   entity.  In this case the calling parser will return an
446   XML_ERROR_EXTERNAL_ENTITY_HANDLING error.
447
448   Note that unlike other handlers the first argument is the parser,
449   not userData.
450*/
451typedef int(XMLCALL *XML_ExternalEntityRefHandler)(XML_Parser parser,
452                                                   const XML_Char *context,
453                                                   const XML_Char *base,
454                                                   const XML_Char *systemId,
455                                                   const XML_Char *publicId);
456
457/* This is called in two situations:
458   1) An entity reference is encountered for which no declaration
459      has been read *and* this is not an error.
460   2) An internal entity reference is read, but not expanded, because
461      XML_SetDefaultHandler has been called.
462   Note: skipped parameter entities in declarations and skipped general
463         entities in attribute values cannot be reported, because
464         the event would be out of sync with the reporting of the
465         declarations or attribute values
466*/
467typedef void(XMLCALL *XML_SkippedEntityHandler)(void *userData,
468                                                const XML_Char *entityName,
469                                                int is_parameter_entity);
470
471/* This structure is filled in by the XML_UnknownEncodingHandler to
472   provide information to the parser about encodings that are unknown
473   to the parser.
474
475   The map[b] member gives information about byte sequences whose
476   first byte is b.
477
478   If map[b] is c where c is >= 0, then b by itself encodes the
479   Unicode scalar value c.
480
481   If map[b] is -1, then the byte sequence is malformed.
482
483   If map[b] is -n, where n >= 2, then b is the first byte of an
484   n-byte sequence that encodes a single Unicode scalar value.
485
486   The data member will be passed as the first argument to the convert
487   function.
488
489   The convert function is used to convert multibyte sequences; s will
490   point to a n-byte sequence where map[(unsigned char)*s] == -n.  The
491   convert function must return the Unicode scalar value represented
492   by this byte sequence or -1 if the byte sequence is malformed.
493
494   The convert function may be NULL if the encoding is a single-byte
495   encoding, that is if map[b] >= -1 for all bytes b.
496
497   When the parser is finished with the encoding, then if release is
498   not NULL, it will call release passing it the data member; once
499   release has been called, the convert function will not be called
500   again.
501
502   Expat places certain restrictions on the encodings that are supported
503   using this mechanism.
504
505   1. Every ASCII character that can appear in a well-formed XML document,
506      other than the characters
507
508      $@\^`{}~
509
510      must be represented by a single byte, and that byte must be the
511      same byte that represents that character in ASCII.
512
513   2. No character may require more than 4 bytes to encode.
514
515   3. All characters encoded must have Unicode scalar values <=
516      0xFFFF, (i.e., characters that would be encoded by surrogates in
517      UTF-16 are  not allowed).  Note that this restriction doesn't
518      apply to the built-in support for UTF-8 and UTF-16.
519
520   4. No Unicode character may be encoded by more than one distinct
521      sequence of bytes.
522*/
523typedef struct {
524  int map[256];
525  void *data;
526  int(XMLCALL *convert)(void *data, const char *s);
527  void(XMLCALL *release)(void *data);
528} XML_Encoding;
529
530/* This is called for an encoding that is unknown to the parser.
531
532   The encodingHandlerData argument is that which was passed as the
533   second argument to XML_SetUnknownEncodingHandler.
534
535   The name argument gives the name of the encoding as specified in
536   the encoding declaration.
537
538   If the callback can provide information about the encoding, it must
539   fill in the XML_Encoding structure, and return XML_STATUS_OK.
540   Otherwise it must return XML_STATUS_ERROR.
541
542   If info does not describe a suitable encoding, then the parser will
543   return an XML_ERROR_UNKNOWN_ENCODING error.
544*/
545typedef int(XMLCALL *XML_UnknownEncodingHandler)(void *encodingHandlerData,
546                                                 const XML_Char *name,
547                                                 XML_Encoding *info);
548
549XMLPARSEAPI(void)
550XML_SetElementHandler(XML_Parser parser, XML_StartElementHandler start,
551                      XML_EndElementHandler end);
552
553XMLPARSEAPI(void)
554XML_SetStartElementHandler(XML_Parser parser, XML_StartElementHandler handler);
555
556XMLPARSEAPI(void)
557XML_SetEndElementHandler(XML_Parser parser, XML_EndElementHandler handler);
558
559XMLPARSEAPI(void)
560XML_SetCharacterDataHandler(XML_Parser parser,
561                            XML_CharacterDataHandler handler);
562
563XMLPARSEAPI(void)
564XML_SetProcessingInstructionHandler(XML_Parser parser,
565                                    XML_ProcessingInstructionHandler handler);
566XMLPARSEAPI(void)
567XML_SetCommentHandler(XML_Parser parser, XML_CommentHandler handler);
568
569XMLPARSEAPI(void)
570XML_SetCdataSectionHandler(XML_Parser parser,
571                           XML_StartCdataSectionHandler start,
572                           XML_EndCdataSectionHandler end);
573
574XMLPARSEAPI(void)
575XML_SetStartCdataSectionHandler(XML_Parser parser,
576                                XML_StartCdataSectionHandler start);
577
578XMLPARSEAPI(void)
579XML_SetEndCdataSectionHandler(XML_Parser parser,
580                              XML_EndCdataSectionHandler end);
581
582/* This sets the default handler and also inhibits expansion of
583   internal entities. These entity references will be passed to the
584   default handler, or to the skipped entity handler, if one is set.
585*/
586XMLPARSEAPI(void)
587XML_SetDefaultHandler(XML_Parser parser, XML_DefaultHandler handler);
588
589/* This sets the default handler but does not inhibit expansion of
590   internal entities.  The entity reference will not be passed to the
591   default handler.
592*/
593XMLPARSEAPI(void)
594XML_SetDefaultHandlerExpand(XML_Parser parser, XML_DefaultHandler handler);
595
596XMLPARSEAPI(void)
597XML_SetDoctypeDeclHandler(XML_Parser parser, XML_StartDoctypeDeclHandler start,
598                          XML_EndDoctypeDeclHandler end);
599
600XMLPARSEAPI(void)
601XML_SetStartDoctypeDeclHandler(XML_Parser parser,
602                               XML_StartDoctypeDeclHandler start);
603
604XMLPARSEAPI(void)
605XML_SetEndDoctypeDeclHandler(XML_Parser parser, XML_EndDoctypeDeclHandler end);
606
607XMLPARSEAPI(void)
608XML_SetUnparsedEntityDeclHandler(XML_Parser parser,
609                                 XML_UnparsedEntityDeclHandler handler);
610
611XMLPARSEAPI(void)
612XML_SetNotationDeclHandler(XML_Parser parser, XML_NotationDeclHandler handler);
613
614XMLPARSEAPI(void)
615XML_SetNamespaceDeclHandler(XML_Parser parser,
616                            XML_StartNamespaceDeclHandler start,
617                            XML_EndNamespaceDeclHandler end);
618
619XMLPARSEAPI(void)
620XML_SetStartNamespaceDeclHandler(XML_Parser parser,
621                                 XML_StartNamespaceDeclHandler start);
622
623XMLPARSEAPI(void)
624XML_SetEndNamespaceDeclHandler(XML_Parser parser,
625                               XML_EndNamespaceDeclHandler end);
626
627XMLPARSEAPI(void)
628XML_SetNotStandaloneHandler(XML_Parser parser,
629                            XML_NotStandaloneHandler handler);
630
631XMLPARSEAPI(void)
632XML_SetExternalEntityRefHandler(XML_Parser parser,
633                                XML_ExternalEntityRefHandler handler);
634
635/* If a non-NULL value for arg is specified here, then it will be
636   passed as the first argument to the external entity ref handler
637   instead of the parser object.
638*/
639XMLPARSEAPI(void)
640XML_SetExternalEntityRefHandlerArg(XML_Parser parser, void *arg);
641
642XMLPARSEAPI(void)
643XML_SetSkippedEntityHandler(XML_Parser parser,
644                            XML_SkippedEntityHandler handler);
645
646XMLPARSEAPI(void)
647XML_SetUnknownEncodingHandler(XML_Parser parser,
648                              XML_UnknownEncodingHandler handler,
649                              void *encodingHandlerData);
650
651/* This can be called within a handler for a start element, end
652   element, processing instruction or character data.  It causes the
653   corresponding markup to be passed to the default handler.
654*/
655XMLPARSEAPI(void)
656XML_DefaultCurrent(XML_Parser parser);
657
658/* If do_nst is non-zero, and namespace processing is in effect, and
659   a name has a prefix (i.e. an explicit namespace qualifier) then
660   that name is returned as a triplet in a single string separated by
661   the separator character specified when the parser was created: URI
662   + sep + local_name + sep + prefix.
663
664   If do_nst is zero, then namespace information is returned in the
665   default manner (URI + sep + local_name) whether or not the name
666   has a prefix.
667
668   Note: Calling XML_SetReturnNSTriplet after XML_Parse or
669     XML_ParseBuffer has no effect.
670*/
671
672XMLPARSEAPI(void)
673XML_SetReturnNSTriplet(XML_Parser parser, int do_nst);
674
675/* This value is passed as the userData argument to callbacks. */
676XMLPARSEAPI(void)
677XML_SetUserData(XML_Parser parser, void *userData);
678
679/* Returns the last value set by XML_SetUserData or NULL. */
680#define XML_GetUserData(parser) (*(void **)(parser))
681
682/* This is equivalent to supplying an encoding argument to
683   XML_ParserCreate. On success XML_SetEncoding returns non-zero,
684   zero otherwise.
685   Note: Calling XML_SetEncoding after XML_Parse or XML_ParseBuffer
686     has no effect and returns XML_STATUS_ERROR.
687*/
688XMLPARSEAPI(enum XML_Status)
689XML_SetEncoding(XML_Parser parser, const XML_Char *encoding);
690
691/* If this function is called, then the parser will be passed as the
692   first argument to callbacks instead of userData.  The userData will
693   still be accessible using XML_GetUserData.
694*/
695XMLPARSEAPI(void)
696XML_UseParserAsHandlerArg(XML_Parser parser);
697
698/* If useDTD == XML_TRUE is passed to this function, then the parser
699   will assume that there is an external subset, even if none is
700   specified in the document. In such a case the parser will call the
701   externalEntityRefHandler with a value of NULL for the systemId
702   argument (the publicId and context arguments will be NULL as well).
703   Note: For the purpose of checking WFC: Entity Declared, passing
704     useDTD == XML_TRUE will make the parser behave as if the document
705     had a DTD with an external subset.
706   Note: If this function is called, then this must be done before
707     the first call to XML_Parse or XML_ParseBuffer, since it will
708     have no effect after that.  Returns
709     XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING.
710   Note: If the document does not have a DOCTYPE declaration at all,
711     then startDoctypeDeclHandler and endDoctypeDeclHandler will not
712     be called, despite an external subset being parsed.
713   Note: If XML_DTD is not defined when Expat is compiled, returns
714     XML_ERROR_FEATURE_REQUIRES_XML_DTD.
715   Note: If parser == NULL, returns XML_ERROR_INVALID_ARGUMENT.
716*/
717XMLPARSEAPI(enum XML_Error)
718XML_UseForeignDTD(XML_Parser parser, XML_Bool useDTD);
719
720/* Sets the base to be used for resolving relative URIs in system
721   identifiers in declarations.  Resolving relative identifiers is
722   left to the application: this value will be passed through as the
723   base argument to the XML_ExternalEntityRefHandler,
724   XML_NotationDeclHandler and XML_UnparsedEntityDeclHandler. The base
725   argument will be copied.  Returns XML_STATUS_ERROR if out of memory,
726   XML_STATUS_OK otherwise.
727*/
728XMLPARSEAPI(enum XML_Status)
729XML_SetBase(XML_Parser parser, const XML_Char *base);
730
731XMLPARSEAPI(const XML_Char *)
732XML_GetBase(XML_Parser parser);
733
734/* Returns the number of the attribute/value pairs passed in last call
735   to the XML_StartElementHandler that were specified in the start-tag
736   rather than defaulted. Each attribute/value pair counts as 2; thus
737   this corresponds to an index into the atts array passed to the
738   XML_StartElementHandler.  Returns -1 if parser == NULL.
739*/
740XMLPARSEAPI(int)
741XML_GetSpecifiedAttributeCount(XML_Parser parser);
742
743/* Returns the index of the ID attribute passed in the last call to
744   XML_StartElementHandler, or -1 if there is no ID attribute or
745   parser == NULL.  Each attribute/value pair counts as 2; thus this
746   corresponds to an index into the atts array passed to the
747   XML_StartElementHandler.
748*/
749XMLPARSEAPI(int)
750XML_GetIdAttributeIndex(XML_Parser parser);
751
752#ifdef XML_ATTR_INFO
753/* Source file byte offsets for the start and end of attribute names and values.
754   The value indices are exclusive of surrounding quotes; thus in a UTF-8 source
755   file an attribute value of "blah" will yield:
756   info->valueEnd - info->valueStart = 4 bytes.
757*/
758typedef struct {
759  XML_Index nameStart;  /* Offset to beginning of the attribute name. */
760  XML_Index nameEnd;    /* Offset after the attribute name's last byte. */
761  XML_Index valueStart; /* Offset to beginning of the attribute value. */
762  XML_Index valueEnd;   /* Offset after the attribute value's last byte. */
763} XML_AttrInfo;
764
765/* Returns an array of XML_AttrInfo structures for the attribute/value pairs
766   passed in last call to the XML_StartElementHandler that were specified
767   in the start-tag rather than defaulted. Each attribute/value pair counts
768   as 1; thus the number of entries in the array is
769   XML_GetSpecifiedAttributeCount(parser) / 2.
770*/
771XMLPARSEAPI(const XML_AttrInfo *)
772XML_GetAttributeInfo(XML_Parser parser);
773#endif
774
775/* Parses some input. Returns XML_STATUS_ERROR if a fatal error is
776   detected.  The last call to XML_Parse must have isFinal true; len
777   may be zero for this call (or any other).
778
779   Though the return values for these functions has always been
780   described as a Boolean value, the implementation, at least for the
781   1.95.x series, has always returned exactly one of the XML_Status
782   values.
783*/
784XMLPARSEAPI(enum XML_Status)
785XML_Parse(XML_Parser parser, const char *s, int len, int isFinal);
786
787XMLPARSEAPI(void *)
788XML_GetBuffer(XML_Parser parser, int len);
789
790XMLPARSEAPI(enum XML_Status)
791XML_ParseBuffer(XML_Parser parser, int len, int isFinal);
792
793/* Stops parsing, causing XML_Parse() or XML_ParseBuffer() to return.
794   Must be called from within a call-back handler, except when aborting
795   (resumable = 0) an already suspended parser. Some call-backs may
796   still follow because they would otherwise get lost. Examples:
797   - endElementHandler() for empty elements when stopped in
798     startElementHandler(),
799   - endNameSpaceDeclHandler() when stopped in endElementHandler(),
800   and possibly others.
801
802   Can be called from most handlers, including DTD related call-backs,
803   except when parsing an external parameter entity and resumable != 0.
804   Returns XML_STATUS_OK when successful, XML_STATUS_ERROR otherwise.
805   Possible error codes:
806   - XML_ERROR_SUSPENDED: when suspending an already suspended parser.
807   - XML_ERROR_FINISHED: when the parser has already finished.
808   - XML_ERROR_SUSPEND_PE: when suspending while parsing an external PE.
809
810   When resumable != 0 (true) then parsing is suspended, that is,
811   XML_Parse() and XML_ParseBuffer() return XML_STATUS_SUSPENDED.
812   Otherwise, parsing is aborted, that is, XML_Parse() and XML_ParseBuffer()
813   return XML_STATUS_ERROR with error code XML_ERROR_ABORTED.
814
815   *Note*:
816   This will be applied to the current parser instance only, that is, if
817   there is a parent parser then it will continue parsing when the
818   externalEntityRefHandler() returns. It is up to the implementation of
819   the externalEntityRefHandler() to call XML_StopParser() on the parent
820   parser (recursively), if one wants to stop parsing altogether.
821
822   When suspended, parsing can be resumed by calling XML_ResumeParser().
823*/
824XMLPARSEAPI(enum XML_Status)
825XML_StopParser(XML_Parser parser, XML_Bool resumable);
826
827/* Resumes parsing after it has been suspended with XML_StopParser().
828   Must not be called from within a handler call-back. Returns same
829   status codes as XML_Parse() or XML_ParseBuffer().
830   Additional error code XML_ERROR_NOT_SUSPENDED possible.
831
832   *Note*:
833   This must be called on the most deeply nested child parser instance
834   first, and on its parent parser only after the child parser has finished,
835   to be applied recursively until the document entity's parser is restarted.
836   That is, the parent parser will not resume by itself and it is up to the
837   application to call XML_ResumeParser() on it at the appropriate moment.
838*/
839XMLPARSEAPI(enum XML_Status)
840XML_ResumeParser(XML_Parser parser);
841
842enum XML_Parsing { XML_INITIALIZED, XML_PARSING, XML_FINISHED, XML_SUSPENDED };
843
844typedef struct {
845  enum XML_Parsing parsing;
846  XML_Bool finalBuffer;
847} XML_ParsingStatus;
848
849/* Returns status of parser with respect to being initialized, parsing,
850   finished, or suspended and processing the final buffer.
851   XXX XML_Parse() and XML_ParseBuffer() should return XML_ParsingStatus,
852   XXX with XML_FINISHED_OK or XML_FINISHED_ERROR replacing XML_FINISHED
853*/
854XMLPARSEAPI(void)
855XML_GetParsingStatus(XML_Parser parser, XML_ParsingStatus *status);
856
857/* Creates an XML_Parser object that can parse an external general
858   entity; context is a '\0'-terminated string specifying the parse
859   context; encoding is a '\0'-terminated string giving the name of
860   the externally specified encoding, or NULL if there is no
861   externally specified encoding.  The context string consists of a
862   sequence of tokens separated by formfeeds (\f); a token consisting
863   of a name specifies that the general entity of the name is open; a
864   token of the form prefix=uri specifies the namespace for a
865   particular prefix; a token of the form =uri specifies the default
866   namespace.  This can be called at any point after the first call to
867   an ExternalEntityRefHandler so longer as the parser has not yet
868   been freed.  The new parser is completely independent and may
869   safely be used in a separate thread.  The handlers and userData are
870   initialized from the parser argument.  Returns NULL if out of memory.
871   Otherwise returns a new XML_Parser object.
872*/
873XMLPARSEAPI(XML_Parser)
874XML_ExternalEntityParserCreate(XML_Parser parser, const XML_Char *context,
875                               const XML_Char *encoding);
876
877enum XML_ParamEntityParsing {
878  XML_PARAM_ENTITY_PARSING_NEVER,
879  XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE,
880  XML_PARAM_ENTITY_PARSING_ALWAYS
881};
882
883/* Controls parsing of parameter entities (including the external DTD
884   subset). If parsing of parameter entities is enabled, then
885   references to external parameter entities (including the external
886   DTD subset) will be passed to the handler set with
887   XML_SetExternalEntityRefHandler.  The context passed will be 0.
888
889   Unlike external general entities, external parameter entities can
890   only be parsed synchronously.  If the external parameter entity is
891   to be parsed, it must be parsed during the call to the external
892   entity ref handler: the complete sequence of
893   XML_ExternalEntityParserCreate, XML_Parse/XML_ParseBuffer and
894   XML_ParserFree calls must be made during this call.  After
895   XML_ExternalEntityParserCreate has been called to create the parser
896   for the external parameter entity (context must be 0 for this
897   call), it is illegal to make any calls on the old parser until
898   XML_ParserFree has been called on the newly created parser.
899   If the library has been compiled without support for parameter
900   entity parsing (ie without XML_DTD being defined), then
901   XML_SetParamEntityParsing will return 0 if parsing of parameter
902   entities is requested; otherwise it will return non-zero.
903   Note: If XML_SetParamEntityParsing is called after XML_Parse or
904      XML_ParseBuffer, then it has no effect and will always return 0.
905   Note: If parser == NULL, the function will do nothing and return 0.
906*/
907XMLPARSEAPI(int)
908XML_SetParamEntityParsing(XML_Parser parser,
909                          enum XML_ParamEntityParsing parsing);
910
911/* Sets the hash salt to use for internal hash calculations.
912   Helps in preventing DoS attacks based on predicting hash
913   function behavior. This must be called before parsing is started.
914   Returns 1 if successful, 0 when called after parsing has started.
915   Note: If parser == NULL, the function will do nothing and return 0.
916*/
917XMLPARSEAPI(int)
918XML_SetHashSalt(XML_Parser parser, unsigned long hash_salt);
919
920/* If XML_Parse or XML_ParseBuffer have returned XML_STATUS_ERROR, then
921   XML_GetErrorCode returns information about the error.
922*/
923XMLPARSEAPI(enum XML_Error)
924XML_GetErrorCode(XML_Parser parser);
925
926/* These functions return information about the current parse
927   location.  They may be called from any callback called to report
928   some parse event; in this case the location is the location of the
929   first of the sequence of characters that generated the event.  When
930   called from callbacks generated by declarations in the document
931   prologue, the location identified isn't as neatly defined, but will
932   be within the relevant markup.  When called outside of the callback
933   functions, the position indicated will be just past the last parse
934   event (regardless of whether there was an associated callback).
935
936   They may also be called after returning from a call to XML_Parse
937   or XML_ParseBuffer.  If the return value is XML_STATUS_ERROR then
938   the location is the location of the character at which the error
939   was detected; otherwise the location is the location of the last
940   parse event, as described above.
941
942   Note: XML_GetCurrentLineNumber and XML_GetCurrentColumnNumber
943   return 0 to indicate an error.
944   Note: XML_GetCurrentByteIndex returns -1 to indicate an error.
945*/
946XMLPARSEAPI(XML_Size) XML_GetCurrentLineNumber(XML_Parser parser);
947XMLPARSEAPI(XML_Size) XML_GetCurrentColumnNumber(XML_Parser parser);
948XMLPARSEAPI(XML_Index) XML_GetCurrentByteIndex(XML_Parser parser);
949
950/* Return the number of bytes in the current event.
951   Returns 0 if the event is in an internal entity.
952*/
953XMLPARSEAPI(int)
954XML_GetCurrentByteCount(XML_Parser parser);
955
956/* If XML_CONTEXT_BYTES is >=1, returns the input buffer, sets
957   the integer pointed to by offset to the offset within this buffer
958   of the current parse position, and sets the integer pointed to by size
959   to the size of this buffer (the number of input bytes). Otherwise
960   returns a NULL pointer. Also returns a NULL pointer if a parse isn't
961   active.
962
963   NOTE: The character pointer returned should not be used outside
964   the handler that makes the call.
965*/
966XMLPARSEAPI(const char *)
967XML_GetInputContext(XML_Parser parser, int *offset, int *size);
968
969/* For backwards compatibility with previous versions. */
970#define XML_GetErrorLineNumber XML_GetCurrentLineNumber
971#define XML_GetErrorColumnNumber XML_GetCurrentColumnNumber
972#define XML_GetErrorByteIndex XML_GetCurrentByteIndex
973
974/* Frees the content model passed to the element declaration handler */
975XMLPARSEAPI(void)
976XML_FreeContentModel(XML_Parser parser, XML_Content *model);
977
978/* Exposing the memory handling functions used in Expat */
979XMLPARSEAPI(void *)
980XML_ATTR_MALLOC
981XML_ATTR_ALLOC_SIZE(2)
982XML_MemMalloc(XML_Parser parser, size_t size);
983
984XMLPARSEAPI(void *)
985XML_ATTR_ALLOC_SIZE(3)
986XML_MemRealloc(XML_Parser parser, void *ptr, size_t size);
987
988XMLPARSEAPI(void)
989XML_MemFree(XML_Parser parser, void *ptr);
990
991/* Frees memory used by the parser. */
992XMLPARSEAPI(void)
993XML_ParserFree(XML_Parser parser);
994
995/* Returns a string describing the error. */
996XMLPARSEAPI(const XML_LChar *)
997XML_ErrorString(enum XML_Error code);
998
999/* Return a string containing the version number of this expat */
1000XMLPARSEAPI(const XML_LChar *)
1001XML_ExpatVersion(void);
1002
1003typedef struct {
1004  int major;
1005  int minor;
1006  int micro;
1007} XML_Expat_Version;
1008
1009/* Return an XML_Expat_Version structure containing numeric version
1010   number information for this version of expat.
1011*/
1012XMLPARSEAPI(XML_Expat_Version)
1013XML_ExpatVersionInfo(void);
1014
1015/* Added in Expat 1.95.5. */
1016enum XML_FeatureEnum {
1017  XML_FEATURE_END = 0,
1018  XML_FEATURE_UNICODE,
1019  XML_FEATURE_UNICODE_WCHAR_T,
1020  XML_FEATURE_DTD,
1021  XML_FEATURE_CONTEXT_BYTES,
1022  XML_FEATURE_MIN_SIZE,
1023  XML_FEATURE_SIZEOF_XML_CHAR,
1024  XML_FEATURE_SIZEOF_XML_LCHAR,
1025  XML_FEATURE_NS,
1026  XML_FEATURE_LARGE_SIZE,
1027  XML_FEATURE_ATTR_INFO,
1028  /* Added in Expat 2.4.0. */
1029  XML_FEATURE_BILLION_LAUGHS_ATTACK_PROTECTION_MAXIMUM_AMPLIFICATION_DEFAULT,
1030  XML_FEATURE_BILLION_LAUGHS_ATTACK_PROTECTION_ACTIVATION_THRESHOLD_DEFAULT,
1031  /* Added in Expat 2.6.0. */
1032  XML_FEATURE_GE
1033  /* Additional features must be added to the end of this enum. */
1034};
1035
1036typedef struct {
1037  enum XML_FeatureEnum feature;
1038  const XML_LChar *name;
1039  long int value;
1040} XML_Feature;
1041
1042XMLPARSEAPI(const XML_Feature *)
1043XML_GetFeatureList(void);
1044
1045#if XML_GE == 1
1046/* Added in Expat 2.4.0 for XML_DTD defined and
1047 * added in Expat 2.6.0 for XML_GE == 1. */
1048XMLPARSEAPI(XML_Bool)
1049XML_SetBillionLaughsAttackProtectionMaximumAmplification(
1050    XML_Parser parser, float maximumAmplificationFactor);
1051
1052/* Added in Expat 2.4.0 for XML_DTD defined and
1053 * added in Expat 2.6.0 for XML_GE == 1. */
1054XMLPARSEAPI(XML_Bool)
1055XML_SetBillionLaughsAttackProtectionActivationThreshold(
1056    XML_Parser parser, unsigned long long activationThresholdBytes);
1057#endif
1058
1059/* Added in Expat 2.6.0. */
1060XMLPARSEAPI(XML_Bool)
1061XML_SetReparseDeferralEnabled(XML_Parser parser, XML_Bool enabled);
1062
1063/* Expat follows the semantic versioning convention.
1064   See https://semver.org
1065*/
1066#define XML_MAJOR_VERSION 2
1067#define XML_MINOR_VERSION 6
1068#define XML_MICRO_VERSION 0
1069
1070#ifdef __cplusplus
1071}
1072#endif
1073
1074#endif /* not Expat_INCLUDED */
1075