Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_xml.h
Go to the documentation of this file.
1 /**
2  * @copyright
3  * ====================================================================
4  * Licensed to the Apache Software Foundation (ASF) under one
5  * or more contributor license agreements. See the NOTICE file
6  * distributed with this work for additional information
7  * regarding copyright ownership. The ASF licenses this file
8  * to you under the Apache License, Version 2.0 (the
9  * "License"); you may not use this file except in compliance
10  * with the License. You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing,
15  * software distributed under the License is distributed on an
16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17  * KIND, either express or implied. See the License for the
18  * specific language governing permissions and limitations
19  * under the License.
20  * ====================================================================
21  * @endcopyright
22  *
23  * @file svn_xml.h
24  * @brief XML code shared by various Subversion libraries.
25  */
26 
27 #ifndef SVN_XML_H
28 #define SVN_XML_H
29 
30 #include <apr.h>
31 #include <apr_pools.h>
32 #include <apr_hash.h>
33 
34 #include "svn_types.h"
35 #include "svn_string.h"
36 
37 #ifdef __cplusplus
38 extern "C" {
39 #endif /* __cplusplus */
40 
41 /** The namespace all Subversion XML uses. */
42 #define SVN_XML_NAMESPACE "svn:"
43 
44 /** Used as style argument to svn_xml_make_open_tag() and friends. */
46  /** <tag ...> */
48 
49  /** <tag ...>, no cosmetic newline */
51 
52  /** <tag .../> */
54 };
55 
56 
57 
58 /** Determine if a string of character @a data of length @a len is a
59  * safe bet for use with the svn_xml_escape_* functions found in this
60  * header.
61  *
62  * Return @c TRUE if it is, @c FALSE otherwise.
63  *
64  * Essentially, this function exists to determine whether or not
65  * simply running a string of bytes through the Subversion XML escape
66  * routines will produce legitimate XML. It should only be necessary
67  * for data which might contain bytes that cannot be safely encoded
68  * into XML (certain control characters, for example).
69  */
71 svn_xml_is_xml_safe(const char *data,
72  apr_size_t len);
73 
74 /** Create or append in @a *outstr an xml-escaped version of @a string,
75  * suitable for output as character data.
76  *
77  * If @a *outstr is @c NULL, set @a *outstr to a new stringbuf allocated
78  * in @a pool, else append to the existing stringbuf there.
79  */
80 void
82  const svn_stringbuf_t *string,
83  apr_pool_t *pool);
84 
85 /** Same as svn_xml_escape_cdata_stringbuf(), but @a string is an
86  * @c svn_string_t.
87  */
88 void
90  const svn_string_t *string,
91  apr_pool_t *pool);
92 
93 /** Same as svn_xml_escape_cdata_stringbuf(), but @a string is a
94  * NULL-terminated C string.
95  */
96 void
98  const char *string,
99  apr_pool_t *pool);
100 
101 
102 /** Create or append in @a *outstr an xml-escaped version of @a string,
103  * suitable for output as an attribute value.
104  *
105  * If @a *outstr is @c NULL, set @a *outstr to a new stringbuf allocated
106  * in @a pool, else append to the existing stringbuf there.
107  */
108 void
110  const svn_stringbuf_t *string,
111  apr_pool_t *pool);
112 
113 /** Same as svn_xml_escape_attr_stringbuf(), but @a string is an
114  * @c svn_string_t.
115  */
116 void
118  const svn_string_t *string,
119  apr_pool_t *pool);
120 
121 /** Same as svn_xml_escape_attr_stringbuf(), but @a string is a
122  * NULL-terminated C string.
123  */
124 void
126  const char *string,
127  apr_pool_t *pool);
128 
129 /**
130  * Return UTF-8 string @a string if it contains no characters that are
131  * unrepresentable in XML. Else, return a copy of @a string,
132  * allocated in @a pool, with each unrepresentable character replaced
133  * by "?\uuu", where "uuu" is the three-digit unsigned decimal value
134  * of that character.
135  *
136  * Neither the input nor the output need be valid XML; however, the
137  * output can always be safely XML-escaped.
138  *
139  * @note The current implementation treats all Unicode characters as
140  * representable, except for most ASCII control characters (the
141  * exceptions being CR, LF, and TAB, which are valid in XML). There
142  * may be other UTF-8 characters that are invalid in XML; see
143  * http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=90591
144  * and its thread for details.
145  *
146  * @since New in 1.2.
147  */
148 const char *
149 svn_xml_fuzzy_escape(const char *string,
150  apr_pool_t *pool);
151 
152 
153 /*---------------------------------------------------------------*/
154 
155 /* Generalized Subversion XML Parsing */
156 
157 /** A generalized Subversion XML parser object */
159 
160 typedef void (*svn_xml_start_elem)(void *baton,
161  const char *name,
162  const char **atts);
163 
164 typedef void (*svn_xml_end_elem)(void *baton, const char *name);
165 
166 /* data is not NULL-terminated. */
167 typedef void (*svn_xml_char_data)(void *baton,
168  const char *data,
169  apr_size_t len);
170 
171 
172 /** Create a general Subversion XML parser */
174 svn_xml_make_parser(void *baton,
175  svn_xml_start_elem start_handler,
176  svn_xml_end_elem end_handler,
177  svn_xml_char_data data_handler,
178  apr_pool_t *pool);
179 
180 
181 /** Free a general Subversion XML parser */
182 void
184 
185 
186 /** Push @a len bytes of xml data in @a buf at @a svn_parser.
187  *
188  * If this is the final push, @a is_final must be set.
189  *
190  * An error will be returned if there was a syntax problem in the XML,
191  * or if any of the callbacks set an error using
192  * svn_xml_signal_bailout().
193  *
194  * If an error is returned, the @c svn_xml_parser_t will have been freed
195  * automatically, so the caller should not call svn_xml_free_parser().
196  */
197 svn_error_t *
198 svn_xml_parse(svn_xml_parser_t *svn_parser,
199  const char *buf,
200  apr_size_t len,
201  svn_boolean_t is_final);
202 
203 
204 
205 /** The way to officially bail out of xml parsing.
206  *
207  * Store @a error in @a svn_parser and set all expat callbacks to @c NULL.
208  */
209 void
211  svn_xml_parser_t *svn_parser);
212 
213 
214 
215 
216 
217 /*** Helpers for dealing with the data Expat gives us. ***/
218 
219 /** Return the value associated with @a name in expat attribute array @a atts,
220  * else return @c NULL.
221  *
222  * (There could never be a @c NULL attribute value in the XML,
223  * although the empty string is possible.)
224  *
225  * @a atts is an array of c-strings: even-numbered indexes are names,
226  * odd-numbers hold values. If all is right, it should end on an
227  * even-numbered index pointing to @c NULL.
228  */
229 const char *
230 svn_xml_get_attr_value(const char *name,
231  const char *const *atts);
232 
233 
234 
235 /* Converting between Expat attribute lists and APR hash tables. */
236 
237 
238 /** Create an attribute hash from @c va_list @a ap.
239  *
240  * The contents of @a ap are alternating <tt>char *</tt> keys and
241  * <tt>char *</tt> vals, terminated by a final @c NULL falling on an
242  * even index (zero-based).
243  */
244 apr_hash_t *
245 svn_xml_ap_to_hash(va_list ap,
246  apr_pool_t *pool);
247 
248 /** Create a hash that corresponds to Expat xml attribute list @a atts.
249  *
250  * The hash's keys and values are <tt>char *</tt>'s.
251  *
252  * @a atts may be NULL, in which case you just get an empty hash back
253  * (this makes life more convenient for some callers).
254  */
255 apr_hash_t *
256 svn_xml_make_att_hash(const char **atts,
257  apr_pool_t *pool);
258 
259 
260 /** Like svn_xml_make_att_hash(), but takes a hash and preserves any
261  * key/value pairs already in it.
262  */
263 void
264 svn_xml_hash_atts_preserving(const char **atts,
265  apr_hash_t *ht,
266  apr_pool_t *pool);
267 
268 /** Like svn_xml_make_att_hash(), but takes a hash and overwrites
269  * key/value pairs already in it that also appear in @a atts.
270  */
271 void
272 svn_xml_hash_atts_overlaying(const char **atts,
273  apr_hash_t *ht,
274  apr_pool_t *pool);
275 
276 
277 
278 /* Printing XML */
279 
280 /** Create an XML header and return it in @a *str.
281  *
282  * Fully-formed XML documents should start out with a header,
283  * something like <pre>
284  * <?xml version="1.0" encoding="UTF-8"?>
285  * </pre>
286  *
287  * This function returns such a header. @a *str must either be @c NULL, in
288  * which case a new string is created, or it must point to an existing
289  * string to be appended to. @a encoding must either be NULL, in which case
290  * encoding information is omitted from the header, or must be the name of
291  * the encoding of the XML document, such as "UTF-8".
292  *
293  * @since New in 1.7.
294  */
295 void
297  const char *encoding,
298  apr_pool_t *pool);
299 
300 /** Like svn_xml_make_header2(), but does not emit encoding information.
301  *
302  * @deprecated Provided for backward compatibility with the 1.6 API.
303  */
305 void
307  apr_pool_t *pool);
308 
309 
310 /** Store a new xml tag @a tagname in @a *str.
311  *
312  * If @a *str is @c NULL, set @a *str to a new stringbuf allocated
313  * in @a pool, else append to the existing stringbuf there.
314  *
315  * Take the tag's attributes from varargs, a SVN_VA_NULL-terminated list of
316  * alternating <tt>char *</tt> key and <tt>char *</tt> val. Do xml-escaping
317  * on each val.
318  *
319  * @a style is one of the enumerated styles in @c svn_xml_open_tag_style.
320  */
321 void
323  apr_pool_t *pool,
324  enum svn_xml_open_tag_style style,
325  const char *tagname,
327 
328 
329 /** Like svn_xml_make_open_tag(), but takes a @c va_list instead of being
330  * variadic.
331  */
332 void
334  apr_pool_t *pool,
335  enum svn_xml_open_tag_style style,
336  const char *tagname,
337  va_list ap);
338 
339 
340 /** Like svn_xml_make_open_tag(), but takes a hash table of attributes
341  * (<tt>char *</tt> keys mapping to <tt>char *</tt> values).
342  *
343  * You might ask, why not just provide svn_xml_make_tag_atts()?
344  *
345  * The reason is that a hash table is the most natural interface to an
346  * attribute list; the fact that Expat uses <tt>char **</tt> atts instead is
347  * certainly a defensible implementation decision, but since we'd have
348  * to have special code to support such lists throughout Subversion
349  * anyway, we might as well write that code for the natural interface
350  * (hashes) and then convert in the few cases where conversion is
351  * needed. Someday it might even be nice to change expat-lite to work
352  * with apr hashes.
353  *
354  * See conversion functions svn_xml_make_att_hash() and
355  * svn_xml_make_att_hash_overlaying(). Callers should use those to
356  * convert Expat attr lists into hashes when necessary.
357  */
358 void
360  apr_pool_t *pool,
361  enum svn_xml_open_tag_style style,
362  const char *tagname,
363  apr_hash_t *attributes);
364 
365 
366 /** Store an xml close tag @a tagname in @a str.
367  *
368  * If @a *str is @c NULL, set @a *str to a new stringbuf allocated
369  * in @a pool, else append to the existing stringbuf there.
370  */
371 void
373  apr_pool_t *pool,
374  const char *tagname);
375 
376 
377 #ifdef __cplusplus
378 }
379 #endif /* __cplusplus */
380 
381 #endif /* SVN_XML_H */