Re: [xml] new SAX2 API

[Daniel Veillard <veillard redhat com>]

On Wed, Oct 01, 2003 at 10:42:45PM +0100, Graham Bennett wrote:
> Here's some more summarisation of my experiences of coding against the
> SAX2 API so far..
>
> In order to initialise the SAX handler struct, I had to do something
> like:
>
> ::memset(ctxt->sax, 0, sizeof(xmlSAXHandler)); // set some callbacks
> ctxt->sax->initialized = XML_SAX2_MAGIC;
>
> Daniel is going to provide a function which initialises the struct for
> the correct SAX API version so people don't have to know about
> XML_SAX2_MAGIC.

  XMLPUBFUN int XMLCALL
                  xmlSAXVersion                   (xmlSAXHandler *hdlr,
                                                   int version);
Where version can be 1 or 2.  The problem is that memset() errases
the magic number :-\

>  - I would rather have a string error message and some location
>    information than the varargs list that is there currently.  At the
> moment I have to run through the args building up a string message
> myself.

  Based on Havoc's and others feedback here is what I started to work
on, it's very close to Gerror, just specialized for the parser needs:

/**
 * xmlErrorLevel:
 *
 * Indicates the level of an error
 */
typedef enum {
    XML_ERR_NONE = 0,
    XML_ERR_WARNING = 1,        /* A simple warning */
    XML_ERR_ERROR = 2,          /* A recoverable error */
    XML_ERR_FATAL = 3           /* A fatal error */
} xmlErrorLevel;

/**
 * xmlErrorDomain:
 *
 * Indicates where an error may have come from
 */
typedef enum {
    XML_FROM_NONE = 0,
    XML_FROM_PARSER,    /* The XML parser */
    XML_ERR_HTML,       /* The HTML parser */
    XML_ERR_MEMORY,     /* The memory allocator */
    XML_ERR_OUTPUT,     /* The serialization code */
    XML_ERR_IO,         /* The Input/Output stack */
    XML_ERR_XINCLUDE,   /* The XInclude processing */
    XML_ERR_XPATH,      /* The XPath engine */
    XML_ERR_XPOINTER    /* The XPointer engine */
} xmlErrorDomain;

/**
 * xmlError:
 *
 * An XML Error instance.
 */
                                                                                
typedef struct _xmlError xmlError;
typedef xmlError *xmlErrorPtr;
struct _xmlError {
    int         domain; /* What part of the library raised this error */
    int         code;   /* The error code, e.g. an xmlParserError */
    char       *message;/* human-readable informative error message */
    xmlErrorLevel level;/* how consequent is the error */
    char       *file;   /* the filename */
    int         line;   /* the line number if available */
    char       *str1;   /* extra string information */
    char       *str2;   /* extra string information */
    int         int1;   /* extra number information */
    int         int2;   /* extra number information */
};

And 

/*
 * Extended error information routines
 */
XMLPUBFUN xmlErrorPtr XMLCALL
    xmlGetLastError             (void);
XMLPUBFUN void XMLCALL
    xmlResetLastError           (void);
XMLPUBFUN int XMLCALL
    xmlCopyError                (xmlErrorPtr from,
                                 xmlErrorPtr to);
XMLPUBFUN xmlErrorPtr XMLCALL
    xmlCtxtGetLastError         (void *ctx);
XMLPUBFUN void XMLCALL
    xmlCtxtResetLastError       (void *ctx);

  The xmlGetLastError() and xmlResetLastError() will work on a global
xmlError which is defined per-thread if the library is configured with
threads. The xmlCtxtGetLastError() and xmlCtxtGetLastError() will
be associated to a parser context, the xmlError is allocated and stored
within the parser context so there is no risk of facing memory allocation
to report error in out of memory condition.
  The real pain is to conver all message reporting in the library to use
those facilities, type of grunt job which is both boring and dangerous,
but this need to get done, and now is the time :-\ , it's certainly more
useful than flaming on xml-dev ...

>  - How best to stop the parser?  I think there is an xmlStopParser (or
>    similar) function that I should be using.  Is there anything else I
> need to worry about when stopping the parse?

  Hum, no, not really. All parsing state will be freed or cleaned up
when calling xmlFreeParserCtxt() or reusing the context with xmlCtxtReadxxx()
I still need to provide similar initialization/reuse for the xmlReader.

Daniel

-- 
Daniel Veillard      | Red Hat Network https://rhn.redhat.com/
veillard redhat com  | libxml GNOME XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/