1 /* 2 neon XML parser interface 3 Copyright (C) 1999-2003, 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 BEGIN_NEON_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 /* Returns non-zero if the parse was valid, zero if it failed (e.g., 90 * any of the callbacks failed, the XML was not well-formed, etc). 91 * Use ne_xml_get_error to retrieve the error message if it failed. */ 92 int ne_xml_valid(ne_xml_parser *p); 93 94 /* Destroy the parser object. */ 95 void ne_xml_destroy(ne_xml_parser *p); 96 97 /* Parse the given block of input of length len. Block does not need 98 * to be NUL-terminated. */ 99 void ne_xml_parse(ne_xml_parser *p, const char *block, size_t len); 100 101 /* As above, casting (ne_xml_parser *)userdata internally. 102 * (This function can be passed to ne_add_response_body_reader) */ 103 void ne_xml_parse_v(void *userdata, const char *block, size_t len); 104 105 /* Return current parse line for errors */ 106 int ne_xml_currentline(ne_xml_parser *p); 107 108 /* Set error string for parser. */ 109 void ne_xml_set_error(ne_xml_parser *p, const char *msg); 110 111 /* Return the error string for the parser and never NULL. */ 112 const char *ne_xml_get_error(ne_xml_parser *p); 113 114 /* From a start_element callback which was passed 'attrs' using given 115 * parser, return attribute of given name and namespace. If nspace is 116 * NULL, no namespace resolution is performed. */ 117 const char *ne_xml_get_attr(ne_xml_parser *parser, 118 const char **attrs, const char *nspace, 119 const char *name); 120 121 /* Return the encoding of the document being parsed. May return NULL 122 * if no encoding is defined or if the XML declaration has not yet 123 * been parsed. */ 124 const char *ne_xml_doc_encoding(const ne_xml_parser *p); 125 126 /* A utility interface for mapping {nspace, name} onto an integer. */ 127 struct ne_xml_idmap { 128 const char *nspace, *name; 129 int id; 130 }; 131 132 /* Return the size of an idmap array */ 133 #define NE_XML_MAPLEN(map) (sizeof(map) / sizeof(struct ne_xml_idmap)) 134 135 /* Return the 'id' corresponding to {nspace, name}, or zero. */ 136 int ne_xml_mapid(const struct ne_xml_idmap map[], size_t maplen, 137 const char *nspace, const char *name); 138 139 /* media type, appropriate for adding to a Content-Type header */ 140 #define NE_XML_MEDIA_TYPE "application/xml" 141 142 END_NEON_DECLS 143 144 #endif /* NE_XML_H */ 145