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