Expat

     /***********************************************************
      * outline.c
      *
      * Copyright 1999, Clark Cooper
      * All rights reserved.
      *
      * This program is free software; you can redistribute it
      * and/or modify it under the terms of the license contained
      * in the COPYING file that comes with the expat distribution.
      *
      * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
      * KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
      * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
      * PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS
      * OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
      * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
      * OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH
      * THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
      *
      * Read an XML document from standard input and print an
      * element outline on standard output.  Must be used with
      * Expat compiled for UTF-8 output.
      */
     
     
     #include <stdio.h>
     #include <expat.h>
     
     #if defined(__amigaos__) && defined(__USE_INLINE__)
     #  include <proto/expat.h>
     #endif
     
     #ifdef XML_LARGE_SIZE
     #  if defined(XML_USE_MSC_EXTENSIONS) && _MSC_VER < 1400
     #    define XML_FMT_INT_MOD "I64"
     #  else
     #    define XML_FMT_INT_MOD "ll"
     #  endif
     #else
     #  define XML_FMT_INT_MOD "l"
     #endif
     
     #define BUFFSIZE        8192
     
     char Buff[BUFFSIZE];
     
     int Depth;
     
     static void XMLCALL
     start (void *data, const char *element, const char **attribute)
     {
       for (int i = 0; i < Depth; i++)
         printf("  ");
     
       printf("%s", element);
     
       for (int i = 0; attribute[i]; i += 2)
         printf(" %s='%s'", attribute[i], attribute[i + 1]);
     
       printf("\n");
       Depth++;
     }
     
     static void XMLCALL
     end (void *data, const char *el)
     {
       Depth--;
     }
     
     int
     main (int argc, char *argv[])
     {
       XML_Parser p = XML_ParserCreate(NULL);
       if (! p)
         {
           fprintf(stderr, "Couldn't allocate memory for parser\n");
           exit(-1);
         }
     
       XML_SetElementHandler(p, start, end);
     
       for (;;)
         {
           int done;
           int len;
     
           len = (int)fread(Buff, 1, BUFFSIZE, stdin);
           if (ferror(stdin))
             {
               fprintf(stderr, "Read error\n");
               exit(-1);
             }
         done = feof(stdin);
     
         if (XML_Parse(p, Buff, len, done) == XML_STATUS_ERROR)
           {
             fprintf(stderr,
                     "Parse error at line %" XML_FMT_INT_MOD "u:\n%s\n",
                     XML_GetCurrentLineNumber(p),
                     XML_ErrorString(XML_GetErrorCode(p)));
             exit(-1);
           }
     
           if (done)
             break;
         }
       XML_ParserFree(p);
       return 0;
     }

     #include <expat.h>
     
     #ifndef XMLCALL
     #  if defined(_MSC_EXTENSIONS) && !defined(__BEOS__) &&
           !defined(__CYGWIN__)
     #    define XMLCALL __cdecl
     #  elif defined(__GNUC__)
     #    define XMLCALL __attribute__((cdecl))
     #  else
     #    define XMLCALL
     #  endif
     #endif

     $ ./configure
     $ make
     $ make install

     #include <expat.h>

     CC=cc
     LDFLAGS=
     LIBS= -lexpat
     xmlapp: xmlapp.o
             $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS)

     CC=cc
     CFLAGS= -I/home/me/mystuff/include
     LDFLAGS=
     LIBS= -L/home/me/mystuff/lib -lexpat
     xmlapp: xmlapp.o
             $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS)

     void
     init_info (Parseinfo *info)
     {
       info->skip  = 0;
       info->depth = 1;
       /* Other initializations here */
     }
     
     void XMLCALL
     rawstart (void *data, const char *el, const char **attr)
     {
       Parseinfo *inf = (Parseinfo *) data;
     
       if (! inf->skip)
         {
           if (should_skip(inf, el, attr))
             inf->skip = inf->depth;
           else
             start(inf, el, attr); /* This does rest of start handling */
         }
     
       inf->depth++;
     }
     
     void XMLCALL
     rawend (void *data, const char *el)
     {
       Parseinfo *inf = (Parseinfo *) data;
     
       inf->depth--;
     
       if (! inf->skip)
         end(inf, el);              /* This does rest of end handling */
     
       if (inf->skip == inf->depth)
         inf->skip = 0;
     }

     static int wrong_version;
     static XML_Parser parser;
     
     static void XMLCALL
     xmldecl_handler(void            *userData,
                     const XML_Char  *version,
                     const XML_Char  *encoding,
                     int              standalone)
     {
       static const XML_Char Version_1_0[] = { '1', '.', '0', 0 };
     
       int i;
     
       for (i=0; i<(sizeof(Version_1_0) / sizeof(Version_1_0[0])); ++i)
         {
           if (version[i] != Version_1_0[i])
             {
               wrong_version = 1;
               /* also clear all other handlers: */
               XML_SetCharacterDataHandler(parser, NULL);
               ...
               return;
             }
         }
       ...
     }

     <?xml version="1.0" encoding="ISO-8859-2"?>

     <?xml encoding="Big5"?>

     fd = open_input()
     p  = create_parser()
     
     if parse_xml(p, fd)
       {
         /* suspended */
     
         int suspended = 1;
     
         while (suspended)
           {
             do_something_else()
             if ready_to_resume()
               {
                 suspended = continue_parsing(p, fd);
               }
           }
       }

     #define BUFF_SIZE 10240
     
     /* Parse a document from the open file descriptor 'fd' until
        the parse is complete (the document has been completely
        parsed, or there's been an error), or the parse is stopped.
        Return non-zero when the parse is merely suspended. */
     
     int
     parse_xml (XML_Parser p, int fd)
     {
       for (;;)
         {
           int last_chunk;
           int bytes_read;
           enum XML_Status status;
     
           void *buff = XML_GetBuffer(p, BUFF_SIZE);
           if (buff == NULL)
             {
              /* handle error... */
              return 0;
             }
         bytes_read = read(fd, buff, BUFF_SIZE);
         if (bytes_read < 0)
           {
             /* handle error... */
             return 0;
           }
         status = XML_ParseBuffer(p, bytes_read, bytes_read == 0);
         switch (status)
           {
             case XML_STATUS_ERROR:
               /* handle error... */
               return 0;
             case XML_STATUS_SUSPENDED:
               return 1;
           }
           if (bytes_read == 0)
             return 0;
         }
     }

     /* Continue parsing a document which had been suspended.
        The 'p' and 'fd' arguments are the same as passed to
        parse_xml().  Return non-zero when the parse is
        suspended. */
     int
     continue_parsing (XML_Parser p, int fd)
     {
       enum XML_Status status = XML_ResumeParser(p);
       switch (status)
         {
           case XML_STATUS_ERROR:
             /* handle error... */
             return 0;
           case XML_ERROR_NOT_SUSPENDED:
             /* handle error... */
             return 0;.
           case XML_STATUS_SUSPENDED:
             return 1;
         }
       return parse_xml(p, fd);
     }

— Enumeration: XML_Status

Constants used as return values to indicate success or failure.

— Enumerated Constant: XML_STATUS_ERROR
— Enumerated Constant: XML_STATUS_OK
— Enumerated Constant: XML_STATUS_SUSPENDED

Constants of type enum XML_Status.

— Enumeration: XML_Error

Constants used to specify an error type.

— Enumerated Constant: XML_ERROR_NONE

Constant of type enum XML_Status. No error.

— Enumerated Constant: XML_ERROR_NO_MEMORY

Constant of type enum XML_Status. Out of memory.

— Enumerated Constant: XML_ERROR_SYNTAX

Constant of type enum XML_Status. Syntax error.

— Enumerated Constant: XML_ERROR_NO_ELEMENTS

Constant of type enum XML_Status. No element found.

— Enumerated Constant: XML_ERROR_INVALID_TOKEN

Constant of type enum XML_Status. Document not well–formed (invalid token).

— Enumerated Constant: XML_ERROR_UNCLOSED_TOKEN

Constant of type enum XML_Status. Unclosed token.

— Enumerated Constant: XML_ERROR_PARTIAL_CHAR

Constant of type enum XML_Status. Partial character.

— Enumerated Constant: XML_ERROR_TAG_MISMATCH

Constant of type enum XML_Status. Mismatched tag.

— Enumerated Constant: XML_ERROR_DUPLICATE_ATTRIBUTE

Constant of type enum XML_Status. Duplicate attribute.

— Enumerated Constant: XML_ERROR_JUNK_AFTER_DOC_ELEMENT

Constant of type enum XML_Status. Junk after document element.

— Enumerated Constant: XML_ERROR_PARAM_ENTITY_REF

Constant of type enum XML_Status. Illegal parameter entity reference.

— Enumerated Constant: XML_ERROR_UNDEFINED_ENTITY

Constant of type enum XML_Status. Undefined entity.

— Enumerated Constant: XML_ERROR_RECURSIVE_ENTITY_REF

Constant of type enum XML_Status. Recursive entity reference.

— Enumerated Constant: XML_ERROR_ASYNC_ENTITY

Constant of type enum XML_Status. Asynchronous entity.

— Enumerated Constant: XML_ERROR_BAD_CHAR_REF

Constant of type enum XML_Status. Reference to invalid character number.

— Enumerated Constant: XML_ERROR_BINARY_ENTITY_REF

Constant of type enum XML_Status. Reference to binary entity.

— Enumerated Constant: XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF

Constant of type enum XML_Status. Reference to external entity in attribute.

— Enumerated Constant: XML_ERROR_MISPLACED_XML_PI

Constant of type enum XML_Status. XML or text declaration not at start of entity.

— Enumerated Constant: XML_ERROR_UNKNOWN_ENCODING

Constant of type enum XML_Status. Unknown encoding.

— Enumerated Constant: XML_ERROR_INCORRECT_ENCODING

Constant of type enum XML_Status. Encoding specified in XML declaration is incorrect.

— Enumerated Constant: XML_ERROR_UNCLOSED_CDATA_SECTION

Constant of type enum XML_Status. Unclosed CDATA section.

— Enumerated Constant: XML_ERROR_EXTERNAL_ENTITY_HANDLING

Constant of type enum XML_Status. Error in processing external entity reference.

— Enumerated Constant: XML_ERROR_NOT_STANDALONE

Constant of type enum XML_Status. Document is not standalone.

— Enumerated Constant: XML_ERROR_UNEXPECTED_STATE

Constant of type enum XML_Status. Unexpected parser state (send a bug report).

— Enumerated Constant: XML_ERROR_ENTITY_DECLARED_IN_PE

Constant of type enum XML_Status. Entity declared in parameter entity.

— Enumerated Constant: XML_ERROR_FEATURE_REQUIRES_XML_DTD

Constant of type enum XML_Status. Requested feature requires XML_DTD support in Expat.

— Enumerated Constant: XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING

Constant of type enum XML_Status. Cannot change setting once parsing has begun.

— Enumerated Constant: XML_ERROR_UNBOUND_PREFIX

Constant of type enum XML_Status. Unbound prefix.

— Enumerated Constant: XML_ERROR_UNDECLARING_PREFIX

Constant of type enum XML_Status. Must not undeclare prefix.

— Enumerated Constant: XML_ERROR_INCOMPLETE_PE

Constant of type enum XML_Status. Incomplete markup in parameter entity.

— Enumerated Constant: XML_ERROR_XML_DECL

Constant of type enum XML_Status. XML declaration not well–formed.

— Enumerated Constant: XML_ERROR_TEXT_DECL

Constant of type enum XML_Status. Text declaration not well–formed.

— Enumerated Constant: XML_ERROR_PUBLICID

Constant of type enum XML_Status. Illegal character(s) in public identifier.

— Enumerated Constant: XML_ERROR_SUSPENDED

Constant of type enum XML_Status. Parser suspended.

— Enumerated Constant: XML_ERROR_NOT_SUSPENDED

Constant of type enum XML_Status. Parser not suspended.

— Enumerated Constant: XML_ERROR_ABORTED

Constant of type enum XML_Status. Parsing aborted.

— Enumerated Constant: XML_ERROR_FINISHED

Constant of type enum XML_Status. Parsing finished.

— Enumerated Constant: XML_ERROR_SUSPEND_PE

Constant of type enum XML_Status. Cannot suspend in external parameter entity.

— Enumerated Constant: XML_ERROR_RESERVED_PREFIX_XML

Constant of type enum XML_Status. Reserved prefix xml must not be undeclared or bound to another namespace name.

— Enumerated Constant: XML_ERROR_RESERVED_PREFIX_XMLNS

Constant of type enum XML_Status. Reserved prefix xmlns must not be declared or undeclared

— Enumerated Constant: XML_ERROR_RESERVED_NAMESPACE_UR

Constant of type enum XML_Status. Prefix must not be bound to one of the reserved namespace names.

— Function: XML_Parser XML_ParserCreate (const XML_Char * encoding)

Construct a new parser. If encoding is non–NULL, it specifies a character encoding to use for the document. This overrides the document encoding declaration. There are four built–in encodings:

          US-ASCII
          UTF-8
          UTF-16
          ISO-8859-1

Any other value will invoke XML_UnknownEncodingHandler.

— Function: XML_Parser XML_ParserCreateNS (const XML_Char * encoding, XML_Char sep)

Construct a new parser that has namespace processing in effect. Namespace expanded element names and attribute names are returned as a concatenation of the namespace URI, sep, and the local part of the name.

This means that we should pick a character for sep that can't be part of a legal URI. There is a special case when sep is the null character \0: the namespace URI and the local part will be concatenated without any separator—this is intended to support RDF processors. It is a programming error to use the null separator with namespace triplets.

— Function: XML_Parser XML_ParserCreate_MM (const XML_Char * encoding, const XML_Memory_Handling_Suite * ms, const XML_Char * sep)

Construct a new parser using the suite of memory handling functions specified in ms. If ms is NULL, then use the standard set of memory management functions. If sep is non–NULL, then namespace processing is enabled in the created parser and the character pointed at by sep is used as the separator between the namespace URI and the local part of the name.

          typedef struct {
            void * ( *malloc_fcn  )(size_t size);
            void * ( *realloc_fcn )(void *ptr, size_t size);
            void   ( *free_fcn    )(void *ptr);
          } XML_Memory_Handling_Suite;

— Function: void XML_ParserFree (XML_Parser p)

Free memory used by the parser. Our application is responsible for freeing any memory associated with user data.

— Function: XML_Bool XML_ParserReset (XML_Parser p, const XML_Char * encoding)

Clean up the memory structures maintained by the parser so that it may be used again. After this has been called, the parser is ready to start parsing a new document. All handlers are cleared from the parser, except for the unknownEncodingHandler. The parser's external state is re–initialized except for the values of ns and ns_triplets. This function may not be used on a parser created using XML_ExternalEntityParserCreate(); it will return XML_FALSE in that case. Returns XML_TRUE on success. Our application is responsible for dealing with any memory associated with user data.

— Enumeration: enum XML_Status

Type of the return values.

XML_STATUS_ERROR

Error.

XML_STATUS_OK

Success.

— Function: enum XML_Status XML_Parse (XML_Parser p, const char * s, int len, int isFinal)

Parse some more of the document.

The string s is a buffer containing part (or perhaps all) of the document. The number of bytes of s that are part of the document is indicated by len. This means that s doesn't have to be zero terminated.

The isFinal parameter informs the parser that this is the last piece of the document. Frequently, the last piece is empty (i.e. len is zero).

If successful return XML_STATUS_OK, otherwise XML_STATUS_ERROR.

— Function: enum XML_Status XML_ParseBuffer (XML_Parser p, int len, int isFinal)

This is just like XML_Parse(), except in this case Expat provides the buffer. By obtaining the buffer from Expat with the XML_GetBuffer() function, the application can avoid double copying of the input.

— Function: void * XML_GetBuffer (XML_Parser p, int len)

Obtain a buffer of size len to read a piece of the document into. Return NULL if Expat can't allocate enough memory for this buffer.

This function has to be called prior to every call to XML_ParseBuffer().

A typical use would look like this:

          #undef BUFF_SIZE
          #define BUFF_SIZE       4096
          XML_Parser       parser = the_parser;
          int              docfd  = the_file_descriptor;
          int              nbytes;
          void *           buff;
          enum XML_Status  status;
          
          for (;;) {
            buff = XML_GetBuffer(parser, BUFF_SIZE);
            if (buff == NULL) {
              /* handle error */
            }
          
            nbytes = read(docfd, buff, BUFF_SIZE);
            if (nbytes < 0) {
              /* handle error */
            }
          
            status = XML_ParseBuffer(parser, nbytes, (0 == nbytes));
            if (XML_STATUS_OK != status) {
              /* handle parse error */
            }
          
            if (0 == nbytes)
              break;
          }

— Function: enum XML_Status XML_StopParser (XML_Parser p, XML_Bool resumable)

Stop parsing causing XML_Parse() or XML_ParseBuffer() to return. Must be called from within a callback handler, except when aborting (when resumable is XML_FALSE) an already suspended parser. Some call–backs may still follow because they would otherwise get lost, including:

• The end element handler for empty elements when stopped in the start element handler.
• The end namespace declaration handler when stopped in the end element handler.
• The character data handler when stopped in the character data handler while making multiple call-backs on a contiguous chunk of characters.

and possibly others.

This can be called from most handlers, including DTD related call–backs, except when parsing an external parameter entity and resumable is XML_TRUE.

If successful return XML_STATUS_OK, otherwise XML_STATUS_ERROR. The possible error codes are:

XML_ERROR_SUSPENDED

When suspending an already suspended parser.

XML_ERROR_FINISHED

When the parser has already finished.

XML_ERROR_SUSPEND_PE

When suspending while parsing an external parameter entity.

Since the stop/resume feature requires application support in the outer parsing loop, it is an error to call this function for a parser not being handled appropriately. using stop for details.

When resumable is XML_TRUE then parsing is suspended, that is, XML_Parse() and XML_ParseBuffer() return XML_STATUS_SUSPENDED. Otherwise, parsing is aborted, that is, XML_Parse() and XML_ParseBuffer() return XML_STATUS_ERROR with error code XML_ERROR_ABORTED.

NOTE This will be applied to the current parser instance only, that is, if there is a parent parser then it will continue parsing when the external entity reference handler returns. It is up to the implementation of that handler to call XML_StopParser() on the parent parser (recursively), if one wants to stop parsing altogether.

When suspended, parsing can be resumed by calling XML_ResumeParser().

NOTE New in Expat 1.95.8.

— Function: enum XML_Status XML_ResumeParser (XML_Parser p)

Resume parsing after it has been suspended with XML_StopParser(). Must not be called from within a handler callback. Return the same status codes of XML_Parse() or XML_ParseBuffer().

An additional error code, XML_ERROR_NOT_SUSPENDED, will be returned if the parser was not currently suspended.

NOTE This must be called on the most deeply nested child parser instance first, and on its parent parser only after the child parser has finished, to be applied recursively until the document entity's parser is restarted. That is, the parent parser will not resume by itself and it is up to the application to call XML_ResumeParser() on it at the appropriate moment.

NOTE New in Expat 1.95.8.

— Enumeration: enum XML_Parsing

Parser status values. Defined symbols are:

          XML_INITIALIZED
          XML_PARSING
          XML_FINISHED
          XML_SUSPENDED

— Struct Typedef: XML_ParsingStatus

The status of a parser. The description of public fields follows.

enum XML_Parsing parsing

The current status of the parser.

XML_Bool finalBuffer

True if the internal buffer holds the final chunk of the document.

— Function: void XML_GetParsingStatus (XML_Parser p, XML_ParsingStatus * status)

Fill the structure referenced by status with the status of the parser with respect to being initialized, parsing, finished, or suspended, and whether the final buffer is being processed.

status must not be NULL.

NOTE New in Expat 1.95.8.

— Function: XML_Parser XML_ExternalEntityParserCreate (XML_Parser p, const XML_Char * context, const XML_Char * encoding)

Construct a new XML_Parser object for parsing an external general entity. context is the context argument passed in a call to a XML_ExternalEntityRefHandler. Other state information such as handlers, user data, namespace processing is inherited from the parser passed as the first argument. So we shouldn't need to call any of the behavior changing functions on this parser (unless we want it to act differently than the parent parser).

— Function Pointer Typedef: XML_ExternalEntityRefHandler

External entity reference handler. Defined as:

          typedef int (* XML_ExternalEntityRefHandler)
             (XML_Parser          parser,
              const XML_Char *    context,
              const XML_Char *    base,
              const XML_Char *    system_id,
              const XML_Char *    public_id);

This handler is also called for processing an external DTD subset if parameter entity parsing is in effect. See XML_SetParamEntityParsing().

The context parameter specifies the parsing context in the format expected by the context argument to XML_ExternalEntityParserCreate(). context is valid only until the handler returns, so if the referenced entity is to be parsed later, it must be copied.

context is NULL only when the entity is a parameter entity, which is how one can differentiate between general and parameter entities.

base is the base to use for relative system identifiers; it is set by XML_SetBase() and may be NULL.

public_id is the public id given in the entity declaration and may be NULL.

system_id is the system identifier specified in the entity declaration and is never NULL.

There are a couple of ways in which this handler differs from others.

1. This handler returns a status indicator (an integer). XML_STATUS_OK should be returned for successful handling of the external entity reference. Returning XML_STATUS_ERROR indicates failure, and causes the calling parser to return an XML_ERROR_EXTERNAL_ENTITY_HANDLING error.
2. Instead of having the user data as its first argument, it receives the parser that encountered the entity reference. This, along with the context parameter, may be used as arguments to a call to XML_ExternalEntityParserCreate(). Using the returned parser, the body of the external entity can be recursively parsed.

Since this handler may be called recursively, it should not be saving information into global or static variables.

— Function: void XML_SetExternalEntityRefHandler (XML_Parser p, XML_ExternalEntityRefHandler h)

Set an external entity reference handler.

— Function: void XML_SetExternalEntityRefHandlerArg (XML_Parser P, void * arg)

Set the argument passed to the XML_ExternalEntityRefHandler. If arg is not NULL, it is the new value passed to the handler set using XML_SetExternalEntityRefHandler(); if arg is NULL, the argument passed to the handler function will be the parser object itself.

NOTE The type of arg and the type of the first argument to the XML_ExternalEntityRefHandler do not match. This function takes a void * to be passed to the handler, while the handler accepts an XML_Parser.

This is a historical accident, but will not be corrected before Expat 2.0 (at the earliest) to avoid causing compiler warnings for code that's known to work with this API. It is the responsibility of the application code to know the actual type of the argument passed to the handler and to manage it properly.

     <?xml version='1.0'?>
     <?xml version='1.0'? encoding='utf-8'>
     <?xml version='1.0'? standalone='yes'>
     <?xml version='1.0'? standalone='no'>

— Function Pointer Typedef: XML_XmlDeclHandler

Handler for XML declarations and also for text declarations discovered in external entities. Defined as:

          typedef void (* XML_XmlDeclHandler)
            (void           *     user_data,
             const XML_Char *     version,
             const XML_Char *     encoding,
             int                  standalone);

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

version is either NULL or references a zero–terminated string representing the XML specification version; such string is always 1.0. The way to distinguish the kind of input is that version will be NULL for text declarations.

encoding is either NULL or references a zero–terminated string representing the character encoding of the document being parsed.

standalone will be:

-1

Indicating that there was no standalone parameter in the declaration.

0

Indicating that standalone was given as no.

+1

Indicating that standalone was given as yes.

— Function: void XML_SetXmlDeclHandler (XML_Parser p, XML_XmlDeclHandler xmldecl)

Set a handler that is called for XML declarations and also for text declarations discovered in external entities.

— Function Pointer Typedef: XML_NotStandaloneHandler

Handler called if the document is not “standalone”. Defined as:

          typedef int (* XML_NotStandaloneHandler) (void * user_data);

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

This handler is called when there is an external subset or a reference to a parameter entity, but it does not have standalone set to yes in an XML declaration.

If this handler returns XML_STATUS_ERROR: the parser will throw an XML_ERROR_NOT_STANDALONE error.

— Function: void XML_SetNotStandaloneHandler (XML_Parser p, XML_NotStandaloneHandler h)

Set a handler that is called if the document is not “standalone”.

     <!DOCTYPE ball [
       <!ELEMENT ball EMPTY>
       <!ATTLIST ball colour CDATA #REQUIRED>
     ]>

     <!DOCTYPE toys SYSTEM 'http://localhost/toys'>
     <!DOCTYPE toys PUBLIC 'The Toys' 'http://localhost/toys'>

— Function Pointer Typedef: XML_StartDoctypeDeclHandler

Handler called at the start of a <!DOCTYPE declaration, before any external or internal subset is parsed. Defined as:

          typedef void (* XML_StartDoctypeDeclHandler)
             (void           *    user_data,
              const XML_Char *    doctype_name,
              const XML_Char *    system_id,
              const XML_Char *    public_id,
              int                 has_internal_subset);

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

doctype_name references a zero–terminated string representing the document type name.

system_id either is NULL or references a zero–terminated string representing the system identifier.

public_id either is NULL or references a zero–terminated string representing the public identifier.

has_internal_subset will be non–zero if the <!DOCTYPE declaration has an internal subset.

— Function: void XML_SetStartDoctypeDeclHandler (XML_Parser P, XML_StartDoctypeDeclHandler H)

Set a handler called at the start of a <!DOCTYPE declaration, before any external or internal subset is parsed.

— Function Pointer Typedef: XML_EndDoctypeDeclHandler

Handler called at the end of a <!DOCTYPE declaration, after parsing any external subset. Defined as:

          typedef void (* XML_EndDoctypeDeclHandler) (void * user_data);

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

— Function: void XML_SetEndDoctypeDeclHandler (XML_Parser P, XML_EndDoctypeDeclHandler H)

Set a handler that is called at the end of a <!DOCTYPE declaration, after parsing any external subset.

— Function: void XML_SetDoctypeDeclHandler (XML_Parser P, XML_StartDoctypeDeclHandler S, XML_EndDoctypeDeclHandler E)

Set both <!DOCTYPE handlers with one call.

     <numbers><one/><two/><three/></numbers>

     <!ELEMENT one     EMPTY>
     <!ELEMENT two     EMPTY>
     <!ELEMENT three   EMPTY>
     <!ELEMENT numbers (one,two,three)>

— Function Pointer Typedef: XML_ElementDeclHandler

Handler for element declarations in the DTD; invoked whenever, while processing a DTD, the parser finds an <!ELEMENT token. Defined as:

          typedef void (* XML_ElementDeclHandler)
            (void *               user_data,
             const XML_Char *     name,
             XML_Content *        model);

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

name references a zero–terminated string holding the name of the element being declared; this pointer is never NULL.

model references a structure describing the element declaration, this pointer is never NULL; it is the application's responsibility to free this data structure using XML_FreeContentModel().

— Function: void XML_SetElementDeclHandler (XML_Parser p, XML_ElementDeclHandler H)

Set or unset a handler for element DTD declarations.

— Function: void XML_FreeContentModel (XML_Parser p, XML_Content * model)

Deallocate the model argument passed to the XML_ElementDeclHandler handler. This function should not be used for any other purpose.

— Enumeration: XML_Content_Type

Used to identify the content type in an element's DTD declaration.

— Enumeration Constant: XML_CTYPE_EMPTY
— Enumeration Constant: XML_CTYPE_ANY
— Enumeration Constant: XML_CTYPE_MIXED
— Enumeration Constant: XML_CTYPE_NAME
— Enumeration Constant: XML_CTYPE_CHOICE
— Enumeration Constant: XML_CTYPE_SEQ

Values of the XML_Content_Type enumeration. See the description of the field type in the structure XML_Content for details.

— Enumeration: XML_Content_Quant

Specify the quantifier used in an element's DTD declaration.

— Enumeration Constant: XML_CQUANT_NONE
— Enumeration Constant: XML_CQUANT_OPT
— Enumeration Constant: XML_CQUANT_REP
— Enumeration Constant: XML_CQUANT_PLUS

Values of the XML_Content_Quant enumeration. An element declaration is described by the values as follows:

XML_CQUANT_NONE

When there is no quantifier.

XML_CQUANT_OPT

When the quantifier ? is used.

XML_CQUANT_REP

When the quantifier * is used. We can imagine REP to stand for “replicated”.

XML_CQUANT_PLUS

When the quantifier + is used.

— Struct Typedef: XML_Content

Instances of this structure type can be: “root elements” when this structure represents an <!ELEMENT declaration; “children elements” when this structure is an element of an array referenced by the children field (see below). Description of public fields follows.

enum XML_Content_Type type

The type of the element described by this instance. When this instance represents a root element, the value is as follows:

               <!ELEMENT THIS EMPTY>
                 ⇒ type == XML_CTYPE_EMPTY
               
               <!ELEMENT THIS ANY>
                 ⇒ type == XML_CTYPE_ANY
               
               <!ELEMENT THIS (#PCDATA)>
                 ⇒ type == XML_CTYPE_MIXED
               
               <!ELEMENT THIS (#PCDATA|THAT)*>
                 ⇒ type == XML_CTYPE_MIXED
               
               <!ELEMENT THIS (THAT|THOSE)>
                 ⇒ type == XML_CTYPE_CHOICE
               
               <!ELEMENT THIS (THAT, THOSE)>
                 ⇒ type == XML_CTYPE_SEQ

when this instance represents a child element, the value of this field is always XML_CTYPE_NAME.

If the type is EMPTY or ANY: quant is XML_CQUANT_NONE and the other fields are zero or NULL.

If the type is MIXED: quant is XML_CQUANT_NONE or XML_CQUANT_REP.

enum XML_Content_Quant quant

The quantifier for the element's content. If this structure represents a root element, the value is as follows:

               <!ELEMENT this (that)>
                 ⇒ quant == XML_CQUANT_NONE
               
               <!ELEMENT this (that)?>
                 ⇒ quant == XML_CQUANT_OPT
               
               <!ELEMENT this (that)*>
                 ⇒ quant == XML_CQUANT_REP
               
               <!ELEMENT this (that)+>
                 ⇒ quant == XML_CQUANT_PLUS

if this structure represents a child element the value is always XML_CQUANT_NONE.

const XML_Char * name

NULL for root elements; for children elements: references a zero–terminated string representing the child's element name.

XML_Content * children

unsigned int numchildren

children is NULL or a pointer to an array of structures describing the children elements; the number of elements in the array is numchildren.

One of the following cases is possible:

• When type is XML_CTYPE_EMPTY or XML_CTYPE_ANY: the array is empty.
• When type is XML_CTYPE_CHOICE or XML_CTYPE_SEQ: the array has a number of entries equal to the number of children elements.
• When type is XML_CTYPE_MIXED and the element's content specification is (#PCDATA): the array is empty.
• When type is XML_CTYPE_MIXED and the element's content specification lists children elements: the array has a number of entries equal to the number of children elements.

— Function Pointer Typedef: XML_AttlistDeclHandler

Handler for attribute list declarations in the DTD; invoked whenever, while processing a DTD, the parser finds an <!ATTLIST token. Defined as:

          typedef void (* XML_AttlistDeclHandler)
            (void *               user_data,
             const XML_Char *     element_name,
             const XML_Char *     attribute_name,
             const XML_Char *     attribute_type,
             const XML_Char *     default_value,
             int                  is_required);

This handler is called for each attribute; so a single <!ATTLIST declaration with multiple attributes declared will generate multiple calls to this handler.

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

element_name references a zero–terminated string representing the name of the element for which the attribute is being declared.

attribute_name references a zero–terminated string representing the attribute name.

attribute_type references a zero–terminated string representing the attribute type; it is the string representing the type in the declaration with whitespace removed.

default_value either is NULL or references a zero–terminated string representing the default value; is_required is true if the attribute is required. These two arguments are interpreted together:

• For #IMPLIED attributes: default_value is NULL and is_required is true.
• For #REQUIRED attributes: default_value is NULL and is_required is false.
• For #FIXED attributes: default_value references a string and is_required is true.

— Function: void XML_SetAttlistDeclHandler (XML_Parser P, XML_AttlistDeclHandler H)

Set a handler for attribute list declarations in the DTD.

     <!NOTATION bouncing SYSTEM 'http://localhost/bouncer'>
     <!NOTATION bouncing PUBLIC 'The Bouncer'>
     <!NOTATION bouncing PUBLIC 'The Bouncer'
        'http://localhost/bouncer'>

— Function Pointer Typedef: XML_NotationDeclHandler

Handler called when parsing a <!NOTATION declaration. Defined as:

          typedef void (* XML_NotationDeclHandler)
             (void           *    user_data,
              const XML_Char *    notation_name,
              const XML_Char *    base,
              const XML_Char *    system_id,
              const XML_Char *    public_id);

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

notation_name references a zero–terminated string representing the notation name.

base is either NULL or references the zero–terminated string set with XML_SetBase().

system_id is either NULL or references a zero–terminated string representing the system identifier.

public_id is either NULL or references a zero–terminated string representing the public identifier.

— Function: void XML_SetNotationDeclHandler (XML_Parser p, XML_NotationDeclHandler h)

Set a handler that receives notation declarations.

     <!-- internal entity -->
     <!ENTITY stuff 'a'>
     
     <!-- external entities -->
     <!ENTITY stuff SYSTEM 'http://localhost/stuff'>
     
     <!ENTITY stuff PUBLIC 'The Stuff' 'http://localhost/stuff'>
     
     <!NOTATION stuffer SYSTEM 'http://localhost/stuffer'>
     <!ENTITY stuff SYSTEM 'http://localhost/stuff' NDATA stuffer>
     
     <!NOTATION stuffer SYSTEM 'http://localhost/stuffer'>
     <!ENTITY stuff PUBLIC 'The Stuff'
       'http://localhost/stuff' NDATA stuffer>

— Function Pointer Typedef: XML_EntityDeclHandler

Handler for entity declarations in the DTD; invoked whenever, while processing a DTD, the parser finds an <!ENTITY token. Defined as:

          typedef void (* XML_EntityDeclHandler)
            (void           * user_data,
             const XML_Char * entity_name,
             int              is_parameter_entity,
             const XML_Char * value,
             int              value_length,
             const XML_Char * base,
             const XML_Char * system_id,
             const XML_Char * public_id,
             const XML_Char * notation_name);

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

entity_name references a zero–terminated string representing the entity name.

The is_parameter_entity argument will be non–zero in the case of parameter entities and zero otherwise.

The value string is not zero–terminated, the length is provided in the value_length parameter; do not use value_length to test for internal entities, since it is legal to have zero–length values, instead check for whether or not value is NULL.

base either is NULL or references a zero–terminated string representing the base set with XML_SetBase().

system_id either is NULL or references a zero–terminated string representing the system literal in a SYSTEM or PUBLIC external identifier.

public_id either is NULL or references a zero–terminated string representing the public literal identifier in a PUBLIC external identifier.

For internal entities: value will be non–NULL and system_id, public_id, and notation_name will all be NULL.

The notation_name argument will have a non–NULL value only for unparsed entity declarations.

— Function: void XML_SetEntityDeclHandler (XML_Parser P, XML_EntityDeclHandler H)

Set a handler that will be called for all entity declarations.

— Function Pointer Typedef: XML_UnparsedEntityDeclHandler

Handler for declarations of unparsed entities; these are entity declarations that have a notation (NDATA) field:

          <!ENTITY logo SYSTEM "images/logo.gif" NDATA gif>

this handler is obsolete and is provided for backwards compatibility. Use instead XML_EntityDeclHandler(). Defined as:

          typedef void (* XML_UnparsedEntityDeclHandler)
             (void           *    user_data,
              const XML_Char *    entity_name,
              const XML_Char *    base,
              const XML_Char *    system_id,
              const XML_Char *    public_id,
              const XML_Char *    notation_name);

— Function: void XML_SetUnparsedEntityDeclHandler (XML_Parser P, XML_UnparsedEntityDeclHandler H)

Set a handler that receives declarations of unparsed entities.

— Function Pointer Typedef: XML_StartElementHandler

Handler for start and empty tags. Defined as:

          typedef void (* XML_StartElementHandler)
             (void           *    user_data,
              const XML_Char *    name,
              const XML_Char **   atts);

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

name references a zero–terminated string representing the element type name.

Attributes are passed to the the start handler as a pointer atts to a vector of char pointers; each attribute seen in a start (or empty) tag occupies 2 consecutive places in this vector: the attribute name followed by the attribute value; these pairs are terminated by a NULL pointer.

Note that an empty tag generates a call to both start and end handlers (in that order).

— Function: void XML_SetStartElementHandler (XML_Parser P, XML_StartElementHandler H)

Set the handler for start and empty tags.

— Function Pointer Typedef: XML_EndElementHandler

Handler for end and empty tags. Defined as:

          typedef void (* XML_EndElementHandler)
             (void           *    user_data,
              const XML_Char *    name);

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

name references a zero–terminated string representing the element type name.

An empty tag generates a call to both start and end handlers.

— Function: void XML_SetEndElementHandler (XML_Parser p, XML_EndElementHandler H)

Set the handler for end (and empty) tags.

— Function: void XML_SetElementHandler (XML_Parser P, XML_StartElementHandler S, XML_EndElementHandler E)

Set handlers for start and end tags with one call.

     <greetings>Hello</greetings>

— Function Pointer Typedef: XML_CharacterDataHandler

Handler for character data. Defined as:

          typedef void (* XML_CharacterDataHandler)
             (void           *    user_data,
              const XML_Char *    string,
              int                 string_len);

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

The string the handler receives through string is not zero–terminated; we have to use the string_len argument to deal with the end of the string.

A single block of contiguous text free of markup may still result in a sequence of calls to this handler. In other words, if we are searching for a pattern in the text, it may be split across calls to this handler.

— Function: void XML_SetCharacterDataHandler (XML_Parser p, XML_CharacterDataHandler handler)

Set a text handler. Setting this handler to NULL may not immediately terminate callbacks if the parser is currently processing such a single block of contiguous markup–free text, as the parser will continue calling back until the end of the block is reached.

     <!-- this text means nothing -->

— Function Pointer Typedef: XML_CommentHandler

Handler for comments. Defined as:

          typedef void (* XML_CommentHandler)
             (void           *    user_data,
              const XML_Char *    data);

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

data is either NULL or references a zero–terminated string representing the text of the comment.

— Function: void XML_SetCommentHandler (XML_Parser p, XML_CommentHandler handler)

Set a handler for comments.

     <![CDATA[<stuff>interpreted literally</stuff>]]>

— Function Pointer Typedef: XML_StartCdataSectionHandler

Handler called when the <![CDATA[ token is parsed. Defined as:

          typedef void (* XML_StartCdataSectionHandler) (void * user_data);

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

— Function: void XML_SetStartCdataSectionHandler (XML_Parser p, XML_StartCdataSectionHandler start)

Set a handler that gets called at the beginning of a CDATA section.

— Function Pointer Typedef: XML_EndCdataSectionHandler

Handler called when the ]]> token ending a CDATA section is parsed. Defined as:

          typedef void (* XML_EndCdataSectionHandler) (void * user_data);

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

— Function: void XML_SetEndCdataSectionHandler (XML_Parser P, XML_EndCdataSectionHandler H)

Set a handler that gets called at the end of a CDATA section.

— Function: void XML_SetCdataSectionHandler (XML_Parser P, XML_StartCdataSectionHandler S, XML_EndCdataSectionHandler E)

Set both CDATA handlers: the one called at the start and the one called at the end.

— Function Pointer Typedef: XML_StartNamespaceDeclHandler

Handler called when a namespace is declared. Defined as:

          typedef void (* XML_StartNamespaceDeclHandler)
             (void           *    user_data,
              const XML_Char *    prefix,
              const XML_Char *    uri);

Namespace declarations occur inside start tags; but the namespace declaration start handler is called before the start tag handler for each namespace declared in that start tag.

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

prefix is either NULL or references a zero–terminated string representing the namespace prefix.

uri is either NULL or references a zero–terminated string representing the namespace URI.

— Function: void XML_SetStartNamespaceDeclHandler (XML_Parser P, XML_StartNamespaceDeclHandler H)

Set a handler to be called when a namespace is declared.

— Function Pointer Typedef: XML_EndNamespaceDeclHandler

Handler called when leaving the scope of a namespace declaration. Defined as:

          typedef void (* XML_EndNamespaceDeclHandler)
             (void           *    user_data,
              const XML_Char *    prefix);

This handler will be called, for each namespace declaration, after the handler for the end tag of the element in which the namespace was declared.

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

prefix is either NULL or references a zero–terminated string representing the namespace prefix.

— Function: void XML_SetEndNamespaceDeclHandler (XML_Parser P, XML_EndNamespaceDeclHandler E)

Set a handler to be called when leaving the scope of a namespace declaration.

— Function: void XML_SetNamespaceDeclHandler (XML_Parser P, XML_StartNamespaceDeclHandler S, XML_EndNamespaceDeclHandler E)

Set both namespace declaration handlers with a single call.

— Function Pointer Typedef: XML_DefaultHandler

Handler called for any characters in the document which would not otherwise be handled; this includes both data for which no handlers can be set (like some kinds of DTD declarations) and data which could be reported but which currently has no handler set. Defined as:

          typedef void (* XML_DefaultHandler)
             (void           *    user_data,
              const XML_Char *    string,
              int                 string_len);

The characters are passed exactly as they were present in the XML document except that they will be encoded in UTF-8 or UTF-16; note that a byte order mark character is not passed to the default handler. Line boundaries are not normalized.

There are no guarantees about how characters are divided between calls to the default handler: for example, a comment might be split between multiple calls.

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

string references a not zero–terminated string holding string_len characters representing the input data.

See also XML_DefaultCurrent().

— Function: void XML_SetDefaultHandler (XML_Parser P, XML_DefaultHandler H)

Set a handler for any characters in the document which wouldn't otherwise be handled. Setting the handler with this call has the side effect of turning off expansion of references to internally defined general entities; instead these references are passed to the default handler.

— Function: void XML_SetDefaultHandlerExpand (XML_Parser P, XML_DefaultHandler H)

Set a default handler, but does not inhibit the expansion of internal entity references. The entity reference will not be passed to the default handler.

See also XML_DefaultCurrent().

— Function: void XML_DefaultCurrent (XML_Parser p)

This function can be called within a handler for a start element, end element, processing instruction or character data. It causes the corresponding markup to be passed to the default handler set by XML_SetDefaultHandler() or XML_SetDefaultHandlerExpand(). It does nothing if there is not a default handler.

— Function Pointer Typedef: XML_SkippedEntityHandler

Handler for skipped entities. Defined as:

          typedef void (* XML_SkippedEntityHandler)
             (void           *    user_data,
              const XML_Char *    entity_name,
              int                 is_parameter_entity);

This is called in two situations:

1. An entity reference is encountered for which no declaration has been read and this is not an error.
2. An internal entity reference is read, but not expanded, because XML_SetDefaultHandler() has been called.

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

entity_name references a zero–terminated string representing the entity name.

is_parameter_entity is non–zero for a parameter entity and zero for a general entity.

NOTE Skipped parameter entities in declarations and skipped general entities in attribute values cannot be reported, because the event would be out of sync with the reporting of the declarations or attribute values.

— Function: void XML_SetSkippedEntityHandler (XML_Parser P, XML_SkippedEntityHandler H)

Set a skipped entity handler.

     <?scheme (display 123)?>

— Function Pointer Typedef: XML_ProcessingInstructionHandler

Handler for processing instructions. Defined as:

          typedef void (* XML_ProcessingInstructionHandler)
             (void           *    user_data,
              const XML_Char *    target,
              const XML_Char *    data);

The target is the first word in the processing instruction. The data is the rest of the characters in it after skipping all whitespace after the initial word.

user_data references the custom value registered with XML_SetUserData() or XML_UseParserAsHandlerArg().

target references a zero–terminated string representing the processing instruction target.

data references a zero–terminated string representing the processing instruction data.

— Function: void XML_SetProcessingInstructionHandler (XML_Parser P, XML_ProcessingInstructionHandler H)

Set a handler for processing instructions.

— Function Pointer Typedef: XML_UnknownEncodingHandler

Handler to deal with encodings other than the built in set. Defined as:

          typedef int (* XML_UnknownEncodingHandler)
             (void           *    handler_data,
              const XML_Char *    name,
              XML_Encoding   *    info);

If the handler knows how to deal with an encoding with the given name, it should fill in the info data structure and return XML_STATUS_OK; otherwise it should return XML_STATUS_ERROR.

The handler will be called at most once per parsed (external) entity.

handler_data is the custom pointer registered with XML_SetUnknownEncodingHandler().

name references a zero–terminated string representing the encoding name.

info references a data structure to be filled with stuff needed to handle the encoding.

— Struct Typedef: XML_Encoding

Structure representing an encoding.

int map[256]

The map array contains information for every possible leading byte in a byte sequence.

• If the corresponding value is N >= 0, then it's a single byte sequence and the byte encodes the Unicode code point N.
• If the value is -1, then that byte is invalid as the initial byte in a sequence.
• If the value is -N, then N is the number of bytes in the sequence and the actual conversion is accomplished by a call to the function pointed at by the field convert.

void * data

Custom pointer used as first argument to the functions referenced by the fields convert and release.

int (* convert) (void * data, const char * str)

Pointer to the function used to convert a sequence of input characters; the convert pointer may be NULL if there are only single byte codes. The string str is not zero–terminated and points at the sequence of bytes to be converted. This function may return -1 if the sequence itself is invalid.

void (* release) (void * data)

The function pointed at by release is called by the parser when it is finished with the encoding; it may be NULL.

— Function: void XML_SetUnknownEncodingHandler (XML_Parser P, XML_UnknownEncodingHandler H, void * encoding_data)

Set a handler to deal with encodings other than the built in set. This function should be called before XML_Parse() or XML_ParseBuffer() have been called on the given parser.

The optional application data pointer encoding_data will be passed back to the handler.

— Function: enum XML_Error XML_GetErrorCode (XML_Parser p)

Return what type of error has occurred.

— Function: const XML_LChar * XML_ErrorString (enum XML_Error code)

Return a string describing the error corresponding to code. The code should be one of the enums that can be returned from XML_GetErrorCode().

— Function: XML_Index XML_GetCurrentByteIndex (XML_Parser p)

Return the byte offset of the position. This always corresponds to the values returned by XML_GetCurrentLineNumber() and XML_GetCurrentColumnNumber().

— Function: XML_Size XML_GetCurrentLineNumber (XML_Parser p)

Return the line number of the position. The first line is reported as 1.

— Function: XML_Size XML_GetCurrentColumnNumber (XML_Parser p)

Return the offset, from the beginning of the current line, of the position.

— Function: int XML_GetCurrentByteCount (XML_Parser p)

Return the number of bytes in the current event, 0 if the event is inside a reference to an internal entity and for the end–tag event for empty element tags (the later can be used to distinguish empty–element tags from empty elements using separate start and end tags).

— Function: const char * XML_GetInputContext (XML_Parser p, int * offset, int * size)

Return the parser's input buffer, sets the integer pointed at by offset to the offset within this buffer of the current parse position, and set the integer pointed at by size to the size of the returned buffer.

This should only be called from within a handler during an active parse and the returned buffer should only be referred to from within the handler that made the call. This input buffer contains the untranslated bytes of the input.

Only a limited amount of context is kept, so if the event triggering a call spans over a very large amount of input, the actual parse position may be before the beginning of the buffer.

If XML_CONTEXT_BYTES is not defined, this will always return NULL.

— Function: XML_LChar * XML_ExpatVersion (void)

Return the library version as a string (e.g. expat_1.95.1).

— Struct Typedef: XML_Expat_Version

Type of structure representing the Expat version. Description of public fields follows.

int major

The major version number.

int minor

The minor version number.

int micro

The micro version number.

— Function: struct XML_Expat_Version XML_ExpatVersionInfo (void)

Return the library version information as a structure (yes, the whole structure is the returned value).

— Macro: XML_MAJOR_VERSION
— Macro: XML_MINOR_VERSION
— Macro: XML_MICRO_VERSION

These macros are defined to support compile–time tests of the library version. Testing these constants is currently the best way to determine if particular parts of the Expat API are available.

— Enumeration: XML_FeatureEnum

Type of values representing Expat features.

— Macro: XML_FEATURE_END
— Macro: XML_FEATURE_UNICODE
— Macro: XML_FEATURE_UNICODE_WCHAR_T
— Macro: XML_FEATURE_DTD
— Macro: XML_FEATURE_CONTEXT_BYTES
— Macro: XML_FEATURE_MIN_SIZE
— Macro: XML_FEATURE_SIZEOF_XML_CHAR
— Macro: XML_FEATURE_SIZEOF_XML_LCHAR
— Macro: XML_FEATURE_NS
— Macro: XML_FEATURE_LARGE_SIZ

Values of the XML_FeatureEnum enumeration representing Expat features.

— Struct Typedef: XML_Feature

Type of the records representing Expat features. Public fields description follows.

enum XML_FeatureEnum feature

A constant representing the feature.

XML_LChar * name

Pointer to a statically allocated string representing the name of the feature.

long int value

A value associated to the feature.

— Function: const XML_Feature * XML_GetFeatureList (void)

Return a list of “feature” records, providing details on how Expat was configured at compile time. Most applications should not need to worry about this, but this information is otherwise not available from Expat. This function allows code that needs to check these features to do so at runtime.

The return value is a pointer to a statically allocated array of XML_Feature, terminated by a record with the feature field set to XML_FEATURE_END and name field set to NULL.

Since an application that requires this kind of information needs to determine the type of character the name points to, records for the XML_FEATURE_SIZEOF_XML_CHAR and XML_FEATURE_SIZEOF_XML_LCHAR will be located at the beginning of the list, followed by XML_FEATURE_UNICODE and XML_FEATURE_UNICODE_WCHAR_T, if they are present at all.

Some features have an associated value. If there isn't an associated value, the value field is set to 0. At this time, the following features have been defined to have values:

XML_FEATURE_SIZEOF_XML_CHAR

The number of bytes occupied by one XML_Char character.

XML_FEATURE_SIZEOF_XML_LCHAR

The number of bytes occupied by one XML_LChar character.

XML_FEATURE_CONTEXT_BYTES

The maximum number of characters of context which can be reported by XML_GetInputContext().

— Function: void * XML_MemMalloc (XML_Parser p, size_t size)

Allocate size bytes of memory using the allocator the parser object has been configured to use. Return a pointer to the memory or NULL on failure. Memory allocated in this way must be freed using XML_MemFree().

— Function: void * XML_MemRealloc (XML_Parser p, void * ptr, size_t size)

Allocate or reallocate size bytes of memory using the allocator the parser object has been configured to use.

ptr must point to a block of memory allocated by XML_MemMalloc() or XML_MemRealloc(), or be NULL.

When reallocating, this function tries to expand the block pointed to by ptr if possible.

Return a pointer to the memory or NULL on failure. On success, the original block has either been expanded or freed. On failure, the original block has not been freed; the caller is responsible for freeing the original block.

Memory allocated in this way must be freed using XML_MemFree().

— Function: void XML_MemFree (XML_Parser p, void * ptr)

Free a block of memory pointed to by ptr. The block must have been allocated by XML_MemMalloc() or XML_MemRealloc(), or be NULL.

— Function: void XML_SetUserData (XML_Parser p, void * user_data)
— Function: void * XML_GetUserData (XML_Parser p)

Set or get the user data pointer that gets passed to handlers, overwriting any previous value. The application is responsible for managing the memory associated with user_data.

— Function: void XML_UseParserAsHandlerArg (XML_Parser p)

Set the parser pointer itself as user_data argument for the handlers. The user data can still be obtained using the XML_GetUserData() function.

— Function: enum XML_Status XML_SetBase (XML_Parser p, const XML_Char * base)

Set the base to be used for resolving relative URIs in system identifiers. The string referenced by base is duplicated. If base is NULL the base is reset.

Return XML_STATUS_OK if successful. Return XML_STATUS_ERROR if there's no memory to duplicate the base.

— Function: const XML_Char * XML_GetBase (XML_Parser p)

Return the current base for resolving relative URIs. The returned value can be NULL if no base was set.

— Function: int XML_GetSpecifiedAttributeCount (XML_Parser p)

When attributes are reported to the start handler in the atts vector, attributes that were explicitly set in the element occur before any attributes that receive their value from default information in an ATTLIST declaration.

This function returns the number of attributes that were explicitly set times 2, thus giving the offset in the atts array passed to the start tag handler of the first attribute set due to defaults. It supplies information for the last call to a start handler. If called inside a start handler, then that means the current call.

— Function: int XML_GetIdAttributeIndex (XML_Parser p)

Return the index of the ID attribute passed in the atts array in the last call to XML_StartElementHandler(), or -1 if there is no ID attribute. If called inside a start handler, then that means the current call.

— Function: enum XML_Status XML_SetEncoding (XML_Parser p, const XML_Char * encoding)

Set the encoding to be used by the parser, return XML_STATUS_OK if successful.

The string referenced by encoding is duplicated, the return value is XML_STATUS_ERROR if there is not enough memory to duplicate it.

This function must not be called after XML_Parse() or XML_ParseBuffer() have been called on the given parser, the return value is XML_STATUS_ERROR if the parser is in the XML_PARSING or XML_SUSPENDED status.

Calling this function is equivalent to passing a non–NULL encoding argument to the parser creation functions.

— Function: int XML_SetParamEntityParsing (XML_Parser p, enum XML_ParamEntityParsing code)

Enable parsing of parameter entities according to code, including the external parameter entity that is the external DTD subset. The choices for code are:

          XML_PARAM_ENTITY_PARSING_NEVER
          XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE
          XML_PARAM_ENTITY_PARSING_ALWAYS

— Function: enum XML_Error XML_UseForeignDTD (XML_Parser p, XML_Bool use_dtd)

Allow an application to provide an external subset for the document type declaration for documents which do not specify an external subset of their own.

For documents which specify an external subset in their DOCTYPE declaration, the application–provided subset will be ignored.

If the document does not contain a DOCTYPE declaration at all and use_dtd is true, the application–provided subset will be parsed, but the XML_StartDoctypeDeclHandler and XML_EndDoctypeDeclHandler functions, if set, will not be called.

The setting of parameter entity parsing will be honored (refer to XML_SetParamEntityParsing()).

The application–provided external subset is read by calling the external entity reference handler set via XML_SetExternalEntityRefHandler() with both publicId and systemId set to NULL.

Return values are:

XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING

If this function is called after parsing has begun; use_dtd is ignored.

XML_ERROR_FEATURE_REQUIRES_XML_DTD

If called when Expat has been compiled without DTD support, it returns

XML_ERROR_NONE

Otherwise.

NOTE For the purpose of checking WFC: Entity Declared, passing use_dtd == XML_TRUE will make the parser behave as if the document had a DTD with an external subset. This holds true even if the external entity reference handler returns without action.

— Function: void XML_SetReturnNSTriplet (XML_Parser p, int do_nst)

This function only has an effect when using a parser created with XML_ParserCreateNS(), i.e. when namespace processing is in effect. The do_nst argument sets whether or not prefixes are returned with names qualified with a namespace prefix. If this function is called with non–zero do_nst, then namespace qualified names (that is qualified with a prefix as opposed to belonging to a default namespace) are returned as a triplet with the three parts separated by the namespace separator specified when the parser was created. The order of returned parts is URI, local name, and prefix.

If do_nst is zero, then namespaces are reported in the default manner, URI then local name separated by the namespace separator.