granicus.if.org Git - apache/blob - include/util_xml.h

   1 /* ====================================================================
   2  * The Apache Software License, Version 1.1
   3  *
   4  * Copyright (c) 2000-2001 The Apache Software Foundation.  All rights
   5  * reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  *
  11  * 1. Redistributions of source code must retain the above copyright
  12  *    notice, this list of conditions and the following disclaimer.
  13  *
  14  * 2. Redistributions in binary form must reproduce the above copyright
  15  *    notice, this list of conditions and the following disclaimer in
  16  *    the documentation and/or other materials provided with the
  17  *    distribution.
  18  *
  19  * 3. The end-user documentation included with the redistribution,
  20  *    if any, must include the following acknowledgment:
  21  *       "This product includes software developed by the
  22  *        Apache Software Foundation (http://www.apache.org/)."
  23  *    Alternately, this acknowledgment may appear in the software itself,
  24  *    if and wherever such third-party acknowledgments normally appear.
  25  *
  26  * 4. The names "Apache" and "Apache Software Foundation" must
  27  *    not be used to endorse or promote products derived from this
  28  *    software without prior written permission. For written
  29  *    permission, please contact apache@apache.org.
  30  *
  31  * 5. Products derived from this software may not be called "Apache",
  32  *    nor may "Apache" appear in their name, without prior written
  33  *    permission of the Apache Software Foundation.
  34  *
  35  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46  * SUCH DAMAGE.
  47  * ====================================================================
  48  *
  49  * This software consists of voluntary contributions made by many
  50  * individuals on behalf of the Apache Software Foundation.  For more
  51  * information on the Apache Software Foundation, please see
  52  * <http://www.apache.org/>.
  53  */
  54
  55 #ifndef UTIL_XML_H
  56 #define UTIL_XML_H
  57
  58 #ifdef __cplusplus
  59 extern "C" {
  60 #endif
  61
  62 #include "httpd.h"
  63 #include "apr_lib.h"
  64
  65 /**
  66  * @package Apache XML library
  67  */
  68
  69 /* -------------------------------------------------------------------- */
  70
  71 /* ### these will need to move at some point to a more logical spot */
  72
  73 /* simple strutures to keep a linked list of pieces of text */
  74 typedef struct ap_text ap_text;
  75
  76 /** Structure to keep a linked list of pieces of text */
  77 struct ap_text {
  78     /** The current piece of text */
  79     const char *text;
  80     /** a pointer to the next piece of text
  81      *  @defvar ap_text *next */
  82     struct ap_text *next;
  83 };
  84
  85 typedef struct ap_text_header ap_text_header;
  86
  87 /** A list of pieces of text */
  88 struct ap_text_header {
  89     /** The first piece of text in the list */
  90     ap_text *first;
  91     /** The last piece of text in the list */
  92     ap_text *last;
  93 };
  94
  95 /**
  96  * Append a piece of text to the end of a list
  97  * @param p The pool to allocate out of
  98  * @param hdr The text header to append to
  99  * @param text The new text to append
 100  * @deffunc void ap_text_append(apr_pool_t *p, ap_text_header *hdr, const char *text)
 101  */
 102 AP_DECLARE(void) ap_text_append(apr_pool_t *p, ap_text_header *hdr,
 103                                 const char *text);
 104
 105
 106 /* --------------------------------------------------------------------
 107 **
 108 ** XML PARSING
 109 */
 110
 111 /*
 112 ** Qualified namespace values
 113 **
 114 ** AP_XML_NS_DAV_ID
 115 **    We always insert the "DAV:" namespace URI at the head of the
 116 **    namespace array. This means that it will always be at ID==0,
 117 **    making it much easier to test for.
 118 **
 119 ** AP_XML_NS_NONE
 120 **    This special ID is used for two situations:
 121 **
 122 **    1) The namespace prefix begins with "xml" (and we do not know
 123 **       what it means). Namespace prefixes with "xml" (any case) as
 124 **       their first three characters are reserved by the XML Namespaces
 125 **       specification for future use. mod_dav will pass these through
 126 **       unchanged. When this identifier is used, the prefix is LEFT in
 127 **       the element/attribute name. Downstream processing should not
 128 **       prepend another prefix.
 129 **
 130 **    2) The element/attribute does not have a namespace.
 131 **
 132 **       a) No prefix was used, and a default namespace has not been
 133 **          defined.
 134 **       b) No prefix was used, and the default namespace was specified
 135 **          to mean "no namespace". This is done with a namespace
 136 **          declaration of:  xmlns=""
 137 **          (this declaration is typically used to override a previous
 138 **          specification for the default namespace)
 139 **
 140 **       In these cases, we need to record that the elem/attr has no
 141 **       namespace so that we will not attempt to prepend a prefix.
 142 **       All namespaces that are used will have a prefix assigned to
 143 **       them -- mod_dav will never set or use the default namespace
 144 **       when generating XML. This means that "no prefix" will always
 145 **       mean "no namespace".
 146 **
 147 **    In both cases, the XML generation will avoid prepending a prefix.
 148 **    For the first case, this means the original prefix/name will be
 149 **    inserted into the output stream. For the latter case, it means
 150 **    the name will have no prefix, and since we never define a default
 151 **    namespace, this means it will have no namespace.
 152 **
 153 ** Note: currently, mod_dav understands the "xmlns" prefix and the
 154 **     "xml:lang" attribute. These are handled specially (they aren't
 155 **     left within the XML tree), so the AP_XML_NS_NONE value won't ever
 156 **     really apply to these values.
 157 */
 158 #define AP_XML_NS_DAV_ID        0       /* namespace ID for "DAV:" */
 159 #define AP_XML_NS_NONE          -10     /* no namespace for this elem/attr */
 160
 161 #define AP_XML_NS_ERROR_BASE    -100    /* used only during processing */
 162 #define AP_XML_NS_IS_ERROR(e)   ((e) <= AP_XML_NS_ERROR_BASE)
 163
 164
 165 typedef struct ap_xml_attr ap_xml_attr;
 166 typedef struct ap_xml_elem ap_xml_elem;
 167 typedef struct ap_xml_doc ap_xml_doc;
 168
 169 /** ap_xml_attr: holds a parsed XML attribute */
 170 struct ap_xml_attr {
 171     /** attribute name */
 172     const char *name;
 173     /** index into namespace array */
 174     int ns;
 175
 176     /** attribute value */
 177     const char *value;
 178
 179     /** next attribute
 180      *  @defvar ap_xml_attr *next */
 181     struct ap_xml_attr *next;
 182 };
 183
 184 /** ap_xml_elem: holds a parsed XML element */
 185 struct ap_xml_elem {
 186     /** element name */
 187     const char *name;
 188     /** index into namespace array */
 189     int ns;
 190     /** xml:lang for attrs/contents */
 191     const char *lang;
 192
 193     /** cdata right after start tag */
 194     ap_text_header first_cdata;
 195     /** cdata after MY end tag */
 196     ap_text_header following_cdata;
 197
 198     /** parent element
 199      *  @defvar ap_xml_elem *parent */
 200     struct ap_xml_elem *parent;
 201     /** next (sibling) element
 202      *  @defvar ap_xml_elem *next */
 203     struct ap_xml_elem *next;
 204     /** first child element
 205      *  @defvar ap_xml_elem *first_child */
 206     struct ap_xml_elem *first_child;
 207     /** first attribute
 208      *  @defvar ap_xml_attr *attr */
 209     struct ap_xml_attr *attr;
 210
 211     /* used only during parsing */
 212     /** last child element
 213      *  @defvar ap_xml_elem *last_child */
 214     struct ap_xml_elem *last_child;
 215     /** namespaces scoped by this elem
 216      *  @defvar ap_xml_ns_scope *ns_scope */
 217     struct ap_xml_ns_scope *ns_scope;
 218
 219     /* used by modules during request processing */
 220     /** Place for modules to store private data */
 221     void *private;
 222 };
 223
 224 #define AP_XML_ELEM_IS_EMPTY(e) ((e)->first_child == NULL && \
 225                                  (e)->first_cdata.first == NULL)
 226
 227 /** ap_xml_doc: holds a parsed XML document */
 228 struct ap_xml_doc {
 229     /** root element */
 230     ap_xml_elem *root;
 231     /** array of namespaces used */
 232     apr_array_header_t *namespaces;
 233 };
 234
 235 /**
 236  * Get XML post data and parse it
 237  * @param r The current request
 238  * @param pdoc The XML post data
 239  * @return HTTP status code
 240  * @deffunc int ap_xml_parse_input(request_rec *r, ap_xml_doc **pdoc)
 241  */
 242 AP_DECLARE(int) ap_xml_parse_input(request_rec *r, ap_xml_doc **pdoc);
 243
 244
 245 /**
 246  * Converts an XML element tree to flat text
 247  * @param p The pool to allocate out of
 248  * @param elem The XML element to convert
 249  * @param style How to covert the XML.  One of:
 250  * <PRE>
 251  *     AP_XML_X2T_FULL                start tag, contents, end tag
 252  *     AP_XML_X2T_INNER               contents only
 253  *     AP_XML_X2T_LANG_INNER          xml:lang + inner contents
 254  *     AP_XML_X2T_FULL_NS_LANG        FULL + ns defns + xml:lang
 255  * </PRE>
 256  * @param namespaces The namespace of the current XML element
 257  * @param ns_map Namespace mapping
 258  * @param pbuf Buffer to put the converted text into
 259  * @param psize Size of the converted text
 260  * @deffunc void ap_xml_to_text(apr_pool_t *p, const ap_xml_elem *elem, int style, apr_array_header_t *namespaces, int *ns_map, const char **pbuf, size_t *psize);
 261  */
 262 AP_DECLARE(void) ap_xml_to_text(apr_pool_t *p, const ap_xml_elem *elem,
 263                                 int style, apr_array_header_t *namespaces,
 264                                 int *ns_map, const char **pbuf,
 265                                 apr_size_t *psize);
 266
 267 /* style argument values: */
 268 #define AP_XML_X2T_FULL         0       /* start tag, contents, end tag */
 269 #define AP_XML_X2T_INNER        1       /* contents only */
 270 #define AP_XML_X2T_LANG_INNER   2       /* xml:lang + inner contents */
 271 #define AP_XML_X2T_FULL_NS_LANG 3       /* FULL + ns defns + xml:lang */
 272
 273 /**
 274  * empty XML element
 275  * @param p The pool to allocate out of
 276  * @param elem The XML element to empty
 277  * @return the string that was stored in the XML element
 278  * @deffunc const char *ap_xml_empty_elem(apr_pool_t *p, const ap_xml_elem *elem)
 279  */
 280 AP_DECLARE(const char *) ap_xml_empty_elem(apr_pool_t *p,
 281                                            const ap_xml_elem *elem);
 282
 283 /**
 284  * quote an XML string
 285  * Replace '<', '>', and '&' with '&lt;', '&gt;', and '&amp;'.
 286  * @param p The pool to allocate out of
 287  * @param s The string to quote
 288  * @param quotes If quotes is true, then replace '"' with '&quot;'.
 289  * @return The quoted string
 290  * @deffunc const char *ap_xml_quote_string(apr_pool_t *p, const char *s, int quotes)
 291  */
 292 AP_DECLARE(const char *) ap_xml_quote_string(apr_pool_t *p, const char *s,
 293                                              int quotes);
 294
 295 /**
 296  * Quote an XML element
 297  * @param p The pool to allocate out of
 298  * @param elem The element to quote
 299  * @deffunc void ap_xml_quote_elem(apr_pool_t *p, ap_xml_elem *elem)
 300  */
 301 AP_DECLARE(void) ap_xml_quote_elem(apr_pool_t *p, ap_xml_elem *elem);
 302
 303 /* manage an array of unique URIs: ap_xml_insert_uri() and AP_XML_URI_ITEM() */
 304
 305 /**
 306  * return the URI's (existing) index, or insert it and return a new index
 307  * @param uri_array array to insert into
 308  * @param uri The uri to insert
 309  * @return int The uri's index
 310  * @deffunc int ap_xml_insert_uri(apr_array_header_t *uri_array, const char *uri)
 311  */
 312 AP_DECLARE(int) ap_xml_insert_uri(apr_array_header_t *uri_array,
 313                                   const char *uri);
 314 #define AP_XML_GET_URI_ITEM(ary, i)    (((const char * const *)(ary)->elts)[i])
 315
 316 #ifdef __cplusplus
 317 }
 318 #endif
 319
 320 #endif /* UTIL_XML_H */