contrib/src/xml/expat/xmlparse/xmlparse.h

   1 /*
   2 Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd
   3 See the file copying.txt for copying permission.
   4 */
   5
   6 #ifndef XmlParse_INCLUDED
   7 #define XmlParse_INCLUDED 1
   8
   9 #ifdef __cplusplus
  10 extern "C" {
  11 #endif
  12
  13 #ifndef XMLPARSEAPI
  14 #define XMLPARSEAPI /* as nothing */
  15 #endif
  16
  17 typedef void *XML_Parser;
  18
  19 #ifdef XML_UNICODE_WCHAR_T
  20
  21 /* XML_UNICODE_WCHAR_T will work only if sizeof(wchar_t) == 2 and wchar_t
  22 uses Unicode. */
  23 /* Information is UTF-16 encoded as wchar_ts */
  24
  25 #ifndef XML_UNICODE
  26 #define XML_UNICODE
  27 #endif
  28
  29 #include <stddef.h>
  30 typedef wchar_t XML_Char;
  31 typedef wchar_t XML_LChar;
  32
  33 #else /* not XML_UNICODE_WCHAR_T */
  34
  35 #ifdef XML_UNICODE
  36
  37 /* Information is UTF-16 encoded as unsigned shorts */
  38 typedef unsigned short XML_Char;
  39 typedef char XML_LChar;
  40
  41 #else /* not XML_UNICODE */
  42
  43 /* Information is UTF-8 encoded. */
  44 typedef char XML_Char;
  45 typedef char XML_LChar;
  46
  47 #endif /* not XML_UNICODE */
  48
  49 #endif /* not XML_UNICODE_WCHAR_T */
  50
  51
  52 /* Constructs a new parser; encoding is the encoding specified by the external
  53 protocol or null if there is none specified. */
  54
  55 XML_Parser XMLPARSEAPI
  56 XML_ParserCreate(const XML_Char *encoding);
  57
  58 /* Constructs a new parser and namespace processor.  Element type names
  59 and attribute names that belong to a namespace will be expanded;
  60 unprefixed attribute names are never expanded; unprefixed element type
  61 names are expanded only if there is a default namespace. The expanded
  62 name is the concatenation of the namespace URI, the namespace separator character,
  63 and the local part of the name.  If the namespace separator is '\0' then
  64 the namespace URI and the local part will be concatenated without any
  65 separator.  When a namespace is not declared, the name and prefix will be
  66 passed through without expansion. */
  67
  68 XML_Parser XMLPARSEAPI
  69 XML_ParserCreateNS(const XML_Char *encoding, XML_Char namespaceSeparator);
  70
  71
  72 /* atts is array of name/value pairs, terminated by 0;
  73    names and values are 0 terminated. */
  74
  75 typedef void (*XML_StartElementHandler)(void *userData,
  76                                         const XML_Char *name,
  77                                         const XML_Char **atts);
  78
  79 typedef void (*XML_EndElementHandler)(void *userData,
  80                                       const XML_Char *name);
  81
  82 /* s is not 0 terminated. */
  83 typedef void (*XML_CharacterDataHandler)(void *userData,
  84                                          const XML_Char *s,
  85                                          int len);
  86
  87 /* target and data are 0 terminated */
  88 typedef void (*XML_ProcessingInstructionHandler)(void *userData,
  89                                                  const XML_Char *target,
  90                                                  const XML_Char *data);
  91
  92 /* data is 0 terminated */
  93 typedef void (*XML_CommentHandler)(void *userData, const XML_Char *data);
  94
  95 typedef void (*XML_StartCdataSectionHandler)(void *userData);
  96 typedef void (*XML_EndCdataSectionHandler)(void *userData);
  97
  98 /* This is called for any characters in the XML document for
  99 which there is no applicable handler.  This includes both
 100 characters that are part of markup which is of a kind that is
 101 not reported (comments, markup declarations), or characters
 102 that are part of a construct which could be reported but
 103 for which no handler has been supplied. The characters are passed
 104 exactly as they were in the XML document except that
 105 they will be encoded in UTF-8.  Line boundaries are not normalized.
 106 Note that a byte order mark character is not passed to the default handler.
 107 There are no guarantees about how characters are divided between calls
 108 to the default handler: for example, a comment might be split between
 109 multiple calls. */
 110
 111 typedef void (*XML_DefaultHandler)(void *userData,
 112                                    const XML_Char *s,
 113                                    int len);
 114
 115 /* This is called for the start of the DOCTYPE declaration when the
 116 name of the DOCTYPE is encountered. */
 117 typedef void (*XML_StartDoctypeDeclHandler)(void *userData,
 118                                             const XML_Char *doctypeName);
 119
 120 /* This is called for the start of the DOCTYPE declaration when the
 121 closing > is encountered, but after processing any external subset. */
 122 typedef void (*XML_EndDoctypeDeclHandler)(void *userData);
 123
 124 /* This is called for a declaration of an unparsed (NDATA)
 125 entity.  The base argument is whatever was set by XML_SetBase.
 126 The entityName, systemId and notationName arguments will never be null.
 127 The other arguments may be. */
 128
 129 typedef void (*XML_UnparsedEntityDeclHandler)(void *userData,
 130                                               const XML_Char *entityName,
 131                                               const XML_Char *base,
 132                                               const XML_Char *systemId,
 133                                               const XML_Char *publicId,
 134                                               const XML_Char *notationName);
 135
 136 /* This is called for a declaration of notation.
 137 The base argument is whatever was set by XML_SetBase.
 138 The notationName will never be null.  The other arguments can be. */
 139
 140 typedef void (*XML_NotationDeclHandler)(void *userData,
 141                                         const XML_Char *notationName,
 142                                         const XML_Char *base,
 143                                         const XML_Char *systemId,
 144                                         const XML_Char *publicId);
 145
 146 typedef void (*XML_ExternalParsedEntityDeclHandler)(void *userData,
 147                                                     const XML_Char *entityName,
 148                                                     const XML_Char *base,
 149                                                     const XML_Char *systemId,
 150                                                     const XML_Char *publicId);
 151
 152 typedef void (*XML_InternalParsedEntityDeclHandler)(void *userData,
 153                                                     const XML_Char *entityName,
 154                                                     const XML_Char *replacementText,
 155                                                     int replacementTextLength);
 156
 157 /* When namespace processing is enabled, these are called once for
 158 each namespace declaration. The call to the start and end element
 159 handlers occur between the calls to the start and end namespace
 160 declaration handlers. For an xmlns attribute, prefix will be null.
 161 For an xmlns="" attribute, uri will be null. */
 162
 163 typedef void (*XML_StartNamespaceDeclHandler)(void *userData,
 164                                               const XML_Char *prefix,
 165                                               const XML_Char *uri);
 166
 167 typedef void (*XML_EndNamespaceDeclHandler)(void *userData,
 168                                             const XML_Char *prefix);
 169
 170 /* This is called if the document is not standalone (it has an
 171 external subset or a reference to a parameter entity, but does not
 172 have standalone="yes"). If this handler returns 0, then processing
 173 will not continue, and the parser will return a
 174 XML_ERROR_NOT_STANDALONE error. */
 175
 176 typedef int (*XML_NotStandaloneHandler)(void *userData);
 177
 178 /* This is called for a reference to an external parsed general entity.
 179 The referenced entity is not automatically parsed.
 180 The application can parse it immediately or later using
 181 XML_ExternalEntityParserCreate.
 182 The parser argument is the parser parsing the entity containing the reference;
 183 it can be passed as the parser argument to XML_ExternalEntityParserCreate.
 184 The systemId argument is the system identifier as specified in the entity declaration;
 185 it will not be null.
 186 The base argument is the system identifier that should be used as the base for
 187 resolving systemId if systemId was relative; this is set by XML_SetBase;
 188 it may be null.
 189 The publicId argument is the public identifier as specified in the entity declaration,
 190 or null if none was specified; the whitespace in the public identifier
 191 will have been normalized as required by the XML spec.
 192 The context argument specifies the parsing context in the format
 193 expected by the context argument to
 194 XML_ExternalEntityParserCreate; context is valid only until the handler
 195 returns, so if the referenced entity is to be parsed later, it must be copied.
 196 The handler should return 0 if processing should not continue because of
 197 a fatal error in the handling of the external entity.
 198 In this case the calling parser will return an XML_ERROR_EXTERNAL_ENTITY_HANDLING
 199 error.
 200 Note that unlike other handlers the first argument is the parser, not userData. */
 201
 202 typedef int (*XML_ExternalEntityRefHandler)(XML_Parser parser,
 203                                             const XML_Char *context,
 204                                             const XML_Char *base,
 205                                             const XML_Char *systemId,
 206                                             const XML_Char *publicId);
 207
 208 /* This structure is filled in by the XML_UnknownEncodingHandler
 209 to provide information to the parser about encodings that are unknown
 210 to the parser.
 211 The map[b] member gives information about byte sequences
 212 whose first byte is b.
 213 If map[b] is c where c is >= 0, then b by itself encodes the Unicode scalar value c.
 214 If map[b] is -1, then the byte sequence is malformed.
 215 If map[b] is -n, where n >= 2, then b is the first byte of an n-byte
 216 sequence that encodes a single Unicode scalar value.
 217 The data member will be passed as the first argument to the convert function.
 218 The convert function is used to convert multibyte sequences;
 219 s will point to a n-byte sequence where map[(unsigned char)*s] == -n.
 220 The convert function must return the Unicode scalar value
 221 represented by this byte sequence or -1 if the byte sequence is malformed.
 222 The convert function may be null if the encoding is a single-byte encoding,
 223 that is if map[b] >= -1 for all bytes b.
 224 When the parser is finished with the encoding, then if release is not null,
 225 it will call release passing it the data member;
 226 once release has been called, the convert function will not be called again.
 227
 228 Expat places certain restrictions on the encodings that are supported
 229 using this mechanism.
 230
 231 1. Every ASCII character that can appear in a well-formed XML document,
 232 other than the characters
 233
 234   $@\^`{}~
 235
 236 must be represented by a single byte, and that byte must be the
 237 same byte that represents that character in ASCII.
 238
 239 2. No character may require more than 4 bytes to encode.
 240
 241 3. All characters encoded must have Unicode scalar values <= 0xFFFF,
 242 (ie characters that would be encoded by surrogates in UTF-16
 243 are  not allowed).  Note that this restriction doesn't apply to
 244 the built-in support for UTF-8 and UTF-16.
 245
 246 4. No Unicode character may be encoded by more than one distinct sequence
 247 of bytes. */
 248
 249 typedef struct {
 250   int map[256];
 251   void *data;
 252   int (*convert)(void *data, const char *s);
 253   void (*release)(void *data);
 254 } XML_Encoding;
 255
 256 /* This is called for an encoding that is unknown to the parser.
 257 The encodingHandlerData argument is that which was passed as the
 258 second argument to XML_SetUnknownEncodingHandler.
 259 The name argument gives the name of the encoding as specified in
 260 the encoding declaration.
 261 If the callback can provide information about the encoding,
 262 it must fill in the XML_Encoding structure, and return 1.
 263 Otherwise it must return 0.
 264 If info does not describe a suitable encoding,
 265 then the parser will return an XML_UNKNOWN_ENCODING error. */
 266
 267 typedef int (*XML_UnknownEncodingHandler)(void *encodingHandlerData,
 268                                           const XML_Char *name,
 269                                           XML_Encoding *info);
 270
 271 void XMLPARSEAPI
 272 XML_SetElementHandler(XML_Parser parser,
 273                       XML_StartElementHandler start,
 274                       XML_EndElementHandler end);
 275
 276 void XMLPARSEAPI
 277 XML_SetCharacterDataHandler(XML_Parser parser,
 278                             XML_CharacterDataHandler handler);
 279
 280 void XMLPARSEAPI
 281 XML_SetProcessingInstructionHandler(XML_Parser parser,
 282                                     XML_ProcessingInstructionHandler handler);
 283 void XMLPARSEAPI
 284 XML_SetCommentHandler(XML_Parser parser,
 285                       XML_CommentHandler handler);
 286
 287 void XMLPARSEAPI
 288 XML_SetCdataSectionHandler(XML_Parser parser,
 289                            XML_StartCdataSectionHandler start,
 290                            XML_EndCdataSectionHandler end);
 291
 292 /* This sets the default handler and also inhibits expansion of internal entities.
 293 The entity reference will be passed to the default handler. */
 294
 295 void XMLPARSEAPI
 296 XML_SetDefaultHandler(XML_Parser parser,
 297                       XML_DefaultHandler handler);
 298
 299 /* This sets the default handler but does not inhibit expansion of internal entities.
 300 The entity reference will not be passed to the default handler. */
 301
 302 void XMLPARSEAPI
 303 XML_SetDefaultHandlerExpand(XML_Parser parser,
 304                             XML_DefaultHandler handler);
 305
 306 void XMLPARSEAPI
 307 XML_SetDoctypeDeclHandler(XML_Parser parser,
 308                           XML_StartDoctypeDeclHandler start,
 309                           XML_EndDoctypeDeclHandler end);
 310
 311 void XMLPARSEAPI
 312 XML_SetUnparsedEntityDeclHandler(XML_Parser parser,
 313                                  XML_UnparsedEntityDeclHandler handler);
 314
 315 void XMLPARSEAPI
 316 XML_SetNotationDeclHandler(XML_Parser parser,
 317                            XML_NotationDeclHandler handler);
 318
 319 void XMLPARSEAPI
 320 XML_SetExternalParsedEntityDeclHandler(XML_Parser parser,
 321                                        XML_ExternalParsedEntityDeclHandler handler);
 322
 323 void XMLPARSEAPI
 324 XML_SetInternalParsedEntityDeclHandler(XML_Parser parser,
 325                                        XML_InternalParsedEntityDeclHandler handler);
 326
 327 void XMLPARSEAPI
 328 XML_SetNamespaceDeclHandler(XML_Parser parser,
 329                             XML_StartNamespaceDeclHandler start,
 330                             XML_EndNamespaceDeclHandler end);
 331
 332 void XMLPARSEAPI
 333 XML_SetNotStandaloneHandler(XML_Parser parser,
 334                             XML_NotStandaloneHandler handler);
 335
 336 void XMLPARSEAPI
 337 XML_SetExternalEntityRefHandler(XML_Parser parser,
 338                                 XML_ExternalEntityRefHandler handler);
 339
 340 /* If a non-null value for arg is specified here, then it will be passed
 341 as the first argument to the external entity ref handler instead
 342 of the parser object. */
 343 void XMLPARSEAPI
 344 XML_SetExternalEntityRefHandlerArg(XML_Parser, void *arg);
 345
 346 void XMLPARSEAPI
 347 XML_SetUnknownEncodingHandler(XML_Parser parser,
 348                               XML_UnknownEncodingHandler handler,
 349                               void *encodingHandlerData);
 350
 351 /* This can be called within a handler for a start element, end element,
 352 processing instruction or character data.  It causes the corresponding
 353 markup to be passed to the default handler. */
 354 void XMLPARSEAPI XML_DefaultCurrent(XML_Parser parser);
 355
 356 /* This value is passed as the userData argument to callbacks. */
 357 void XMLPARSEAPI
 358 XML_SetUserData(XML_Parser parser, void *userData);
 359
 360 /* Returns the last value set by XML_SetUserData or null. */
 361 #define XML_GetUserData(parser) (*(void **)(parser))
 362
 363 /* This is equivalent to supplying an encoding argument
 364 to XML_ParserCreate. It must not be called after XML_Parse
 365 or XML_ParseBuffer. */
 366
 367 int XMLPARSEAPI
 368 XML_SetEncoding(XML_Parser parser, const XML_Char *encoding);
 369
 370 /* If this function is called, then the parser will be passed
 371 as the first argument to callbacks instead of userData.
 372 The userData will still be accessible using XML_GetUserData. */
 373
 374 void XMLPARSEAPI
 375 XML_UseParserAsHandlerArg(XML_Parser parser);
 376
 377 /* Sets the base to be used for resolving relative URIs in system identifiers in
 378 declarations.  Resolving relative identifiers is left to the application:
 379 this value will be passed through as the base argument to the
 380 XML_ExternalEntityRefHandler, XML_NotationDeclHandler
 381 and XML_UnparsedEntityDeclHandler. The base argument will be copied.
 382 Returns zero if out of memory, non-zero otherwise. */
 383
 384 int XMLPARSEAPI
 385 XML_SetBase(XML_Parser parser, const XML_Char *base);
 386
 387 const XML_Char XMLPARSEAPI *
 388 XML_GetBase(XML_Parser parser);
 389
 390 /* Returns the number of the attribute/value pairs passed in last call
 391 to the XML_StartElementHandler that were specified in the start-tag
 392 rather than defaulted. Each attribute/value pair counts as 2; thus
 393 this correspondds to an index into the atts array passed to the
 394 XML_StartElementHandler. */
 395
 396 int XMLPARSEAPI XML_GetSpecifiedAttributeCount(XML_Parser parser);
 397
 398 /* Returns the index of the ID attribute passed in the last call to
 399 XML_StartElementHandler, or -1 if there is no ID attribute.  Each
 400 attribute/value pair counts as 2; thus this correspondds to an index
 401 into the atts array passed to the XML_StartElementHandler. */
 402 int XMLPARSEAPI XML_GetIdAttributeIndex(XML_Parser parser);
 403
 404 /* Parses some input. Returns 0 if a fatal error is detected.
 405 The last call to XML_Parse must have isFinal true;
 406 len may be zero for this call (or any other). */
 407 int XMLPARSEAPI
 408 XML_Parse(XML_Parser parser, const char *s, int len, int isFinal);
 409
 410 void XMLPARSEAPI *
 411 XML_GetBuffer(XML_Parser parser, int len);
 412
 413 int XMLPARSEAPI
 414 XML_ParseBuffer(XML_Parser parser, int len, int isFinal);
 415
 416 /* Creates an XML_Parser object that can parse an external general entity;
 417 context is a '\0'-terminated string specifying the parse context;
 418 encoding is a '\0'-terminated string giving the name of the externally specified encoding,
 419 or null if there is no externally specified encoding.
 420 The context string consists of a sequence of tokens separated by formfeeds (\f);
 421 a token consisting of a name specifies that the general entity of the name
 422 is open; a token of the form prefix=uri specifies the namespace for a particular
 423 prefix; a token of the form =uri specifies the default namespace.
 424 This can be called at any point after the first call to an ExternalEntityRefHandler
 425 so longer as the parser has not yet been freed.
 426 The new parser is completely independent and may safely be used in a separate thread.
 427 The handlers and userData are initialized from the parser argument.
 428 Returns 0 if out of memory.  Otherwise returns a new XML_Parser object. */
 429 XML_Parser XMLPARSEAPI
 430 XML_ExternalEntityParserCreate(XML_Parser parser,
 431                                const XML_Char *context,
 432                                const XML_Char *encoding);
 433
 434 enum XML_ParamEntityParsing {
 435   XML_PARAM_ENTITY_PARSING_NEVER,
 436   XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE,
 437   XML_PARAM_ENTITY_PARSING_ALWAYS
 438 };
 439
 440 /* Controls parsing of parameter entities (including the external DTD
 441 subset). If parsing of parameter entities is enabled, then references
 442 to external parameter entities (including the external DTD subset)
 443 will be passed to the handler set with
 444 XML_SetExternalEntityRefHandler.  The context passed will be 0.
 445 Unlike external general entities, external parameter entities can only
 446 be parsed synchronously.  If the external parameter entity is to be
 447 parsed, it must be parsed during the call to the external entity ref
 448 handler: the complete sequence of XML_ExternalEntityParserCreate,
 449 XML_Parse/XML_ParseBuffer and XML_ParserFree calls must be made during
 450 this call.  After XML_ExternalEntityParserCreate has been called to
 451 create the parser for the external parameter entity (context must be 0
 452 for this call), it is illegal to make any calls on the old parser
 453 until XML_ParserFree has been called on the newly created parser.  If
 454 the library has been compiled without support for parameter entity
 455 parsing (ie without XML_DTD being defined), then
 456 XML_SetParamEntityParsing will return 0 if parsing of parameter
 457 entities is requested; otherwise it will return non-zero. */
 458
 459 int XMLPARSEAPI
 460 XML_SetParamEntityParsing(XML_Parser parser,
 461                           enum XML_ParamEntityParsing parsing);
 462
 463 enum XML_Error {
 464   XML_ERROR_NONE,
 465   XML_ERROR_NO_MEMORY,
 466   XML_ERROR_SYNTAX,
 467   XML_ERROR_NO_ELEMENTS,
 468   XML_ERROR_INVALID_TOKEN,
 469   XML_ERROR_UNCLOSED_TOKEN,
 470   XML_ERROR_PARTIAL_CHAR,
 471   XML_ERROR_TAG_MISMATCH,
 472   XML_ERROR_DUPLICATE_ATTRIBUTE,
 473   XML_ERROR_JUNK_AFTER_DOC_ELEMENT,
 474   XML_ERROR_PARAM_ENTITY_REF,
 475   XML_ERROR_UNDEFINED_ENTITY,
 476   XML_ERROR_RECURSIVE_ENTITY_REF,
 477   XML_ERROR_ASYNC_ENTITY,
 478   XML_ERROR_BAD_CHAR_REF,
 479   XML_ERROR_BINARY_ENTITY_REF,
 480   XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF,
 481   XML_ERROR_MISPLACED_XML_PI,
 482   XML_ERROR_UNKNOWN_ENCODING,
 483   XML_ERROR_INCORRECT_ENCODING,
 484   XML_ERROR_UNCLOSED_CDATA_SECTION,
 485   XML_ERROR_EXTERNAL_ENTITY_HANDLING,
 486   XML_ERROR_NOT_STANDALONE
 487 };
 488
 489 /* If XML_Parse or XML_ParseBuffer have returned 0, then XML_GetErrorCode
 490 returns information about the error. */
 491
 492 enum XML_Error XMLPARSEAPI XML_GetErrorCode(XML_Parser parser);
 493
 494 /* These functions return information about the current parse location.
 495 They may be called when XML_Parse or XML_ParseBuffer return 0;
 496 in this case the location is the location of the character at which
 497 the error was detected.
 498 They may also be called from any other callback called to report
 499 some parse event; in this the location is the location of the first
 500 of the sequence of characters that generated the event. */
 501
 502 int XMLPARSEAPI XML_GetCurrentLineNumber(XML_Parser parser);
 503 int XMLPARSEAPI XML_GetCurrentColumnNumber(XML_Parser parser);
 504 long XMLPARSEAPI XML_GetCurrentByteIndex(XML_Parser parser);
 505
 506 /* Return the number of bytes in the current event.
 507 Returns 0 if the event is in an internal entity. */
 508
 509 int XMLPARSEAPI XML_GetCurrentByteCount(XML_Parser parser);
 510
 511 /* For backwards compatibility with previous versions. */
 512 #define XML_GetErrorLineNumber XML_GetCurrentLineNumber
 513 #define XML_GetErrorColumnNumber XML_GetCurrentColumnNumber
 514 #define XML_GetErrorByteIndex XML_GetCurrentByteIndex
 515
 516 /* Frees memory used by the parser. */
 517 void XMLPARSEAPI
 518 XML_ParserFree(XML_Parser parser);
 519
 520 /* Returns a string describing the error. */
 521 const XML_LChar XMLPARSEAPI *XML_ErrorString(int code);
 522
 523 #ifdef __cplusplus
 524 }
 525 #endif
 526
 527 #endif /* not XmlParse_INCLUDED */