1 /* 2 neon XML parser interface 3 Copyright (C) 1999-2007, Joe Orton <joe@manyfish.co.uk> 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 */ 166