github.com/krum110487/go-htaccess@v0.0.0-20240316004156-60641c8e7598/tests/data/apache_2_2_34/include/apr_xml.h (about) 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 */