← Back to branch summary

~alinuxninja/nginx-edge/trunk

« back to all changes in this revision

Viewing changes to debian/modules/ngx_pagespeed/psol/include/third_party/aprutil/src/include/apr_xml.h

  • Committer: Vivian
  • Date: 2015-12-04 18:20:11 UTC
  • Revision ID: git-v1:a36f2bc32e884f7473b3a47040e5411306144d7d
* Do not extract psol.tar.gz

Show diffs side-by-side

added added

removed removed

Lines of Context:
debian/modules/ngx_pagespeed/psol/include/third_party/aprutil/src/include/apr_xml.h
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 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.
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 '&lt;', '&gt;', and '&amp;'.
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 '&quot;'.
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 */