source: protocols/jabber/xmlparse.h @ df70eafa

Last change on this file since df70eafa was b7d3cc34, checked in by Wilmer van der Gaast <wilmer@…>, at 2005-11-06T18:23:18Z

Initial repository (0.99 release tree)

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