util_xml.h revision 155c41995a4728123ceb4c637df8e2aaf0d7223f
f6b86fd524444dacf82f64148300d8be04918314gstein/* ====================================================================
f6b86fd524444dacf82f64148300d8be04918314gstein * The Apache Software License, Version 1.1
f6b86fd524444dacf82f64148300d8be04918314gstein * Copyright (c) 2000 The Apache Software Foundation. All rights
f6b86fd524444dacf82f64148300d8be04918314gstein * reserved.
f6b86fd524444dacf82f64148300d8be04918314gstein * Redistribution and use in source and binary forms, with or without
f6b86fd524444dacf82f64148300d8be04918314gstein * modification, are permitted provided that the following conditions
f6b86fd524444dacf82f64148300d8be04918314gstein * 1. Redistributions of source code must retain the above copyright
f6b86fd524444dacf82f64148300d8be04918314gstein * notice, this list of conditions and the following disclaimer.
f6b86fd524444dacf82f64148300d8be04918314gstein * 2. Redistributions in binary form must reproduce the above copyright
f6b86fd524444dacf82f64148300d8be04918314gstein * notice, this list of conditions and the following disclaimer in
f6b86fd524444dacf82f64148300d8be04918314gstein * the documentation and/or other materials provided with the
f6b86fd524444dacf82f64148300d8be04918314gstein * distribution.
f6b86fd524444dacf82f64148300d8be04918314gstein * 3. The end-user documentation included with the redistribution,
f6b86fd524444dacf82f64148300d8be04918314gstein * if any, must include the following acknowledgment:
f6b86fd524444dacf82f64148300d8be04918314gstein * "This product includes software developed by the
f6b86fd524444dacf82f64148300d8be04918314gstein * Apache Software Foundation (http://www.apache.org/)."
f6b86fd524444dacf82f64148300d8be04918314gstein * Alternately, this acknowledgment may appear in the software itself,
f6b86fd524444dacf82f64148300d8be04918314gstein * if and wherever such third-party acknowledgments normally appear.
f6b86fd524444dacf82f64148300d8be04918314gstein * 4. The names "Apache" and "Apache Software Foundation" must
f6b86fd524444dacf82f64148300d8be04918314gstein * not be used to endorse or promote products derived from this
f6b86fd524444dacf82f64148300d8be04918314gstein * software without prior written permission. For written
f6b86fd524444dacf82f64148300d8be04918314gstein * permission, please contact apache@apache.org.
f6b86fd524444dacf82f64148300d8be04918314gstein * 5. Products derived from this software may not be called "Apache",
f6b86fd524444dacf82f64148300d8be04918314gstein * nor may "Apache" appear in their name, without prior written
f6b86fd524444dacf82f64148300d8be04918314gstein * permission of the Apache Software Foundation.
f6b86fd524444dacf82f64148300d8be04918314gstein * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
f6b86fd524444dacf82f64148300d8be04918314gstein * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
f6b86fd524444dacf82f64148300d8be04918314gstein * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
f6b86fd524444dacf82f64148300d8be04918314gstein * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
f6b86fd524444dacf82f64148300d8be04918314gstein * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
f6b86fd524444dacf82f64148300d8be04918314gstein * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
f6b86fd524444dacf82f64148300d8be04918314gstein * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
f6b86fd524444dacf82f64148300d8be04918314gstein * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
f6b86fd524444dacf82f64148300d8be04918314gstein * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
f6b86fd524444dacf82f64148300d8be04918314gstein * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
f6b86fd524444dacf82f64148300d8be04918314gstein * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
f6b86fd524444dacf82f64148300d8be04918314gstein * SUCH DAMAGE.
f6b86fd524444dacf82f64148300d8be04918314gstein * ====================================================================
f6b86fd524444dacf82f64148300d8be04918314gstein * This software consists of voluntary contributions made by many
f6b86fd524444dacf82f64148300d8be04918314gstein * individuals on behalf of the Apache Software Foundation. For more
f6b86fd524444dacf82f64148300d8be04918314gstein * information on the Apache Software Foundation, please see
f6b86fd524444dacf82f64148300d8be04918314gsteinextern "C" {
f6b86fd524444dacf82f64148300d8be04918314gstein/* -------------------------------------------------------------------- */
f6b86fd524444dacf82f64148300d8be04918314gstein/* ### these will need to move at some point to a more logical spot */
f6b86fd524444dacf82f64148300d8be04918314gstein/* simple strutures to keep a linked list of pieces of text */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb/** Structure to keep a linked list of pieces of text */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** The current piece of text */
f6b86fd524444dacf82f64148300d8be04918314gstein const char *text;
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** a pointer to the next piece of text
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @defvar ap_text *next */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb/** A list of pieces of text */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** The first piece of text in the list */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** The last piece of text in the list */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * Append a piece of text to the end of a list
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param p The pool to allocate out of
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param hdr The text header to append to
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param text The new text to append
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @deffunc void ap_text_append(apr_pool_t *p, ap_text_header *hdr, const char *text)
1ccd992d37d62c8cb2056126f2234f64ec189bfddougmAPI_EXPORT(void) ap_text_append(apr_pool_t *p, ap_text_header *hdr,
f6b86fd524444dacf82f64148300d8be04918314gstein const char *text);
f6b86fd524444dacf82f64148300d8be04918314gstein/* --------------------------------------------------------------------
f6b86fd524444dacf82f64148300d8be04918314gstein** XML PARSING
f6b86fd524444dacf82f64148300d8be04918314gstein** Qualified namespace values
f6b86fd524444dacf82f64148300d8be04918314gstein** AP_XML_NS_DAV_ID
f6b86fd524444dacf82f64148300d8be04918314gstein** We always insert the "DAV:" namespace URI at the head of the
f6b86fd524444dacf82f64148300d8be04918314gstein** namespace array. This means that it will always be at ID==0,
f6b86fd524444dacf82f64148300d8be04918314gstein** making it much easier to test for.
f6b86fd524444dacf82f64148300d8be04918314gstein** AP_XML_NS_NONE
f6b86fd524444dacf82f64148300d8be04918314gstein** This special ID is used for two situations:
f6b86fd524444dacf82f64148300d8be04918314gstein** 1) The namespace prefix begins with "xml" (and we do not know
f6b86fd524444dacf82f64148300d8be04918314gstein** what it means). Namespace prefixes with "xml" (any case) as
f6b86fd524444dacf82f64148300d8be04918314gstein** their first three characters are reserved by the XML Namespaces
f6b86fd524444dacf82f64148300d8be04918314gstein** specification for future use. mod_dav will pass these through
f6b86fd524444dacf82f64148300d8be04918314gstein** unchanged. When this identifier is used, the prefix is LEFT in
f6b86fd524444dacf82f64148300d8be04918314gstein** the element/attribute name. Downstream processing should not
f6b86fd524444dacf82f64148300d8be04918314gstein** prepend another prefix.
f6b86fd524444dacf82f64148300d8be04918314gstein** 2) The element/attribute does not have a namespace.
f6b86fd524444dacf82f64148300d8be04918314gstein** a) No prefix was used, and a default namespace has not been
f6b86fd524444dacf82f64148300d8be04918314gstein** b) No prefix was used, and the default namespace was specified
f6b86fd524444dacf82f64148300d8be04918314gstein** to mean "no namespace". This is done with a namespace
f6b86fd524444dacf82f64148300d8be04918314gstein** declaration of: xmlns=""
f6b86fd524444dacf82f64148300d8be04918314gstein** (this declaration is typically used to override a previous
f6b86fd524444dacf82f64148300d8be04918314gstein** specification for the default namespace)
f6b86fd524444dacf82f64148300d8be04918314gstein** In these cases, we need to record that the elem/attr has no
f6b86fd524444dacf82f64148300d8be04918314gstein** namespace so that we will not attempt to prepend a prefix.
f6b86fd524444dacf82f64148300d8be04918314gstein** All namespaces that are used will have a prefix assigned to
f6b86fd524444dacf82f64148300d8be04918314gstein** them -- mod_dav will never set or use the default namespace
f6b86fd524444dacf82f64148300d8be04918314gstein** when generating XML. This means that "no prefix" will always
f6b86fd524444dacf82f64148300d8be04918314gstein** mean "no namespace".
f6b86fd524444dacf82f64148300d8be04918314gstein** In both cases, the XML generation will avoid prepending a prefix.
f6b86fd524444dacf82f64148300d8be04918314gstein** For the first case, this means the original prefix/name will be
f6b86fd524444dacf82f64148300d8be04918314gstein** inserted into the output stream. For the latter case, it means
f6b86fd524444dacf82f64148300d8be04918314gstein** the name will have no prefix, and since we never define a default
f6b86fd524444dacf82f64148300d8be04918314gstein** namespace, this means it will have no namespace.
f6b86fd524444dacf82f64148300d8be04918314gstein** Note: currently, mod_dav understands the "xmlns" prefix and the
f6b86fd524444dacf82f64148300d8be04918314gstein** "xml:lang" attribute. These are handled specially (they aren't
f6b86fd524444dacf82f64148300d8be04918314gstein** left within the XML tree), so the AP_XML_NS_NONE value won't ever
f6b86fd524444dacf82f64148300d8be04918314gstein** really apply to these values.
f6b86fd524444dacf82f64148300d8be04918314gstein#define AP_XML_NS_DAV_ID 0 /* namespace ID for "DAV:" */
f6b86fd524444dacf82f64148300d8be04918314gstein#define AP_XML_NS_NONE -10 /* no namespace for this elem/attr */
f6b86fd524444dacf82f64148300d8be04918314gstein#define AP_XML_NS_ERROR_BASE -100 /* used only during processing */
f6b86fd524444dacf82f64148300d8be04918314gstein#define AP_XML_NS_IS_ERROR(e) ((e) <= AP_XML_NS_ERROR_BASE)
155c41995a4728123ceb4c637df8e2aaf0d7223frbb/** ap_xml_attr: holds a parsed XML attribute */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** attribute name */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb const char *name;
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** index into namespace array */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** attribute value */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb const char *value;
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** next attribute
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @defvar ap_xml_attr *next */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb/** ap_xml_elem: holds a parsed XML element */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** element name */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb const char *name;
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** index into namespace array */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** xml:lang for attrs/contents */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb const char *lang;
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** cdata right after start tag */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** cdata after MY end tag */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** parent element
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @defvar ap_xml_elem *parent */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** next (sibling) element
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @defvar ap_xml_elem *next */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** first child element
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @defvar ap_xml_elem *first_child */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** first attribute
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @defvar ap_xml_attr *attr */
f6b86fd524444dacf82f64148300d8be04918314gstein /* used only during parsing */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** last child element
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @defvar ap_xml_elem *last_child */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** namespaces scoped by this elem
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @defvar ap_xml_ns_scope *ns_scope */
f6b86fd524444dacf82f64148300d8be04918314gstein /* used by modules during request processing */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** Place for modules to store private data */
f6b86fd524444dacf82f64148300d8be04918314gstein#define AP_XML_ELEM_IS_EMPTY(e) ((e)->first_child == NULL && \
155c41995a4728123ceb4c637df8e2aaf0d7223frbb/** ap_xml_doc: holds a parsed XML document */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** root element */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb /** array of namespaces used */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * Get XML post data and parse it
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param r The current request
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param pdoc The XML post data
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @return HTTP status code
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @deffunc int ap_xml_parse_input(request_rec *r, ap_xml_doc **pdoc)
f6b86fd524444dacf82f64148300d8be04918314gsteinAPI_EXPORT(int) ap_xml_parse_input(request_rec *r, ap_xml_doc **pdoc);
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * Converts an XML element tree to flat text
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param p The pool to allocate out of
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param elem The XML element to convert
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param style How to covert the XML. One of:
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * AP_XML_X2T_FULL start tag, contents, end tag
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * AP_XML_X2T_INNER contents only
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * AP_XML_X2T_LANG_INNER xml:lang + inner contents
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * AP_XML_X2T_FULL_NS_LANG FULL + ns defns + xml:lang
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param namespaces The namespace of the current XML element
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param ns_map Namespace mapping
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param pbuf Buffer to put the converted text into
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param psize Size of the converted text
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @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);
1ccd992d37d62c8cb2056126f2234f64ec189bfddougmAPI_EXPORT(void) ap_xml_to_text(apr_pool_t *p, const ap_xml_elem *elem,
f6b86fd524444dacf82f64148300d8be04918314gstein/* style argument values: */
f6b86fd524444dacf82f64148300d8be04918314gstein#define AP_XML_X2T_FULL 0 /* start tag, contents, end tag */
f6b86fd524444dacf82f64148300d8be04918314gstein#define AP_XML_X2T_LANG_INNER 2 /* xml:lang + inner contents */
f6b86fd524444dacf82f64148300d8be04918314gstein#define AP_XML_X2T_FULL_NS_LANG 3 /* FULL + ns defns + xml:lang */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * empty XML element
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param p The pool to allocate out of
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param elem The XML element to empty
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @return the string that was stored in the XML element
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @deffunc const char *ap_xml_empty_elem(apr_pool_t *p, const ap_xml_elem *elem)
1ccd992d37d62c8cb2056126f2234f64ec189bfddougmAPI_EXPORT(const char *) ap_xml_empty_elem(apr_pool_t *p,
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * quote an XML string
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * Replace '<', '>', and '&' with '<', '>', and '&'.
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param p The pool to allocate out of
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param s The string to quote
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param quotes If quotes is true, then replace '"' with '"'.
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @return The quoted string
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @deffunc const char *ap_xml_quote_string(apr_pool_t *p, const char *s, int quotes)
1ccd992d37d62c8cb2056126f2234f64ec189bfddougmAPI_EXPORT(const char *) ap_xml_quote_string(apr_pool_t *p, const char *s,
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * Quote an XML element
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param p The pool to allocate out of
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param elem The element to quote
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @deffunc void ap_xml_quote_elem(apr_pool_t *p, ap_xml_elem *elem)
1ccd992d37d62c8cb2056126f2234f64ec189bfddougmAPI_EXPORT(void) ap_xml_quote_elem(apr_pool_t *p, ap_xml_elem *elem);
f6b86fd524444dacf82f64148300d8be04918314gstein/* manage an array of unique URIs: ap_xml_insert_uri() and AP_XML_URI_ITEM() */
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * return the URI's (existing) index, or insert it and return a new index
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param uri_array array to insert into
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @param uri The uri to insert
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @return int The uri's index
155c41995a4728123ceb4c637df8e2aaf0d7223frbb * @deffunc int ap_xml_insert_uri(apr_array_header_t *uri_array, const char *uri)
1ccd992d37d62c8cb2056126f2234f64ec189bfddougmAPI_EXPORT(int) ap_xml_insert_uri(apr_array_header_t *uri_array,
f6b86fd524444dacf82f64148300d8be04918314gstein const char *uri);
f6b86fd524444dacf82f64148300d8be04918314gstein#define AP_XML_GET_URI_ITEM(ary, i) (((const char * const *)(ary)->elts)[i])
f6b86fd524444dacf82f64148300d8be04918314gstein#endif /* UTIL_XML_H */