1/* 2The contents of this file are subject to the Mozilla Public License 3Version 1.0 (the "License"); you may not use this file except in 4compliance with the License. You may obtain a copy of the License at 5http://www.mozilla.org/MPL/ 6 7Software distributed under the License is distributed on an "AS IS" 8basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the 9License for the specific language governing rights and limitations 10under the License. 11 12The Original Code is expat. 13 14The Initial Developer of the Original Code is James Clark. 15Portions created by James Clark are Copyright (C) 1998 16James Clark. All Rights Reserved. 17 18Contributor(s): 19*/ 20 21#ifndef XmlParse_INCLUDED 22#define XmlParse_INCLUDED 1 23 24#ifdef __cplusplus 25extern "C" { 26#endif 27 28#ifndef XMLPARSEAPI 29#define XMLPARSEAPI /* as nothing */ 30#endif 31 32typedef void *XML_Parser; 33 34#ifdef XML_UNICODE_WCHAR_T 35 36/* XML_UNICODE_WCHAR_T will work only if sizeof(wchar_t) == 2 and wchar_t 37uses Unicode. */ 38/* Information is UTF-16 encoded as wchar_ts */ 39 40#ifndef XML_UNICODE 41#define XML_UNICODE 42#endif 43 44#include <stddef.h> 45typedef wchar_t XML_Char; 46typedef wchar_t XML_LChar; 47 48#else /* not XML_UNICODE_WCHAR_T */ 49 50#ifdef XML_UNICODE 51 52/* Information is UTF-16 encoded as unsigned shorts */ 53typedef unsigned short XML_Char; 54typedef char XML_LChar; 55 56#else /* not XML_UNICODE */ 57 58/* Information is UTF-8 encoded. */ 59typedef char XML_Char; 60typedef char XML_LChar; 61 62#endif /* not XML_UNICODE */ 63 64#endif /* not XML_UNICODE_WCHAR_T */ 65 66 67/* Constructs a new parser; encoding is the encoding specified by the external 68protocol or null if there is none specified. */ 69 70XML_Parser XMLPARSEAPI 71XML_ParserCreate(const XML_Char *encoding); 72 73 74/* atts is array of name/value pairs, terminated by 0; 75 names and values are 0 terminated. */ 76 77typedef void (*XML_StartElementHandler)(void *userData, 78 const XML_Char *name, 79 const XML_Char **atts); 80 81typedef void (*XML_EndElementHandler)(void *userData, 82 const XML_Char *name); 83 84/* s is not 0 terminated. */ 85typedef void (*XML_CharacterDataHandler)(void *userData, 86 const XML_Char *s, 87 size_t len); 88 89/* target and data are 0 terminated */ 90typedef void (*XML_ProcessingInstructionHandler)(void *userData, 91 const XML_Char *target, 92 const XML_Char *data); 93 94/* This is called for any characters in the XML document for 95which there is no applicable handler. This includes both 96characters that are part of markup which is of a kind that is 97not reported (comments, markup declarations), or characters 98that are part of a construct which could be reported but 99for which no handler has been supplied. The characters are passed 100exactly as they were in the XML document except that 101they will be encoded in UTF-8. Line boundaries are not normalized. 102Note that a byte order mark character is not passed to the default handler. 103If a default handler is set, internal entity references 104are not expanded. There are no guarantees about 105how characters are divided between calls to the default handler: 106for example, a comment might be split between multiple calls. */ 107 108typedef void (*XML_DefaultHandler)(void *userData, 109 const XML_Char *s, 110 int len); 111 112/* This is called for a declaration of an unparsed (NDATA) 113entity. The base argument is whatever was set by XML_SetBase. 114The entityName, systemId and notationName arguments will never be null. 115The other arguments may be. */ 116 117typedef void (*XML_UnparsedEntityDeclHandler)(void *userData, 118 const XML_Char *entityName, 119 const XML_Char *base, 120 const XML_Char *systemId, 121 const XML_Char *publicId, 122 const XML_Char *notationName); 123 124/* This is called for a declaration of notation. 125The base argument is whatever was set by XML_SetBase. 126The notationName will never be null. The other arguments can be. */ 127 128typedef void (*XML_NotationDeclHandler)(void *userData, 129 const XML_Char *notationName, 130 const XML_Char *base, 131 const XML_Char *systemId, 132 const XML_Char *publicId); 133 134/* This is called for a reference to an external parsed general entity. 135The referenced entity is not automatically parsed. 136The application can parse it immediately or later using 137XML_ExternalEntityParserCreate. 138The parser argument is the parser parsing the entity containing the reference; 139it can be passed as the parser argument to XML_ExternalEntityParserCreate. 140The systemId argument is the system identifier as specified in the entity declaration; 141it will not be null. 142The base argument is the system identifier that should be used as the base for 143resolving systemId if systemId was relative; this is set by XML_SetBase; 144it may be null. 145The publicId argument is the public identifier as specified in the entity declaration, 146or null if none was specified; the whitespace in the public identifier 147will have been normalized as required by the XML spec. 148The openEntityNames argument is a space-separated list of the names of the entities 149that are open for the parse of this entity (including the name of the referenced 150entity); this can be passed as the openEntityNames argument to 151XML_ExternalEntityParserCreate; openEntityNames is valid only until the handler 152returns, so if the referenced entity is to be parsed later, it must be copied. 153The handler should return 0 if processing should not continue because of 154a fatal error in the handling of the external entity. 155In this case the calling parser will return an XML_ERROR_EXTERNAL_ENTITY_HANDLING 156error. 157Note that unlike other handlers the first argument is the parser, not userData. */ 158 159typedef int (*XML_ExternalEntityRefHandler)(XML_Parser parser, 160 const XML_Char *openEntityNames, 161 const XML_Char *base, 162 const XML_Char *systemId, 163 const XML_Char *publicId); 164 165/* This structure is filled in by the XML_UnknownEncodingHandler 166to provide information to the parser about encodings that are unknown 167to the parser. 168The map[b] member gives information about byte sequences 169whose first byte is b. 170If map[b] is c where c is >= 0, then b by itself encodes the Unicode scalar value c. 171If map[b] is -1, then the byte sequence is malformed. 172If map[b] is -n, where n >= 2, then b is the first byte of an n-byte 173sequence that encodes a single Unicode scalar value. 174The data member will be passed as the first argument to the convert function. 175The convert function is used to convert multibyte sequences; 176s will point to a n-byte sequence where map[(unsigned char)*s] == -n. 177The convert function must return the Unicode scalar value 178represented by this byte sequence or -1 if the byte sequence is malformed. 179The convert function may be null if the encoding is a single-byte encoding, 180that is if map[b] >= -1 for all bytes b. 181When the parser is finished with the encoding, then if release is not null, 182it will call release passing it the data member; 183once release has been called, the convert function will not be called again. 184 185Expat places certain restrictions on the encodings that are supported 186using this mechanism. 187 1881. Every ASCII character that can appear in a well-formed XML document, 189other than the characters 190 191 $@\^`{}~ 192 193must be represented by a single byte, and that byte must be the 194same byte that represents that character in ASCII. 195 1962. No character may require more than 4 bytes to encode. 197 1983. All characters encoded must have Unicode scalar values <= 0xFFFF, 199(ie characters that would be encoded by surrogates in UTF-16 200are not allowed). Note that this restriction doesn't apply to 201the built-in support for UTF-8 and UTF-16. 202 2034. No Unicode character may be encoded by more than one distinct sequence 204of bytes. */ 205 206typedef struct { 207 int map[256]; 208 void *data; 209 int (*convert)(void *data, const char *s); 210 void (*release)(void *data); 211} XML_Encoding; 212 213/* This is called for an encoding that is unknown to the parser. 214The encodingHandlerData argument is that which was passed as the 215second argument to XML_SetUnknownEncodingHandler. 216The name argument gives the name of the encoding as specified in 217the encoding declaration. 218If the callback can provide information about the encoding, 219it must fill in the XML_Encoding structure, and return 1. 220Otherwise it must return 0. 221If info does not describe a suitable encoding, 222then the parser will return an XML_UNKNOWN_ENCODING error. */ 223 224typedef int (*XML_UnknownEncodingHandler)(void *encodingHandlerData, 225 const XML_Char *name, 226 XML_Encoding *info); 227 228void XMLPARSEAPI 229XML_SetElementHandler(XML_Parser parser, 230 XML_StartElementHandler start, 231 XML_EndElementHandler end); 232 233void XMLPARSEAPI 234XML_SetCharacterDataHandler(XML_Parser parser, 235 XML_CharacterDataHandler handler); 236 237void XMLPARSEAPI 238XML_SetProcessingInstructionHandler(XML_Parser parser, 239 XML_ProcessingInstructionHandler handler); 240 241void XMLPARSEAPI 242XML_SetDefaultHandler(XML_Parser parser, 243 XML_DefaultHandler handler); 244 245void XMLPARSEAPI 246XML_SetUnparsedEntityDeclHandler(XML_Parser parser, 247 XML_UnparsedEntityDeclHandler handler); 248 249void XMLPARSEAPI 250XML_SetNotationDeclHandler(XML_Parser parser, 251 XML_NotationDeclHandler handler); 252 253void XMLPARSEAPI 254XML_SetExternalEntityRefHandler(XML_Parser parser, 255 XML_ExternalEntityRefHandler handler); 256 257void XMLPARSEAPI 258XML_SetUnknownEncodingHandler(XML_Parser parser, 259 XML_UnknownEncodingHandler handler, 260 void *encodingHandlerData); 261 262/* This can be called within a handler for a start element, end element, 263processing instruction or character data. It causes the corresponding 264markup to be passed to the default handler. 265Within the expansion of an internal entity, nothing will be passed 266to the default handler, although this usually will not happen since 267setting a default handler inhibits expansion of internal entities. */ 268void XMLPARSEAPI XML_DefaultCurrent(XML_Parser parser); 269 270/* This value is passed as the userData argument to callbacks. */ 271void XMLPARSEAPI 272XML_SetUserData(XML_Parser parser, void *userData); 273 274/* Returns the last value set by XML_SetUserData or null. */ 275#define XML_GetUserData(parser) (*(void **)(parser)) 276 277/* If this function is called, then the parser will be passed 278as the first argument to callbacks instead of userData. 279The userData will still be accessible using XML_GetUserData. */ 280 281void XMLPARSEAPI 282XML_UseParserAsHandlerArg(XML_Parser parser); 283 284/* Sets the base to be used for resolving relative URIs in system identifiers in 285declarations. Resolving relative identifiers is left to the application: 286this value will be passed through as the base argument to the 287XML_ExternalEntityRefHandler, XML_NotationDeclHandler 288and XML_UnparsedEntityDeclHandler. The base argument will be copied. 289Returns zero if out of memory, non-zero otherwise. */ 290 291int XMLPARSEAPI 292XML_SetBase(XML_Parser parser, const XML_Char *base); 293 294const XML_Char XMLPARSEAPI * 295XML_GetBase(XML_Parser parser); 296 297/* Parses some input. Returns 0 if a fatal error is detected. 298The last call to XML_Parse must have isFinal true; 299len may be zero for this call (or any other). */ 300int XMLPARSEAPI 301XML_Parse(XML_Parser parser, const char *s, size_t len, int isFinal); 302 303void XMLPARSEAPI * 304XML_GetBuffer(XML_Parser parser, size_t len); 305 306int XMLPARSEAPI 307XML_ParseBuffer(XML_Parser parser, size_t len, int isFinal); 308 309/* Creates an XML_Parser object that can parse an external general entity; 310openEntityNames is a space-separated list of the names of the entities that are open 311for the parse of this entity (including the name of this one); 312encoding is the externally specified encoding, 313or null if there is no externally specified encoding. 314This can be called at any point after the first call to an ExternalEntityRefHandler 315so longer as the parser has not yet been freed. 316The new parser is completely independent and may safely be used in a separate thread. 317The handlers and userData are initialized from the parser argument. 318Returns 0 if out of memory. Otherwise returns a new XML_Parser object. */ 319XML_Parser XMLPARSEAPI 320XML_ExternalEntityParserCreate(XML_Parser parser, 321 const XML_Char *openEntityNames, 322 const XML_Char *encoding); 323 324enum XML_Error { 325 XML_ERROR_NONE, 326 XML_ERROR_NO_MEMORY, 327 XML_ERROR_SYNTAX, 328 XML_ERROR_NO_ELEMENTS, 329 XML_ERROR_INVALID_TOKEN, 330 XML_ERROR_UNCLOSED_TOKEN, 331 XML_ERROR_PARTIAL_CHAR, 332 XML_ERROR_TAG_MISMATCH, 333 XML_ERROR_DUPLICATE_ATTRIBUTE, 334 XML_ERROR_JUNK_AFTER_DOC_ELEMENT, 335 XML_ERROR_PARAM_ENTITY_REF, 336 XML_ERROR_UNDEFINED_ENTITY, 337 XML_ERROR_RECURSIVE_ENTITY_REF, 338 XML_ERROR_ASYNC_ENTITY, 339 XML_ERROR_BAD_CHAR_REF, 340 XML_ERROR_BINARY_ENTITY_REF, 341 XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF, 342 XML_ERROR_MISPLACED_XML_PI, 343 XML_ERROR_UNKNOWN_ENCODING, 344 XML_ERROR_INCORRECT_ENCODING, 345 XML_ERROR_UNCLOSED_CDATA_SECTION, 346 XML_ERROR_EXTERNAL_ENTITY_HANDLING 347}; 348 349/* If XML_Parse or XML_ParseBuffer have returned 0, then XML_GetErrorCode 350returns information about the error. */ 351 352enum XML_Error XMLPARSEAPI XML_GetErrorCode(XML_Parser parser); 353 354/* These functions return information about the current parse location. 355They may be called when XML_Parse or XML_ParseBuffer return 0; 356in this case the location is the location of the character at which 357the error was detected. 358They may also be called from any other callback called to report 359some parse event; in this the location is the location of the first 360of the sequence of characters that generated the event. */ 361 362int XMLPARSEAPI XML_GetCurrentLineNumber(XML_Parser parser); 363int XMLPARSEAPI XML_GetCurrentColumnNumber(XML_Parser parser); 364long XMLPARSEAPI XML_GetCurrentByteIndex(XML_Parser parser); 365 366/* For backwards compatibility with previous versions. */ 367#define XML_GetErrorLineNumber XML_GetCurrentLineNumber 368#define XML_GetErrorColumnNumber XML_GetCurrentColumnNumber 369#define XML_GetErrorByteIndex XML_GetCurrentByteIndex 370 371/* Frees memory used by the parser. */ 372void XMLPARSEAPI 373XML_ParserFree(XML_Parser parser); 374 375/* Returns a string describing the error. */ 376const XML_LChar XMLPARSEAPI *XML_ErrorString(enum XML_Error code); 377 378#ifdef __cplusplus 379} 380#endif 381 382#endif /* not XmlParse_INCLUDED */ 383