| 1 |
/* |
| 2 |
neon XML parser interface |
| 3 |
Copyright (C) 1999-2007, Joe Orton <[email protected]> |
| 4 |
|
| 5 |
This library is free software; you can redistribute it and/or |
| 6 |
modify it under the terms of the GNU Library General Public |
| 7 |
License as published by the Free Software Foundation; either |
| 8 |
version 2 of the License, or (at your option) any later version. |
| 9 |
|
| 10 |
This library is distributed in the hope that it will be useful, |
| 11 |
but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 13 |
Library General Public License for more details. |
| 14 |
|
| 15 |
You should have received a copy of the GNU Library General Public |
| 16 |
License along with this library; if not, write to the Free |
| 17 |
Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, |
| 18 |
MA 02111-1307, USA |
| 19 |
|
| 20 |
*/ |
| 21 |
|
| 22 |
#ifndef NE_XML_H |
| 23 |
#define NE_XML_H |
| 24 |
|
| 25 |
#include <sys/types.h> /* for size_t */ |
| 26 |
|
| 27 |
#include "ne_defs.h" |
| 28 |
|
| 29 |
NE_BEGIN_DECLS |
| 30 |
|
| 31 |
/* The neon XML interface filters a streamed XML tree through a stack |
| 32 |
* of SAX "handlers". A handler is made up of three callbacks |
| 33 |
* (start-element, char-data, end-element). Each start-element event |
| 34 |
* is passed to each handler in the stack in turn until one until one |
| 35 |
* accepts the element. This handler then receives subsequent |
| 36 |
* char-data and end-element events for the element. |
| 37 |
* |
| 38 |
* For each new start-element event, the search up the handler stack |
| 39 |
* begins with the handler for the parent element (for the root |
| 40 |
* element, at the base of the stack). |
| 41 |
* |
| 42 |
* For each accepted element, a "state" integer is stored, which is |
| 43 |
* passed to the corresponding char-data and end-element callbacks for |
| 44 |
* the element. This integer is also passed to the start-element |
| 45 |
* callback of child elements so they can determine context. |
| 46 |
* |
| 47 |
* If no handler in the stack accepts a particular element, it (and |
| 48 |
* its children, if any) is ignored. */ |
| 49 |
|
| 50 |
#define NE_XML_DECLINE (0) |
| 51 |
#define NE_XML_ABORT (-1) |
| 52 |
|
| 53 |
/* A start-element callback for element with given namespace/name. |
| 54 |
* The callback may return: |
| 55 |
* <0 => abort the parse (NE_XML_ABORT) |
| 56 |
* 0 => decline this element (NE_XML_DECLINE) |
| 57 |
* >0 => accept this element; value is state for this element. |
| 58 |
* |
| 59 |
* The 'parent' integer is the state returned by the handler of the |
| 60 |
* parent element. The attributes array gives name/value pairs |
| 61 |
* in atts[n] and atts[n+1] from n=0 up to atts[n]==NULL. */ |
| 62 |
typedef int ne_xml_startelm_cb(void *userdata, int parent, |
| 63 |
const char *nspace, const char *name, |
| 64 |
const char **atts); |
| 65 |
|
| 66 |
/* state for the root element */ |
| 67 |
#define NE_XML_STATEROOT (0) |
| 68 |
|
| 69 |
/* Character data callback; may return non-zero to abort the parse. */ |
| 70 |
typedef int ne_xml_cdata_cb(void *userdata, int state, |
| 71 |
const char *cdata, size_t len); |
| 72 |
/* End element callback; may return non-zero to abort the parse. */ |
| 73 |
typedef int ne_xml_endelm_cb(void *userdata, int state, |
| 74 |
const char *nspace, const char *name); |
| 75 |
|
| 76 |
typedef struct ne_xml_parser_s ne_xml_parser; |
| 77 |
|
| 78 |
/* Create an XML parser. */ |
| 79 |
ne_xml_parser *ne_xml_create(void); |
| 80 |
|
| 81 |
/* Push a new handler on the stack of parser 'p'. 'cdata' and/or |
| 82 |
* 'endelm' may be NULL; startelm must be non-NULL. */ |
| 83 |
void ne_xml_push_handler(ne_xml_parser *p, |
| 84 |
ne_xml_startelm_cb *startelm, |
| 85 |
ne_xml_cdata_cb *cdata, |
| 86 |
ne_xml_endelm_cb *endelm, |
| 87 |
void *userdata); |
| 88 |
|
| 89 |
/* ne_xml_failed returns non-zero if there was an error during |
| 90 |
* parsing, or zero if the parse completed successfully. The return |
| 91 |
* value is equal to that of the last ne_xml_parse() call for this |
| 92 |
* parser object. */ |
| 93 |
int ne_xml_failed(ne_xml_parser *p); |
| 94 |
|
| 95 |
/* Set error string for parser. (The string may be truncated |
| 96 |
* internally). */ |
| 97 |
void ne_xml_set_error(ne_xml_parser *p, const char *msg); |
| 98 |
|
| 99 |
/* Return the error string (and never NULL). After ne_xml_failed |
| 100 |
* returns >0, this will describe the parse error. Otherwise it will |
| 101 |
* be a default error string. */ |
| 102 |
const char *ne_xml_get_error(ne_xml_parser *p); |
| 103 |
|
| 104 |
/* Parse the given block of input of length len. Parser must be |
| 105 |
* called with len=0 to signify the end of the document (for that |
| 106 |
* case, the block argument is ignored). Returns zero on success, or |
| 107 |
* non-zero on error: for an XML syntax error, a positive number is |
| 108 |
* returned; if parsing is aborted by a caller-supplied callback, that |
| 109 |
* callback's return value is returned. */ |
| 110 |
int ne_xml_parse(ne_xml_parser *p, const char *block, size_t len); |
| 111 |
|
| 112 |
/* As ne_xml_parse, casting (ne_xml_parser *)userdata internally. |
| 113 |
* (This function can be passed to ne_add_response_body_reader) */ |
| 114 |
int ne_xml_parse_v(void *userdata, const char *block, size_t len); |
| 115 |
|
| 116 |
/* Return current line of document during parsing or after parsing is |
| 117 |
* complete. */ |
| 118 |
int ne_xml_currentline(ne_xml_parser *p); |
| 119 |
|
| 120 |
/* From a start_element callback which was passed 'attrs' using given |
| 121 |
* parser, return attribute of given name and namespace. If nspace is |
| 122 |
* NULL, no namespace resolution is performed. Note that this call is |
| 123 |
* context-specific; if called outside a start_element callback, |
| 124 |
* behaviour is undefined. */ |
| 125 |
const char *ne_xml_get_attr(ne_xml_parser *parser, |
| 126 |
const char **attrs, const char *nspace, |
| 127 |
const char *name); |
| 128 |
|
| 129 |
/* From a start_element callback, resolve a given XML Namespace |
| 130 |
* prefix, if defined. Given a non-NULL prefix, returns the namespace |
| 131 |
* URI which corresponds to the prefix 'prefix' (of length 'length'), |
| 132 |
* or NULL if no such namespace prefix is defined. Given a NULL |
| 133 |
* prefix, returns the default namespace URI or the empty string if |
| 134 |
* none is defined. Note that this call is context-specific; if |
| 135 |
* called outside a start_element callback, behaviour is undefined. */ |
| 136 |
const char *ne_xml_resolve_nspace(ne_xml_parser *parser, |
| 137 |
const char *prefix, size_t length); |
| 138 |
|
| 139 |
/* Return the encoding of the document being parsed. May return NULL |
| 140 |
* if no encoding is defined or if the XML declaration has not yet |
| 141 |
* been parsed. */ |
| 142 |
const char *ne_xml_doc_encoding(const ne_xml_parser *p); |
| 143 |
|
| 144 |
/* Destroy the parser object. */ |
| 145 |
void ne_xml_destroy(ne_xml_parser *p); |
| 146 |
|
| 147 |
/* A utility interface for mapping {nspace, name} onto an integer. */ |
| 148 |
struct ne_xml_idmap { |
| 149 |
const char *nspace, *name; |
| 150 |
int id; |
| 151 |
}; |
| 152 |
|
| 153 |
/* Return the size of an idmap array */ |
| 154 |
#define NE_XML_MAPLEN(map) (sizeof(map) / sizeof(struct ne_xml_idmap)) |
| 155 |
|
| 156 |
/* Return the 'id' corresponding to {nspace, name}, or zero. */ |
| 157 |
int ne_xml_mapid(const struct ne_xml_idmap map[], size_t maplen, |
| 158 |
const char *nspace, const char *name); |
| 159 |
|
| 160 |
/* media type, appropriate for adding to a Content-Type header */ |
| 161 |
#define NE_XML_MEDIA_TYPE "application/xml" |
| 162 |
|
| 163 |
NE_END_DECLS |
| 164 |
|
| 165 |
#endif /* NE_XML_H */ |