torcs - 1.2.2

src/libs/txml/xmlparse.h

Go to the documentation of this file.
00001 /*
00002 The contents of this file are subject to the Mozilla Public License
00003 Version 1.0 (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
00016 James Clark. All Rights Reserved.
00017 
00018 Contributor(s):
00019 $Id: xmlparse.h,v 1.1.1.1 2001/06/24 18:29:53 torcs Exp $
00020 */
00021 
00022 #ifndef XmlParse_INCLUDED
00023 #define XmlParse_INCLUDED 1
00024 
00025 #ifdef __cplusplus
00026 extern "C" {
00027 #endif
00028 
00029 #ifndef XMLPARSEAPI
00030 #define XMLPARSEAPI /* as nothing */
00031 #endif
00032 
00033 typedef void *XML_Parser;
00034 
00035 #ifdef XML_UNICODE_WCHAR_T
00036 
00037 /* XML_UNICODE_WCHAR_T will work only if sizeof(wchar_t) == 2 and wchar_t
00038 uses Unicode. */
00039 /* Information is UTF-16 encoded as wchar_ts */
00040 
00041 #ifndef XML_UNICODE
00042 #define XML_UNICODE
00043 #endif
00044 
00045 #include <stddef.h>
00046 typedef wchar_t XML_Char;
00047 typedef wchar_t XML_LChar;
00048 
00049 #else /* not XML_UNICODE_WCHAR_T */
00050 
00051 #ifdef XML_UNICODE
00052 
00053 /* Information is UTF-16 encoded as unsigned shorts */
00054 typedef unsigned short XML_Char;
00055 typedef char XML_LChar;
00056 
00057 #else /* not XML_UNICODE */
00058 
00059 /* Information is UTF-8 encoded. */
00060 typedef char XML_Char;
00061 typedef char XML_LChar;
00062 
00063 #endif /* not XML_UNICODE */
00064 
00065 #endif /* not XML_UNICODE_WCHAR_T */
00066 
00067 
00068 /* Constructs a new parser; encoding is the encoding specified by the external
00069 protocol or null if there is none specified. */
00070 
00071 XML_Parser XMLPARSEAPI
00072 XML_ParserCreate(const XML_Char *encoding);
00073 
00074 
00075 /* atts is array of name/value pairs, terminated by 0;
00076    names and values are 0 terminated. */
00077 
00078 typedef void (*XML_StartElementHandler)(void *userData,
00079                                         const XML_Char *name,
00080                                         const XML_Char **atts);
00081 
00082 typedef void (*XML_EndElementHandler)(void *userData,
00083                                       const XML_Char *name);
00084 
00085 /* s is not 0 terminated. */
00086 typedef void (*XML_CharacterDataHandler)(void *userData,
00087                                          const XML_Char *s,
00088                                          int len);
00089 
00090 /* target and data are 0 terminated */
00091 typedef void (*XML_ProcessingInstructionHandler)(void *userData,
00092                                                  const XML_Char *target,
00093                                                  const XML_Char *data);
00094 
00095 /* This is called for any characters in the XML document for
00096 which there is no applicable handler.  This includes both
00097 characters that are part of markup which is of a kind that is
00098 not reported (comments, markup declarations), or characters
00099 that are part of a construct which could be reported but
00100 for which no handler has been supplied. The characters are passed
00101 exactly as they were in the XML document except that
00102 they will be encoded in UTF-8.  Line boundaries are not normalized.
00103 Note that a byte order mark character is not passed to the default handler.
00104 If a default handler is set, internal entity references
00105 are not expanded. There are no guarantees about
00106 how characters are divided between calls to the default handler:
00107 for example, a comment might be split between multiple calls. */
00108 
00109 typedef void (*XML_DefaultHandler)(void *userData,
00110                                    const XML_Char *s,
00111                                    int len);
00112 
00113 /* This is called for a declaration of an unparsed (NDATA)
00114 entity.  The base argument is whatever was set by XML_SetBase.
00115 The entityName, systemId and notationName arguments will never be null.
00116 The other arguments may be. */
00117 
00118 typedef void (*XML_UnparsedEntityDeclHandler)(void *userData,
00119                                               const XML_Char *entityName,
00120                                               const XML_Char *base,
00121                                               const XML_Char *systemId,
00122                                               const XML_Char *publicId,
00123                                               const XML_Char *notationName);
00124 
00125 /* This is called for a declaration of notation.
00126 The base argument is whatever was set by XML_SetBase.
00127 The notationName will never be null.  The other arguments can be. */
00128 
00129 typedef void (*XML_NotationDeclHandler)(void *userData,
00130                                         const XML_Char *notationName,
00131                                         const XML_Char *base,
00132                                         const XML_Char *systemId,
00133                                         const XML_Char *publicId);
00134 
00135 /* This is called for a reference to an external parsed general entity.
00136 The referenced entity is not automatically parsed.
00137 The application can parse it immediately or later using
00138 XML_ExternalEntityParserCreate.
00139 The parser argument is the parser parsing the entity containing the reference;
00140 it can be passed as the parser argument to XML_ExternalEntityParserCreate.
00141 The systemId argument is the system identifier as specified in the entity declaration;
00142 it will not be null.
00143 The base argument is the system identifier that should be used as the base for
00144 resolving systemId if systemId was relative; this is set by XML_SetBase;
00145 it may be null.
00146 The publicId argument is the public identifier as specified in the entity declaration,
00147 or null if none was specified; the whitespace in the public identifier
00148 will have been normalized as required by the XML spec.
00149 The openEntityNames argument is a space-separated list of the names of the entities
00150 that are open for the parse of this entity (including the name of the referenced
00151 entity); this can be passed as the openEntityNames argument to
00152 XML_ExternalEntityParserCreate; openEntityNames is valid only until the handler
00153 returns, so if the referenced entity is to be parsed later, it must be copied.
00154 The handler should return 0 if processing should not continue because of
00155 a fatal error in the handling of the external entity.
00156 In this case the calling parser will return an XML_ERROR_EXTERNAL_ENTITY_HANDLING
00157 error.
00158 Note that unlike other handlers the first argument is the parser, not userData. */
00159 
00160 typedef int (*XML_ExternalEntityRefHandler)(XML_Parser parser,
00161                                             const XML_Char *openEntityNames,
00162                                             const XML_Char *base,
00163                                             const XML_Char *systemId,
00164                                             const XML_Char *publicId);
00165 
00166 /* This structure is filled in by the XML_UnknownEncodingHandler
00167 to provide information to the parser about encodings that are unknown
00168 to the parser.
00169 The map[b] member gives information about byte sequences
00170 whose first byte is b.
00171 If map[b] is c where c is >= 0, then b by itself encodes the Unicode scalar value c.
00172 If map[b] is -1, then the byte sequence is malformed.
00173 If map[b] is -n, where n >= 2, then b is the first byte of an n-byte
00174 sequence that encodes a single Unicode scalar value.
00175 The data member will be passed as the first argument to the convert function.
00176 The convert function is used to convert multibyte sequences;
00177 s will point to a n-byte sequence where map[(unsigned char)*s] == -n.
00178 The convert function must return the Unicode scalar value
00179 represented by this byte sequence or -1 if the byte sequence is malformed.
00180 The convert function may be null if the encoding is a single-byte encoding,
00181 that is if map[b] >= -1 for all bytes b.
00182 When the parser is finished with the encoding, then if release is not null,
00183 it will call release passing it the data member;
00184 once release has been called, the convert function will not be called again.
00185 
00186 Expat places certain restrictions on the encodings that are supported
00187 using this mechanism.
00188 
00189 1. Every ASCII character that can appear in a well-formed XML document,
00190 other than the characters
00191 
00192   $@\^`{}~
00193 
00194 must be represented by a single byte, and that byte must be the
00195 same byte that represents that character in ASCII.
00196 
00197 2. No character may require more than 4 bytes to encode.
00198 
00199 3. All characters encoded must have Unicode scalar values <= 0xFFFF,
00200 (ie characters that would be encoded by surrogates in UTF-16
00201 are  not allowed).  Note that this restriction doesn't apply to
00202 the built-in support for UTF-8 and UTF-16.
00203 
00204 4. No Unicode character may be encoded by more than one distinct sequence
00205 of bytes. */
00206 
00207 typedef struct {
00208   int map[256];
00209   void *data;
00210   int (*convert)(void *data, const char *s);
00211   void (*release)(void *data);
00212 } XML_Encoding;
00213 
00214 /* This is called for an encoding that is unknown to the parser.
00215 The encodingHandlerData argument is that which was passed as the
00216 second argument to XML_SetUnknownEncodingHandler.
00217 The name argument gives the name of the encoding as specified in
00218 the encoding declaration.
00219 If the callback can provide information about the encoding,
00220 it must fill in the XML_Encoding structure, and return 1.
00221 Otherwise it must return 0.
00222 If info does not describe a suitable encoding,
00223 then the parser will return an XML_UNKNOWN_ENCODING error. */
00224 
00225 typedef int (*XML_UnknownEncodingHandler)(void *encodingHandlerData,
00226                                           const XML_Char *name,
00227                                           XML_Encoding *info);
00228 
00229 void XMLPARSEAPI
00230 XML_SetElementHandler(XML_Parser parser,
00231                       XML_StartElementHandler start,
00232                       XML_EndElementHandler end);
00233 
00234 void XMLPARSEAPI
00235 XML_SetCharacterDataHandler(XML_Parser parser,
00236                             XML_CharacterDataHandler handler);
00237 
00238 void XMLPARSEAPI
00239 XML_SetProcessingInstructionHandler(XML_Parser parser,
00240                                     XML_ProcessingInstructionHandler handler);
00241 
00242 void XMLPARSEAPI
00243 XML_SetDefaultHandler(XML_Parser parser,
00244                       XML_DefaultHandler handler);
00245 
00246 void XMLPARSEAPI
00247 XML_SetUnparsedEntityDeclHandler(XML_Parser parser,
00248                                  XML_UnparsedEntityDeclHandler handler);
00249 
00250 void XMLPARSEAPI
00251 XML_SetNotationDeclHandler(XML_Parser parser,
00252                            XML_NotationDeclHandler handler);
00253 
00254 void XMLPARSEAPI
00255 XML_SetExternalEntityRefHandler(XML_Parser parser,
00256                                 XML_ExternalEntityRefHandler handler);
00257 
00258 void XMLPARSEAPI
00259 XML_SetUnknownEncodingHandler(XML_Parser parser,
00260                               XML_UnknownEncodingHandler handler,
00261                               void *encodingHandlerData);
00262 
00263 /* This can be called within a handler for a start element, end element,
00264 processing instruction or character data.  It causes the corresponding
00265 markup to be passed to the default handler.
00266 Within the expansion of an internal entity, nothing will be passed
00267 to the default handler, although this usually will not happen since
00268 setting a default handler inhibits expansion of internal entities. */
00269 void XMLPARSEAPI XML_DefaultCurrent(XML_Parser parser);
00270 
00271 /* This value is passed as the userData argument to callbacks. */
00272 void XMLPARSEAPI
00273 XML_SetUserData(XML_Parser parser, void *userData);
00274 
00275 /* Returns the last value set by XML_SetUserData or null. */
00276 #define XML_GetUserData(parser) (*(void **)(parser))
00277 
00278 /* If this function is called, then the parser will be passed
00279 as the first argument to callbacks instead of userData.
00280 The userData will still be accessible using XML_GetUserData. */
00281 
00282 void XMLPARSEAPI
00283 XML_UseParserAsHandlerArg(XML_Parser parser);
00284 
00285 /* Sets the base to be used for resolving relative URIs in system identifiers in
00286 declarations.  Resolving relative identifiers is left to the application:
00287 this value will be passed through as the base argument to the
00288 XML_ExternalEntityRefHandler, XML_NotationDeclHandler
00289 and XML_UnparsedEntityDeclHandler. The base argument will be copied.
00290 Returns zero if out of memory, non-zero otherwise. */
00291 
00292 int XMLPARSEAPI
00293 XML_SetBase(XML_Parser parser, const XML_Char *base);
00294 
00295 const XML_Char XMLPARSEAPI *
00296 XML_GetBase(XML_Parser parser);
00297 
00298 /* Parses some input. Returns 0 if a fatal error is detected.
00299 The last call to XML_Parse must have isFinal true;
00300 len may be zero for this call (or any other). */
00301 int XMLPARSEAPI
00302 XML_Parse(XML_Parser parser, const char *s, int len, int isFinal);
00303 
00304 void XMLPARSEAPI *
00305 XML_GetBuffer(XML_Parser parser, int len);
00306 
00307 int XMLPARSEAPI
00308 XML_ParseBuffer(XML_Parser parser, int len, int isFinal);
00309 
00310 /* Creates an XML_Parser object that can parse an external general entity;
00311 openEntityNames is a space-separated list of the names of the entities that are open
00312 for the parse of this entity (including the name of this one);
00313 encoding is the externally specified encoding,
00314 or null if there is no externally specified encoding.
00315 This can be called at any point after the first call to an ExternalEntityRefHandler
00316 so longer as the parser has not yet been freed.
00317 The new parser is completely independent and may safely be used in a separate thread.
00318 The handlers and userData are initialized from the parser argument.
00319 Returns 0 if out of memory.  Otherwise returns a new XML_Parser object. */
00320 XML_Parser XMLPARSEAPI
00321 XML_ExternalEntityParserCreate(XML_Parser parser,
00322                                const XML_Char *openEntityNames,
00323                                const XML_Char *encoding);
00324 
00325 enum XML_Error {
00326   XML_ERROR_NONE,
00327   XML_ERROR_NO_MEMORY,
00328   XML_ERROR_SYNTAX,
00329   XML_ERROR_NO_ELEMENTS,
00330   XML_ERROR_INVALID_TOKEN,
00331   XML_ERROR_UNCLOSED_TOKEN,
00332   XML_ERROR_PARTIAL_CHAR,
00333   XML_ERROR_TAG_MISMATCH,
00334   XML_ERROR_DUPLICATE_ATTRIBUTE,
00335   XML_ERROR_JUNK_AFTER_DOC_ELEMENT,
00336   XML_ERROR_PARAM_ENTITY_REF,
00337   XML_ERROR_UNDEFINED_ENTITY,
00338   XML_ERROR_RECURSIVE_ENTITY_REF,
00339   XML_ERROR_ASYNC_ENTITY,
00340   XML_ERROR_BAD_CHAR_REF,
00341   XML_ERROR_BINARY_ENTITY_REF,
00342   XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF,
00343   XML_ERROR_MISPLACED_XML_PI,
00344   XML_ERROR_UNKNOWN_ENCODING,
00345   XML_ERROR_INCORRECT_ENCODING,
00346   XML_ERROR_UNCLOSED_CDATA_SECTION,
00347   XML_ERROR_EXTERNAL_ENTITY_HANDLING
00348 };
00349 
00350 /* If XML_Parse or XML_ParseBuffer have returned 0, then XML_GetErrorCode
00351 returns information about the error. */
00352 
00353 enum XML_Error XMLPARSEAPI XML_GetErrorCode(XML_Parser parser);
00354 
00355 /* These functions return information about the current parse location.
00356 They may be called when XML_Parse or XML_ParseBuffer return 0;
00357 in this case the location is the location of the character at which
00358 the error was detected.
00359 They may also be called from any other callback called to report
00360 some parse event; in this the location is the location of the first
00361 of the sequence of characters that generated the event. */
00362 
00363 int XMLPARSEAPI XML_GetCurrentLineNumber(XML_Parser parser);
00364 int XMLPARSEAPI XML_GetCurrentColumnNumber(XML_Parser parser);
00365 long XMLPARSEAPI XML_GetCurrentByteIndex(XML_Parser parser);
00366 
00367 /* For backwards compatibility with previous versions. */
00368 #define XML_GetErrorLineNumber XML_GetCurrentLineNumber
00369 #define XML_GetErrorColumnNumber XML_GetCurrentColumnNumber
00370 #define XML_GetErrorByteIndex XML_GetCurrentByteIndex
00371 
00372 /* Frees memory used by the parser. */
00373 void XMLPARSEAPI
00374 XML_ParserFree(XML_Parser parser);
00375 
00376 /* Returns a string describing the error. */
00377 const XML_LChar XMLPARSEAPI *XML_ErrorString(int code);
00378 
00379 #ifdef __cplusplus
00380 }
00381 #endif
00382 
00383 #endif /* not XmlParse_INCLUDED */

Generated at Thu Feb 26 21:52:28 2004 for torcs by doxygen 1.3.3 written by Dimitri van Heesch, © 1997-1999
TORCS © Eric Espié 1999, 2002.