GME  13
Defines | Typedefs | Enumerations | Functions
svn_xml.h File Reference

XML code shared by various Subversion libraries. More...

Go to the source code of this file.

Defines

#define SVN_XML_NAMESPACE   "svn:"

Typedefs

typedef struct svn_xml_parser_t svn_xml_parser_t
typedef void(* svn_xml_start_elem )(void *baton, const char *name, const char **atts)
typedef void(* svn_xml_end_elem )(void *baton, const char *name)
typedef void(* svn_xml_char_data )(void *baton, const char *data, apr_size_t len)

Enumerations

enum  svn_xml_open_tag_style { svn_xml_normal = 1, svn_xml_protect_pcdata, svn_xml_self_closing }

Functions

svn_boolean_t svn_xml_is_xml_safe (const char *data, apr_size_t len)
void svn_xml_escape_cdata_stringbuf (svn_stringbuf_t **outstr, const svn_stringbuf_t *string, apr_pool_t *pool)
void svn_xml_escape_cdata_string (svn_stringbuf_t **outstr, const svn_string_t *string, apr_pool_t *pool)
void svn_xml_escape_cdata_cstring (svn_stringbuf_t **outstr, const char *string, apr_pool_t *pool)
void svn_xml_escape_attr_stringbuf (svn_stringbuf_t **outstr, const svn_stringbuf_t *string, apr_pool_t *pool)
void svn_xml_escape_attr_string (svn_stringbuf_t **outstr, const svn_string_t *string, apr_pool_t *pool)
void svn_xml_escape_attr_cstring (svn_stringbuf_t **outstr, const char *string, apr_pool_t *pool)
const char * svn_xml_fuzzy_escape (const char *string, apr_pool_t *pool)
svn_xml_parser_tsvn_xml_make_parser (void *baton, svn_xml_start_elem start_handler, svn_xml_end_elem end_handler, svn_xml_char_data data_handler, apr_pool_t *pool)
void svn_xml_free_parser (svn_xml_parser_t *svn_parser)
svn_error_tsvn_xml_parse (svn_xml_parser_t *svn_parser, const char *buf, apr_size_t len, svn_boolean_t is_final)
void svn_xml_signal_bailout (svn_error_t *error, svn_xml_parser_t *svn_parser)
const char * svn_xml_get_attr_value (const char *name, const char *const *atts)
apr_hash_tsvn_xml_ap_to_hash (va_list ap, apr_pool_t *pool)
apr_hash_tsvn_xml_make_att_hash (const char **atts, apr_pool_t *pool)
void svn_xml_hash_atts_preserving (const char **atts, apr_hash_t *ht, apr_pool_t *pool)
void svn_xml_hash_atts_overlaying (const char **atts, apr_hash_t *ht, apr_pool_t *pool)
void svn_xml_make_header2 (svn_stringbuf_t **str, const char *encoding, apr_pool_t *pool)
SVN_DEPRECATED void svn_xml_make_header (svn_stringbuf_t **str, apr_pool_t *pool)
void svn_xml_make_open_tag (svn_stringbuf_t **str, apr_pool_t *pool, enum svn_xml_open_tag_style style, const char *tagname,...)
void svn_xml_make_open_tag_v (svn_stringbuf_t **str, apr_pool_t *pool, enum svn_xml_open_tag_style style, const char *tagname, va_list ap)
void svn_xml_make_open_tag_hash (svn_stringbuf_t **str, apr_pool_t *pool, enum svn_xml_open_tag_style style, const char *tagname, apr_hash_t *attributes)
void svn_xml_make_close_tag (svn_stringbuf_t **str, apr_pool_t *pool, const char *tagname)

Detailed Description

XML code shared by various Subversion libraries.

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ====================================================================

Definition in file svn_xml.h.


Define Documentation

#define SVN_XML_NAMESPACE   "svn:"

The namespace all Subversion XML uses.

Definition at line 42 of file svn_xml.h.


Typedef Documentation

typedef void(* svn_xml_char_data)(void *baton, const char *data, apr_size_t len)

Definition at line 167 of file svn_xml.h.

typedef void(* svn_xml_end_elem)(void *baton, const char *name)

Definition at line 164 of file svn_xml.h.

A generalized Subversion XML parser object

Definition at line 158 of file svn_xml.h.

typedef void(* svn_xml_start_elem)(void *baton, const char *name, const char **atts)

Definition at line 160 of file svn_xml.h.


Enumeration Type Documentation

Used as style argument to svn_xml_make_open_tag() and friends.

Enumerator:
svn_xml_normal 

<tag ...>

svn_xml_protect_pcdata 

<tag ...>, no cosmetic newline

svn_xml_self_closing 

<tag .../>

Definition at line 45 of file svn_xml.h.


Function Documentation

apr_hash_t* svn_xml_ap_to_hash ( va_list  ap,
apr_pool_t pool 
)

Create an attribute hash from va_list ap.

The contents of ap are alternating char * keys and char * vals, terminated by a final NULL falling on an even index (zero-based).

void svn_xml_escape_attr_cstring ( svn_stringbuf_t **  outstr,
const char *  string,
apr_pool_t pool 
)

Same as svn_xml_escape_attr_stringbuf(), but string is a NULL-terminated C string.

void svn_xml_escape_attr_string ( svn_stringbuf_t **  outstr,
const svn_string_t string,
apr_pool_t pool 
)

Same as svn_xml_escape_attr_stringbuf(), but string is an svn_string_t.

void svn_xml_escape_attr_stringbuf ( svn_stringbuf_t **  outstr,
const svn_stringbuf_t string,
apr_pool_t pool 
)

Create or append in *outstr an xml-escaped version of string, suitable for output as an attribute value.

If *outstr is NULL, set *outstr to a new stringbuf allocated in pool, else append to the existing stringbuf there.

void svn_xml_escape_cdata_cstring ( svn_stringbuf_t **  outstr,
const char *  string,
apr_pool_t pool 
)

Same as svn_xml_escape_cdata_stringbuf(), but string is a NULL-terminated C string.

void svn_xml_escape_cdata_string ( svn_stringbuf_t **  outstr,
const svn_string_t string,
apr_pool_t pool 
)

Same as svn_xml_escape_cdata_stringbuf(), but string is an svn_string_t.

void svn_xml_escape_cdata_stringbuf ( svn_stringbuf_t **  outstr,
const svn_stringbuf_t string,
apr_pool_t pool 
)

Create or append in *outstr an xml-escaped version of string, suitable for output as character data.

If *outstr is NULL, set *outstr to a new stringbuf allocated in pool, else append to the existing stringbuf there.

void svn_xml_free_parser ( svn_xml_parser_t svn_parser)

Free a general Subversion XML parser

const char* svn_xml_fuzzy_escape ( const char *  string,
apr_pool_t pool 
)

Return UTF-8 string string if it contains no characters that are unrepresentable in XML. Else, return a copy of string, allocated in pool, with each unrepresentable character replaced by "?\uuu", where "uuu" is the three-digit unsigned decimal value of that character.

Neither the input nor the output need be valid XML; however, the output can always be safely XML-escaped.

Note:
The current implementation treats all Unicode characters as representable, except for most ASCII control characters (the exceptions being CR, LF, and TAB, which are valid in XML). There may be other UTF-8 characters that are invalid in XML; see http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=90591 and its thread for details.
Since:
New in 1.2.
const char* svn_xml_get_attr_value ( const char *  name,
const char *const *  atts 
)

Return the value associated with name in expat attribute array atts, else return NULL.

(There could never be a NULL attribute value in the XML, although the empty string is possible.)

atts is an array of c-strings: even-numbered indexes are names, odd-numbers hold values. If all is right, it should end on an even-numbered index pointing to NULL.

void svn_xml_hash_atts_overlaying ( const char **  atts,
apr_hash_t ht,
apr_pool_t pool 
)

Like svn_xml_make_att_hash(), but takes a hash and overwrites key/value pairs already in it that also appear in atts.

void svn_xml_hash_atts_preserving ( const char **  atts,
apr_hash_t ht,
apr_pool_t pool 
)

Like svn_xml_make_att_hash(), but takes a hash and preserves any key/value pairs already in it.

svn_boolean_t svn_xml_is_xml_safe ( const char *  data,
apr_size_t  len 
)

Determine if a string of character data of length len is a safe bet for use with the svn_xml_escape_* functions found in this header.

Return TRUE if it is, FALSE otherwise.

Essentially, this function exists to determine whether or not simply running a string of bytes through the Subversion XML escape routines will produce legitimate XML. It should only be necessary for data which might contain bytes that cannot be safely encoded into XML (certain control characters, for example).

apr_hash_t* svn_xml_make_att_hash ( const char **  atts,
apr_pool_t pool 
)

Create a hash that corresponds to Expat xml attribute list atts.

The hash's keys and values are char *'s.

atts may be NULL, in which case you just get an empty hash back (this makes life more convenient for some callers).

void svn_xml_make_close_tag ( svn_stringbuf_t **  str,
apr_pool_t pool,
const char *  tagname 
)

Store an xml close tag tagname in str.

If *str is NULL, set *str to a new stringbuf allocated in pool, else append to the existing stringbuf there.

Like svn_xml_make_header2(), but does not emit encoding information.

Deprecated:
Provided for backward compatibility with the 1.6 API.
void svn_xml_make_header2 ( svn_stringbuf_t **  str,
const char *  encoding,
apr_pool_t pool 
)

Create an XML header and return it in *str.

Fully-formed XML documents should start out with a header, something like

         <?xml version="1.0" encoding="UTF-8"?>
 

This function returns such a header. *str must either be NULL, in which case a new string is created, or it must point to an existing string to be appended to. encoding must either be NULL, in which case encoding information is omitted from the header, or must be the name of the encoding of the XML document, such as "UTF-8".

Since:
New in 1.7.
void svn_xml_make_open_tag ( svn_stringbuf_t **  str,
apr_pool_t pool,
enum svn_xml_open_tag_style  style,
const char *  tagname,
  ... 
)

Store a new xml tag tagname in *str.

If *str is NULL, set *str to a new stringbuf allocated in pool, else append to the existing stringbuf there.

Take the tag's attributes from varargs, a NULL-terminated list of alternating char * key and char * val. Do xml-escaping on each val.

style is one of the enumerated styles in svn_xml_open_tag_style.

void svn_xml_make_open_tag_hash ( svn_stringbuf_t **  str,
apr_pool_t pool,
enum svn_xml_open_tag_style  style,
const char *  tagname,
apr_hash_t attributes 
)

Like svn_xml_make_open_tag(), but takes a hash table of attributes (char * keys mapping to char * values).

You might ask, why not just provide svn_xml_make_tag_atts()?

The reason is that a hash table is the most natural interface to an attribute list; the fact that Expat uses char ** atts instead is certainly a defensible implementation decision, but since we'd have to have special code to support such lists throughout Subversion anyway, we might as well write that code for the natural interface (hashes) and then convert in the few cases where conversion is needed. Someday it might even be nice to change expat-lite to work with apr hashes.

See conversion functions svn_xml_make_att_hash() and svn_xml_make_att_hash_overlaying(). Callers should use those to convert Expat attr lists into hashes when necessary.

void svn_xml_make_open_tag_v ( svn_stringbuf_t **  str,
apr_pool_t pool,
enum svn_xml_open_tag_style  style,
const char *  tagname,
va_list  ap 
)

Like svn_xml_make_open_tag(), but takes a va_list instead of being variadic.

svn_xml_parser_t* svn_xml_make_parser ( void *  baton,
svn_xml_start_elem  start_handler,
svn_xml_end_elem  end_handler,
svn_xml_char_data  data_handler,
apr_pool_t pool 
)

Create a general Subversion XML parser

svn_error_t* svn_xml_parse ( svn_xml_parser_t svn_parser,
const char *  buf,
apr_size_t  len,
svn_boolean_t  is_final 
)

Push len bytes of xml data in buf at svn_parser.

If this is the final push, is_final must be set.

An error will be returned if there was a syntax problem in the XML, or if any of the callbacks set an error using svn_xml_signal_bailout().

If an error is returned, the svn_xml_parser_t will have been freed automatically, so the caller should not call svn_xml_free_parser().

void svn_xml_signal_bailout ( svn_error_t error,
svn_xml_parser_t svn_parser 
)

The way to officially bail out of xml parsing.

Store error in svn_parser and set all expat callbacks to NULL.