1
/* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
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
8
* http://www.apache.org/licenses/LICENSE-2.0
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.
18
* @brief APR-UTIL XML Library
24
* @defgroup APR_Util_XML XML
28
#include "apr_pools.h"
29
#include "apr_tables.h"
30
#include "apr_file_io.h"
33
#if APR_CHARSET_EBCDIC
34
#include "apr_xlate.h"
42
* @package Apache XML library
45
/* -------------------------------------------------------------------- */
47
/* ### these will need to move at some point to a more logical spot */
50
typedef struct apr_text apr_text;
52
/** Structure to keep a linked list of pieces of text */
54
/** The current piece of text */
56
/** a pointer to the next piece of text */
57
struct apr_text *next;
60
/** @see apr_text_header */
61
typedef struct apr_text_header apr_text_header;
63
/** A list of pieces of text */
64
struct apr_text_header {
65
/** The first piece of text in the list */
67
/** The last piece of text in the list */
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
77
APU_DECLARE(void) apr_text_append(apr_pool_t *p, apr_text_header *hdr,
81
/* --------------------------------------------------------------------
87
** Qualified namespace values
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.
95
** This special ID is used for two situations:
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.
105
** 2) The element/attribute does not have a namespace.
107
** a) No prefix was used, and a default namespace has not been
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)
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".
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.
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.
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 */
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)
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;
147
/** apr_xml_attr: holds a parsed XML attribute */
148
struct apr_xml_attr {
149
/** attribute name */
151
/** index into namespace array */
154
/** attribute value */
157
/** next attribute */
158
struct apr_xml_attr *next;
161
/** apr_xml_elem: holds a parsed XML element */
162
struct apr_xml_elem {
165
/** index into namespace array */
167
/** xml:lang for attrs/contents */
170
/** cdata right after start tag */
171
apr_text_header first_cdata;
172
/** cdata after MY end tag */
173
apr_text_header following_cdata;
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;
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;
190
/* used by modules during request processing */
191
/** Place for modules to store private data */
195
/** Is this XML element empty? */
196
#define APR_XML_ELEM_IS_EMPTY(e) ((e)->first_child == NULL && \
197
(e)->first_cdata.first == NULL)
199
/** apr_xml_doc: holds a parsed XML document */
203
/** array of namespaces used */
204
apr_array_header_t *namespaces;
207
/** Opaque XML parser structure */
208
typedef struct apr_xml_parser apr_xml_parser;
211
* Create an XML parser
212
* @param pool The pool for allocating the parser and the parse results.
213
* @return The new parser.
215
APU_DECLARE(apr_xml_parser *) apr_xml_parser_create(apr_pool_t *pool);
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 successfull 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.
227
APU_DECLARE(apr_status_t) apr_xml_parse_file(apr_pool_t *p,
228
apr_xml_parser **parser,
231
apr_size_t buffer_length);
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.
242
APU_DECLARE(apr_status_t) apr_xml_parser_feed(apr_xml_parser *parser,
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.
254
APU_DECLARE(apr_status_t) apr_xml_parser_done(apr_xml_parser *parser,
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
264
APU_DECLARE(char *) apr_xml_parser_geterror(apr_xml_parser *parser,
266
apr_size_t errbufsize);
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:
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
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
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,
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 */
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
302
APU_DECLARE(const char *) apr_xml_empty_elem(apr_pool_t *p,
303
const apr_xml_elem *elem);
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.
315
APU_DECLARE(const char *) apr_xml_quote_string(apr_pool_t *p, const char *s,
319
* Quote an XML element
320
* @param p The pool to allocate out of
321
* @param elem The element to quote
323
APU_DECLARE(void) apr_xml_quote_elem(apr_pool_t *p, apr_xml_elem *elem);
325
/* manage an array of unique URIs: apr_xml_insert_uri() and APR_XML_URI_ITEM() */
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
333
APU_DECLARE(int) apr_xml_insert_uri(apr_array_header_t *uri_array,
336
/** Get the URI item for this XML element */
337
#define APR_XML_GET_URI_ITEM(ary, i) (((const char * const *)(ary)->elts)[i])
339
#if APR_CHARSET_EBCDIC
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.
347
APU_DECLARE(apr_status_t) apr_xml_parser_convert_doc(apr_pool_t *p,
349
apr_xlate_t *convset);
356
#endif /* APR_XML_H */
added
removed
srclib/apr-util/include/apr_xml.h
