include/apr-0/apr_xml.h

   1 /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
   2  * applicable.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 /**
  17  * @file apr_xml.h
  18  * @brief APR-UTIL XML Library
  19  */
  20 #ifndef APR_XML_H
  21 #define APR_XML_H
  22
  23 /**
  24  * @defgroup APR_Util_XML XML
  25  * @ingroup APR_Util
  26  * @{
  27  */
  28 #include "apr_pools.h"
  29 #include "apr_tables.h"
  30 #include "apr_file_io.h"
  31
  32 #include "apu.h"
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /**
  39  * @package Apache XML library
  40  */
  41
  42 /* -------------------------------------------------------------------- */
  43
  44 /* ### these will need to move at some point to a more logical spot */
  45
  46 /** @see apr_text */
  47 typedef struct apr_text apr_text;
  48
  49 /** Structure to keep a linked list of pieces of text */
  50 struct apr_text {
  51     /** The current piece of text */
  52     const char *text;
  53     /** a pointer to the next piece of text */
  54     struct apr_text *next;
  55 };
  56
  57 /** @see apr_text_header */
  58 typedef struct apr_text_header apr_text_header;
  59
  60 /** A list of pieces of text */
  61 struct apr_text_header {
  62     /** The first piece of text in the list */
  63     apr_text *first;
  64     /** The last piece of text in the list */
  65     apr_text *last;
  66 };
  67
  68 /**
  69  * Append a piece of text to the end of a list
  70  * @param p The pool to allocate out of
  71  * @param hdr The text header to append to
  72  * @param text The new text to append
  73  */
  74 APU_DECLARE(void) apr_text_append(apr_pool_t *p, apr_text_header *hdr,
  75                                   const char *text);
  76
  77
  78 /* --------------------------------------------------------------------
  79 **
  80 ** XML PARSING
  81 */
  82
  83 /*
  84 ** Qualified namespace values
  85 **
  86 ** APR_XML_NS_DAV_ID
  87 **    We always insert the "DAV:" namespace URI at the head of the
  88 **    namespace array. This means that it will always be at ID==0,
  89 **    making it much easier to test for.
  90 **
  91 ** APR_XML_NS_NONE
  92 **    This special ID is used for two situations:
  93 **
  94 **    1) The namespace prefix begins with "xml" (and we do not know
  95 **       what it means). Namespace prefixes with "xml" (any case) as
  96 **       their first three characters are reserved by the XML Namespaces
  97 **       specification for future use. mod_dav will pass these through
  98 **       unchanged. When this identifier is used, the prefix is LEFT in
  99 **       the element/attribute name. Downstream processing should not
 100 **       prepend another prefix.
 101 **
 102 **    2) The element/attribute does not have a namespace.
 103 **
 104 **       a) No prefix was used, and a default namespace has not been
 105 **          defined.
 106 **       b) No prefix was used, and the default namespace was specified
 107 **          to mean "no namespace". This is done with a namespace
 108 **          declaration of:  xmlns=""
 109 **          (this declaration is typically used to override a previous
 110 **          specification for the default namespace)
 111 **
 112 **       In these cases, we need to record that the elem/attr has no
 113 **       namespace so that we will not attempt to prepend a prefix.
 114 **       All namespaces that are used will have a prefix assigned to
 115 **       them -- mod_dav will never set or use the default namespace
 116 **       when generating XML. This means that "no prefix" will always
 117 **       mean "no namespace".
 118 **
 119 **    In both cases, the XML generation will avoid prepending a prefix.
 120 **    For the first case, this means the original prefix/name will be
 121 **    inserted into the output stream. For the latter case, it means
 122 **    the name will have no prefix, and since we never define a default
 123 **    namespace, this means it will have no namespace.
 124 **
 125 ** Note: currently, mod_dav understands the "xmlns" prefix and the
 126 **     "xml:lang" attribute. These are handled specially (they aren't
 127 **     left within the XML tree), so the APR_XML_NS_NONE value won't ever
 128 **     really apply to these values.
 129 */
 130 #define APR_XML_NS_DAV_ID       0       /**< namespace ID for "DAV:" */
 131 #define APR_XML_NS_NONE         -10     /**< no namespace for this elem/attr */
 132
 133 #define APR_XML_NS_ERROR_BASE   -100    /**< used only during processing */
 134 /** Is this namespace an error? */
 135 #define APR_XML_NS_IS_ERROR(e)  ((e) <= APR_XML_NS_ERROR_BASE)
 136
 137 /** @see apr_xml_attr */
 138 typedef struct apr_xml_attr apr_xml_attr;
 139 /** @see apr_xml_elem */
 140 typedef struct apr_xml_elem apr_xml_elem;
 141 /** @see apr_xml_doc */
 142 typedef struct apr_xml_doc apr_xml_doc;
 143
 144 /** apr_xml_attr: holds a parsed XML attribute */
 145 struct apr_xml_attr {
 146     /** attribute name */
 147     const char *name;
 148     /** index into namespace array */
 149     int ns;
 150
 151     /** attribute value */
 152     const char *value;
 153
 154     /** next attribute */
 155     struct apr_xml_attr *next;
 156 };
 157
 158 /** apr_xml_elem: holds a parsed XML element */
 159 struct apr_xml_elem {
 160     /** element name */
 161     const char *name;
 162     /** index into namespace array */
 163     int ns;
 164     /** xml:lang for attrs/contents */
 165     const char *lang;
 166
 167     /** cdata right after start tag */
 168     apr_text_header first_cdata;
 169     /** cdata after MY end tag */
 170     apr_text_header following_cdata;
 171
 172     /** parent element */
 173     struct apr_xml_elem *parent;
 174     /** next (sibling) element */
 175     struct apr_xml_elem *next;
 176     /** first child element */
 177     struct apr_xml_elem *first_child;
 178     /** first attribute */
 179     struct apr_xml_attr *attr;
 180
 181     /* used only during parsing */
 182     /** last child element */
 183     struct apr_xml_elem *last_child;
 184     /** namespaces scoped by this elem */
 185     struct apr_xml_ns_scope *ns_scope;
 186
 187     /* used by modules during request processing */
 188     /** Place for modules to store private data */
 189     void *priv;
 190 };
 191
 192 /** Is this XML element empty? */
 193 #define APR_XML_ELEM_IS_EMPTY(e) ((e)->first_child == NULL && \
 194                                   (e)->first_cdata.first == NULL)
 195
 196 /** apr_xml_doc: holds a parsed XML document */
 197 struct apr_xml_doc {
 198     /** root element */
 199     apr_xml_elem *root;
 200     /** array of namespaces used */
 201     apr_array_header_t *namespaces;
 202 };
 203
 204 /** Opaque XML parser structure */
 205 typedef struct apr_xml_parser apr_xml_parser;
 206
 207 /**
 208  * Create an XML parser
 209  * @param pool The pool for allocating the parser and the parse results.
 210  * @return The new parser.
 211  */
 212 APU_DECLARE(apr_xml_parser *) apr_xml_parser_create(apr_pool_t *pool);
 213
 214 /**
 215  * Parse a File, producing a xml_doc
 216  * @param p      The pool for allocating the parse results.
 217  * @param parser A pointer to *parser (needed so calling function can get
 218  *               errors), will be set to NULL on successfull completion.
 219  * @param ppdoc  A pointer to *apr_xml_doc (which has the parsed results in it)
 220  * @param xmlfd  A file to read from.
 221  * @param buffer_length Buffer length which would be suitable
 222  * @return Any errors found during parsing.
 223  */
 224 APU_DECLARE(apr_status_t) apr_xml_parse_file(apr_pool_t *p,
 225                                              apr_xml_parser **parser,
 226                                              apr_xml_doc **ppdoc,
 227                                              apr_file_t *xmlfd,
 228                                              apr_size_t buffer_length);
 229
 230
 231 /**
 232  * Feed input into the parser
 233  * @param parser The XML parser for parsing this data.
 234  * @param data The data to parse.
 235  * @param len The length of the data.
 236  * @return Any errors found during parsing.
 237  * @remark Use apr_xml_parser_geterror() to get more error information.
 238  */
 239 APU_DECLARE(apr_status_t) apr_xml_parser_feed(apr_xml_parser *parser,
 240                                               const char *data,
 241                                               apr_size_t len);
 242
 243 /**
 244  * Terminate the parsing and return the result
 245  * @param parser The XML parser for parsing this data.
 246  * @param pdoc The resulting parse information. May be NULL to simply
 247  *             terminate the parsing without fetching the info.
 248  * @return Any errors found during the final stage of parsing.
 249  * @remark Use apr_xml_parser_geterror() to get more error information.
 250  */
 251 APU_DECLARE(apr_status_t) apr_xml_parser_done(apr_xml_parser *parser,
 252                                               apr_xml_doc **pdoc);
 253
 254 /**
 255  * Fetch additional error information from the parser.
 256  * @param parser The XML parser to query for errors.
 257  * @param errbuf A buffer for storing error text.
 258  * @param errbufsize The length of the error text buffer.
 259  * @return The error buffer
 260  */
 261 APU_DECLARE(char *) apr_xml_parser_geterror(apr_xml_parser *parser,
 262                                             char *errbuf,
 263                                             apr_size_t errbufsize);
 264
 265
 266 /**
 267  * Converts an XML element tree to flat text
 268  * @param p The pool to allocate out of
 269  * @param elem The XML element to convert
 270  * @param style How to covert the XML.  One of:
 271  * <PRE>
 272  *     APR_XML_X2T_FULL                start tag, contents, end tag
 273  *     APR_XML_X2T_INNER               contents only
 274  *     APR_XML_X2T_LANG_INNER          xml:lang + inner contents
 275  *     APR_XML_X2T_FULL_NS_LANG        FULL + ns defns + xml:lang
 276  * </PRE>
 277  * @param namespaces The namespace of the current XML element
 278  * @param ns_map Namespace mapping
 279  * @param pbuf Buffer to put the converted text into
 280  * @param psize Size of the converted text
 281  */
 282 APU_DECLARE(void) apr_xml_to_text(apr_pool_t *p, const apr_xml_elem *elem,
 283                                   int style, apr_array_header_t *namespaces,
 284                                   int *ns_map, const char **pbuf,
 285                                   apr_size_t *psize);
 286
 287 /* style argument values: */
 288 #define APR_XML_X2T_FULL         0      /**< start tag, contents, end tag */
 289 #define APR_XML_X2T_INNER        1      /**< contents only */
 290 #define APR_XML_X2T_LANG_INNER   2      /**< xml:lang + inner contents */
 291 #define APR_XML_X2T_FULL_NS_LANG 3      /**< FULL + ns defns + xml:lang */
 292
 293 /**
 294  * empty XML element
 295  * @param p The pool to allocate out of
 296  * @param elem The XML element to empty
 297  * @return the string that was stored in the XML element
 298  */
 299 APU_DECLARE(const char *) apr_xml_empty_elem(apr_pool_t *p,
 300                                              const apr_xml_elem *elem);
 301
 302 /**
 303  * quote an XML string
 304  * Replace '<', '>', and '&' with '&lt;', '&gt;', and '&amp;'.
 305  * @param p The pool to allocate out of
 306  * @param s The string to quote
 307  * @param quotes If quotes is true, then replace '"' with '&quot;'.
 308  * @return The quoted string
 309  * @note If the string does not contain special characters, it is not
 310  * duplicated into the pool and the original string is returned.
 311  */
 312 APU_DECLARE(const char *) apr_xml_quote_string(apr_pool_t *p, const char *s,
 313                                                int quotes);
 314
 315 /**
 316  * Quote an XML element
 317  * @param p The pool to allocate out of
 318  * @param elem The element to quote
 319  */
 320 APU_DECLARE(void) apr_xml_quote_elem(apr_pool_t *p, apr_xml_elem *elem);
 321
 322 /* manage an array of unique URIs: apr_xml_insert_uri() and APR_XML_URI_ITEM() */
 323
 324 /**
 325  * return the URI's (existing) index, or insert it and return a new index
 326  * @param uri_array array to insert into
 327  * @param uri The uri to insert
 328  * @return int The uri's index
 329  */
 330 APU_DECLARE(int) apr_xml_insert_uri(apr_array_header_t *uri_array,
 331                                     const char *uri);
 332
 333 /** Get the URI item for this XML element */
 334 #define APR_XML_GET_URI_ITEM(ary, i) (((const char * const *)(ary)->elts)[i])
 335
 336 #ifdef __cplusplus
 337 }
 338 #endif
 339 /** @} */
 340 #endif /* APR_XML_H */