head 1.4; access; symbols; locks; strict; comment @# @; 1.4 date 2002.09.07.01.50.41; author curt; state Exp; branches; next 1.3; 1.3 date 2002.08.31.19.01.59; author curt; state Exp; branches; next 1.2; 1.2 date 2002.08.31.18.54.05; author curt; state Exp; branches; next 1.1; 1.1 date 2002.02.15.17.22.03; author curt; state Exp; branches; next ; desc @@ 1.4 log @Updated doxygen docs. @ text @
Main Page Class Hierarchy Compound List File List Compound Members File Members

# xmlparse.h

    00001 /*
    00002 The contents of this file are subject to the Mozilla Public License
    00003 Version 1.1 (the "License"); you may not use this file except in
    00004 compliance with the License. You may obtain a copy of the License at
    00005 http://www.mozilla.org/MPL/
    00006
    00007 Software distributed under the License is distributed on an "AS IS"
    00008 basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
    00009 License for the specific language governing rights and limitations
    00010 under the License.
    00011
    00012 The Original Code is expat.
    00013
    00014 The Initial Developer of the Original Code is James Clark.
    00015 Portions created by James Clark are Copyright (C) 1998, 1999
    00016 James Clark. All Rights Reserved.
    00017
    00018 Contributor(s):
    00019
    00020 Alternatively, the contents of this file may be used under the terms
    00021 of the GNU General Public License (the "GPL"), in which case the
    00022 provisions of the GPL are applicable instead of those above.  If you
    00023 wish to allow use of your version of this file only under the terms of
    00024 the GPL and not to allow others to use your version of this file under
    00025 the MPL, indicate your decision by deleting the provisions above and
    00026 replace them with the notice and other provisions required by the
    00027 GPL. If you do not delete the provisions above, a recipient may use
    00028 your version of this file under either the MPL or the GPL.
    00029 */
    00030
    00031 #ifndef XmlParse_INCLUDED
    00032 #define XmlParse_INCLUDED 1
    00033
    00034 #ifdef __cplusplus
    00035 extern "C" {
    00036 #endif
    00037
    00038 #ifndef XMLPARSEAPI
    00039 #define XMLPARSEAPI /* as nothing */
    00040 #endif
    00041
    00042 typedef void *XML_Parser;
    00043
    00044 #ifdef XML_UNICODE_WCHAR_T
    00045
    00046 /* XML_UNICODE_WCHAR_T will work only if sizeof(wchar_t) == 2 and wchar_t
    00047 uses Unicode. */
    00048 /* Information is UTF-16 encoded as wchar_ts */
    00049
    00050 #ifndef XML_UNICODE
    00051 #define XML_UNICODE
    00052 #endif
    00053
    00054 #include <stddef.h>
    00055 typedef wchar_t XML_Char;
    00056 typedef wchar_t XML_LChar;
    00057
    00058 #else /* not XML_UNICODE_WCHAR_T */
    00059
    00060 #ifdef XML_UNICODE
    00061
    00062 /* Information is UTF-16 encoded as unsigned shorts */
    00063 typedef unsigned short XML_Char;
    00064 typedef char XML_LChar;
    00065
    00066 #else /* not XML_UNICODE */
    00067
    00068 /* Information is UTF-8 encoded. */
    00069 typedef char XML_Char;
    00070 typedef char XML_LChar;
    00071
    00072 #endif /* not XML_UNICODE */
    00073
    00074 #endif /* not XML_UNICODE_WCHAR_T */
    00075
    00076
    00077 /* Constructs a new parser; encoding is the encoding specified by the external
    00078 protocol or null if there is none specified. */
    00079
    00080 XML_Parser XMLPARSEAPI
    00081 XML_ParserCreate(const XML_Char *encoding);
    00082
    00083 /* Constructs a new parser and namespace processor.  Element type names
    00084 and attribute names that belong to a namespace will be expanded;
    00085 unprefixed attribute names are never expanded; unprefixed element type
    00086 names are expanded only if there is a default namespace. The expanded
    00087 name is the concatenation of the namespace URI, the namespace separator character,
    00088 and the local part of the name.  If the namespace separator is '\0' then
    00089 the namespace URI and the local part will be concatenated without any
    00090 separator.  When a namespace is not declared, the name and prefix will be
    00091 passed through without expansion. */
    00092
    00093 XML_Parser XMLPARSEAPI
    00094 XML_ParserCreateNS(const XML_Char *encoding, XML_Char namespaceSeparator);
    00095
    00096
    00097 /* atts is array of name/value pairs, terminated by 0;
    00098    names and values are 0 terminated. */
    00099
    00100 typedef void (*XML_StartElementHandler)(void *userData,
    00101                                         const XML_Char *name,
    00102                                         const XML_Char **atts);
    00103
    00104 typedef void (*XML_EndElementHandler)(void *userData,
    00105                                       const XML_Char *name);
    00106
    00107 /* s is not 0 terminated. */
    00108 typedef void (*XML_CharacterDataHandler)(void *userData,
    00109                                          const XML_Char *s,
    00110                                          int len);
    00111
    00112 /* target and data are 0 terminated */
    00113 typedef void (*XML_ProcessingInstructionHandler)(void *userData,
    00114                                                  const XML_Char *target,
    00115                                                  const XML_Char *data);
    00116
    00117 /* data is 0 terminated */
    00118 typedef void (*XML_CommentHandler)(void *userData, const XML_Char *data);
    00119
    00120 typedef void (*XML_StartCdataSectionHandler)(void *userData);
    00121 typedef void (*XML_EndCdataSectionHandler)(void *userData);
    00122
    00123 /* This is called for any characters in the XML document for
    00124 which there is no applicable handler.  This includes both
    00125 characters that are part of markup which is of a kind that is
    00126 not reported (comments, markup declarations), or characters
    00127 that are part of a construct which could be reported but
    00128 for which no handler has been supplied. The characters are passed
    00129 exactly as they were in the XML document except that
    00130 they will be encoded in UTF-8.  Line boundaries are not normalized.
    00131 Note that a byte order mark character is not passed to the default handler.
    00132 There are no guarantees about how characters are divided between calls
    00133 to the default handler: for example, a comment might be split between
    00134 multiple calls. */
    00135
    00136 typedef void (*XML_DefaultHandler)(void *userData,
    00137                                    const XML_Char *s,
    00138                                    int len);
    00139
    00140 /* This is called for a declaration of an unparsed (NDATA)
    00141 entity.  The base argument is whatever was set by XML_SetBase.
    00142 The entityName, systemId and notationName arguments will never be null.
    00143 The other arguments may be. */
    00144
    00145 typedef void (*XML_UnparsedEntityDeclHandler)(void *userData,
    00146                                               const XML_Char *entityName,
    00147                                               const XML_Char *base,
    00148                                               const XML_Char *systemId,
    00149                                               const XML_Char *publicId,
    00150                                               const XML_Char *notationName);
    00151
    00152 /* This is called for a declaration of notation.
    00153 The base argument is whatever was set by XML_SetBase.
    00154 The notationName will never be null.  The other arguments can be. */
    00155
    00156 typedef void (*XML_NotationDeclHandler)(void *userData,
    00157                                         const XML_Char *notationName,
    00158                                         const XML_Char *base,
    00159                                         const XML_Char *systemId,
    00160                                         const XML_Char *publicId);
    00161
    00162 /* When namespace processing is enabled, these are called once for
    00163 each namespace declaration. The call to the start and end element
    00164 handlers occur between the calls to the start and end namespace
    00165 declaration handlers. For an xmlns attribute, prefix will be null.
    00166 For an xmlns="" attribute, uri will be null. */
    00167
    00168 typedef void (*XML_StartNamespaceDeclHandler)(void *userData,
    00169                                               const XML_Char *prefix,
    00170                                               const XML_Char *uri);
    00171
    00172 typedef void (*XML_EndNamespaceDeclHandler)(void *userData,
    00173                                             const XML_Char *prefix);
    00174
    00175 /* This is called if the document is not standalone (it has an
    00176 external subset or a reference to a parameter entity, but does not
    00177 have standalone="yes"). If this handler returns 0, then processing
    00178 will not continue, and the parser will return a
    00179 XML_ERROR_NOT_STANDALONE error. */
    00180
    00181 typedef int (*XML_NotStandaloneHandler)(void *userData);
    00182
    00183 /* This is called for a reference to an external parsed general entity.
    00184 The referenced entity is not automatically parsed.
    00185 The application can parse it immediately or later using
    00186 XML_ExternalEntityParserCreate.
    00187 The parser argument is the parser parsing the entity containing the reference;
    00188 it can be passed as the parser argument to XML_ExternalEntityParserCreate.
    00189 The systemId argument is the system identifier as specified in the entity declaration;
    00190 it will not be null.
    00191 The base argument is the system identifier that should be used as the base for
    00192 resolving systemId if systemId was relative; this is set by XML_SetBase;
    00193 it may be null.
    00194 The publicId argument is the public identifier as specified in the entity declaration,
    00195 or null if none was specified; the whitespace in the public identifier
    00196 will have been normalized as required by the XML spec.
    00197 The context argument specifies the parsing context in the format
    00198 expected by the context argument to
    00199 XML_ExternalEntityParserCreate; context is valid only until the handler
    00200 returns, so if the referenced entity is to be parsed later, it must be copied.
    00201 The handler should return 0 if processing should not continue because of
    00202 a fatal error in the handling of the external entity.
    00203 In this case the calling parser will return an XML_ERROR_EXTERNAL_ENTITY_HANDLING
    00204 error.
    00205 Note that unlike other handlers the first argument is the parser, not userData. */
    00206
    00207 typedef int (*XML_ExternalEntityRefHandler)(XML_Parser parser,
    00208                                             const XML_Char *context,
    00209                                             const XML_Char *base,
    00210                                             const XML_Char *systemId,
    00211                                             const XML_Char *publicId);
    00212
    00213 /* This structure is filled in by the XML_UnknownEncodingHandler
    00214 to provide information to the parser about encodings that are unknown
    00215 to the parser.
    00216 The map[b] member gives information about byte sequences
    00217 whose first byte is b.
    00218 If map[b] is c where c is >= 0, then b by itself encodes the Unicode scalar value c.
    00219 If map[b] is -1, then the byte sequence is malformed.
    00220 If map[b] is -n, where n >= 2, then b is the first byte of an n-byte
    00221 sequence that encodes a single Unicode scalar value.
    00222 The data member will be passed as the first argument to the convert function.
    00223 The convert function is used to convert multibyte sequences;
    00224 s will point to a n-byte sequence where map[(unsigned char)*s] == -n.
    00225 The convert function must return the Unicode scalar value
    00226 represented by this byte sequence or -1 if the byte sequence is malformed.
    00227 The convert function may be null if the encoding is a single-byte encoding,
    00228 that is if map[b] >= -1 for all bytes b.
    00229 When the parser is finished with the encoding, then if release is not null,
    00230 it will call release passing it the data member;
    00231 once release has been called, the convert function will not be called again.
    00232
    00233 Expat places certain restrictions on the encodings that are supported
    00234 using this mechanism.
    00235
    00236 1. Every ASCII character that can appear in a well-formed XML document,
    00237 other than the characters
    00238
    00239   $@@\^`{}~
    00240
    00241 must be represented by a single byte, and that byte must be the
    00242 same byte that represents that character in ASCII.
    00243
    00244 2. No character may require more than 4 bytes to encode.
    00245
    00246 3. All characters encoded must have Unicode scalar values <= 0xFFFF,
    00247 (ie characters that would be encoded by surrogates in UTF-16
    00248 are  not allowed).  Note that this restriction doesn't apply to
    00249 the built-in support for UTF-8 and UTF-16.
    00250
    00251 4. No Unicode character may be encoded by more than one distinct sequence
    00252 of bytes. */
    00253
    00254 typedef struct {
    00255   int map[256];
    00256   void *data;
    00257   int (*convert)(void *data, const char *s);
    00258   void (*release)(void *data);
    00259 } XML_Encoding;
    00260
    00261 /* This is called for an encoding that is unknown to the parser.
    00262 The encodingHandlerData argument is that which was passed as the
    00263 second argument to XML_SetUnknownEncodingHandler.
    00264 The name argument gives the name of the encoding as specified in
    00265 the encoding declaration.
    00266 If the callback can provide information about the encoding,
    00267 it must fill in the XML_Encoding structure, and return 1.
    00268 Otherwise it must return 0.
    00269 If info does not describe a suitable encoding,
    00270 then the parser will return an XML_UNKNOWN_ENCODING error. */
    00271
    00272 typedef int (*XML_UnknownEncodingHandler)(void *encodingHandlerData,
    00273                                           const XML_Char *name,
    00274                                           XML_Encoding *info);
    00275
    00276 void XMLPARSEAPI
    00277 XML_SetElementHandler(XML_Parser parser,
    00278                       XML_StartElementHandler start,
    00279                       XML_EndElementHandler end);
    00280
    00281 void XMLPARSEAPI
    00282 XML_SetCharacterDataHandler(XML_Parser parser,
    00283                             XML_CharacterDataHandler handler);
    00284
    00285 void XMLPARSEAPI
    00286 XML_SetProcessingInstructionHandler(XML_Parser parser,
    00287                                     XML_ProcessingInstructionHandler handler);
    00288 void XMLPARSEAPI
    00289 XML_SetCommentHandler(XML_Parser parser,
    00290                       XML_CommentHandler handler);
    00291
    00292 void XMLPARSEAPI
    00293 XML_SetCdataSectionHandler(XML_Parser parser,
    00294                            XML_StartCdataSectionHandler start,
    00295                            XML_EndCdataSectionHandler end);
    00296
    00297 /* This sets the default handler and also inhibits expansion of internal entities.
    00298 The entity reference will be passed to the default handler. */
    00299
    00300 void XMLPARSEAPI
    00301 XML_SetDefaultHandler(XML_Parser parser,
    00302                       XML_DefaultHandler handler);
    00303
    00304 /* This sets the default handler but does not inhibit expansion of internal entities.
    00305 The entity reference will not be passed to the default handler. */
    00306
    00307 void XMLPARSEAPI
    00308 XML_SetDefaultHandlerExpand(XML_Parser parser,
    00309                             XML_DefaultHandler handler);
    00310
    00311 void XMLPARSEAPI
    00312 XML_SetUnparsedEntityDeclHandler(XML_Parser parser,
    00313                                  XML_UnparsedEntityDeclHandler handler);
    00314
    00315 void XMLPARSEAPI
    00316 XML_SetNotationDeclHandler(XML_Parser parser,
    00317                            XML_NotationDeclHandler handler);
    00318
    00319 void XMLPARSEAPI
    00320 XML_SetNamespaceDeclHandler(XML_Parser parser,
    00321                             XML_StartNamespaceDeclHandler start,
    00322                             XML_EndNamespaceDeclHandler end);
    00323
    00324 void XMLPARSEAPI
    00325 XML_SetNotStandaloneHandler(XML_Parser parser,
    00326                             XML_NotStandaloneHandler handler);
    00327
    00328 void XMLPARSEAPI
    00329 XML_SetExternalEntityRefHandler(XML_Parser parser,
    00330                                 XML_ExternalEntityRefHandler handler);
    00331
    00332 /* If a non-null value for arg is specified here, then it will be passed
    00333 as the first argument to the external entity ref handler instead
    00334 of the parser object. */
    00335 void XMLPARSEAPI
    00336 XML_SetExternalEntityRefHandlerArg(XML_Parser, void *arg);
    00337
    00338 void XMLPARSEAPI
    00339 XML_SetUnknownEncodingHandler(XML_Parser parser,
    00340                               XML_UnknownEncodingHandler handler,
    00341                               void *encodingHandlerData);
    00342
    00343 /* This can be called within a handler for a start element, end element,
    00344 processing instruction or character data.  It causes the corresponding
    00345 markup to be passed to the default handler. */
    00346 void XMLPARSEAPI XML_DefaultCurrent(XML_Parser parser);
    00347
    00348 /* This value is passed as the userData argument to callbacks. */
    00349 void XMLPARSEAPI
    00350 XML_SetUserData(XML_Parser parser, void *userData);
    00351
    00352 /* Returns the last value set by XML_SetUserData or null. */
    00353 #define XML_GetUserData(parser) (*(void **)(parser))
    00354
    00355 /* This is equivalent to supplying an encoding argument
    00356 to XML_CreateParser. It must not be called after XML_Parse
    00357 or XML_ParseBuffer. */
    00358
    00359 int XMLPARSEAPI
    00360 XML_SetEncoding(XML_Parser parser, const XML_Char *encoding);
    00361
    00362 /* If this function is called, then the parser will be passed
    00363 as the first argument to callbacks instead of userData.
    00364 The userData will still be accessible using XML_GetUserData. */
    00365
    00366 void XMLPARSEAPI
    00367 XML_UseParserAsHandlerArg(XML_Parser parser);
    00368
    00369 /* Sets the base to be used for resolving relative URIs in system identifiers in
    00370 declarations.  Resolving relative identifiers is left to the application:
    00371 this value will be passed through as the base argument to the
    00372 XML_ExternalEntityRefHandler, XML_NotationDeclHandler
    00373 and XML_UnparsedEntityDeclHandler. The base argument will be copied.
    00374 Returns zero if out of memory, non-zero otherwise. */
    00375
    00376 int XMLPARSEAPI
    00377 XML_SetBase(XML_Parser parser, const XML_Char *base);
    00378
    00379 const XML_Char XMLPARSEAPI *
    00380 XML_GetBase(XML_Parser parser);
    00381
    00382 /* Returns the number of the attributes passed in last call to the
    00383 XML_StartElementHandler that were specified in the start-tag rather
    00384 than defaulted. */
    00385
    00386 int XMLPARSEAPI XML_GetSpecifiedAttributeCount(XML_Parser parser);
    00387
    00388 /* Parses some input. Returns 0 if a fatal error is detected.
    00389 The last call to XML_Parse must have isFinal true;
    00390 len may be zero for this call (or any other). */
    00391 int XMLPARSEAPI
    00392 XML_Parse(XML_Parser parser, const char *s, int len, int isFinal);
    00393
    00394 void XMLPARSEAPI *
    00395 XML_GetBuffer(XML_Parser parser, int len);
    00396
    00397 int XMLPARSEAPI
    00398 XML_ParseBuffer(XML_Parser parser, int len, int isFinal);
    00399
    00400 /* Creates an XML_Parser object that can parse an external general entity;
    00401 context is a '\0'-terminated string specifying the parse context;
    00402 encoding is a '\0'-terminated string giving the name of the externally specified encoding,
    00403 or null if there is no externally specified encoding.
    00404 The context string consists of a sequence of tokens separated by formfeeds (\f);
    00405 a token consisting of a name specifies that the general entity of the name
    00406 is open; a token of the form prefix=uri specifies the namespace for a particular
    00407 prefix; a token of the form =uri specifies the default namespace.
    00408 This can be called at any point after the first call to an ExternalEntityRefHandler
    00409 so longer as the parser has not yet been freed.
    00410 The new parser is completely independent and may safely be used in a separate thread.
    00411 The handlers and userData are initialized from the parser argument.
    00412 Returns 0 if out of memory.  Otherwise returns a new XML_Parser object. */
    00413 XML_Parser XMLPARSEAPI
    00414 XML_ExternalEntityParserCreate(XML_Parser parser,
    00415                                const XML_Char *context,
    00416                                const XML_Char *encoding);
    00417
    00418 enum XML_Error {
    00419   XML_ERROR_NONE,
    00420   XML_ERROR_NO_MEMORY,
    00421   XML_ERROR_SYNTAX,
    00422   XML_ERROR_NO_ELEMENTS,
    00423   XML_ERROR_INVALID_TOKEN,
    00424   XML_ERROR_UNCLOSED_TOKEN,
    00425   XML_ERROR_PARTIAL_CHAR,
    00426   XML_ERROR_TAG_MISMATCH,
    00427   XML_ERROR_DUPLICATE_ATTRIBUTE,
    00428   XML_ERROR_JUNK_AFTER_DOC_ELEMENT,
    00429   XML_ERROR_PARAM_ENTITY_REF,
    00430   XML_ERROR_UNDEFINED_ENTITY,
    00431   XML_ERROR_RECURSIVE_ENTITY_REF,
    00432   XML_ERROR_ASYNC_ENTITY,
    00433   XML_ERROR_BAD_CHAR_REF,
    00434   XML_ERROR_BINARY_ENTITY_REF,
    00435   XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF,
    00436   XML_ERROR_MISPLACED_XML_PI,
    00437   XML_ERROR_UNKNOWN_ENCODING,
    00438   XML_ERROR_INCORRECT_ENCODING,
    00439   XML_ERROR_UNCLOSED_CDATA_SECTION,
    00440   XML_ERROR_EXTERNAL_ENTITY_HANDLING,
    00441   XML_ERROR_NOT_STANDALONE
    00442 };
    00443
    00444 /* If XML_Parse or XML_ParseBuffer have returned 0, then XML_GetErrorCode
    00445 returns information about the error. */
    00446
    00447 enum XML_Error XMLPARSEAPI XML_GetErrorCode(XML_Parser parser);
    00448
    00449 /* These functions return information about the current parse location.
    00450 They may be called when XML_Parse or XML_ParseBuffer return 0;
    00451 in this case the location is the location of the character at which
    00452 the error was detected.
    00453 They may also be called from any other callback called to report
    00454 some parse event; in this the location is the location of the first
    00455 of the sequence of characters that generated the event. */
    00456
    00457 int XMLPARSEAPI XML_GetCurrentLineNumber(XML_Parser parser);
    00458 int XMLPARSEAPI XML_GetCurrentColumnNumber(XML_Parser parser);
    00459 long XMLPARSEAPI XML_GetCurrentByteIndex(XML_Parser parser);
    00460
    00461 /* Return the number of bytes in the current event.
    00462 Returns 0 if the event is in an internal entity. */
    00463
    00464 int XMLPARSEAPI XML_GetCurrentByteCount(XML_Parser parser);
    00465
    00466 /* For backwards compatibility with previous versions. */
    00467 #define XML_GetErrorLineNumber XML_GetCurrentLineNumber
    00468 #define XML_GetErrorColumnNumber XML_GetCurrentColumnNumber
    00469 #define XML_GetErrorByteIndex XML_GetCurrentByteIndex
    00470
    00471 /* Frees memory used by the parser. */
    00472 void XMLPARSEAPI
    00473 XML_ParserFree(XML_Parser parser);
    00474
    00475 /* Returns a string describing the error. */
    00476 const XML_LChar XMLPARSEAPI *XML_ErrorString(int code);
    00477
    00478 #ifdef __cplusplus
    00479 }
    00480 #endif
    00481
    00482 #endif /* not XmlParse_INCLUDED */

@ 1.3 log @Oops, try again. @ text @d491 1 a491 1