XML

XML — XML and XML Writer

Synopsis




typedef     raptor_xml_element;
raptor_xml_element* raptor_new_xml_element  (raptor_qname *name,
                                             unsigned char *xml_language,
                                             raptor_uri *xml_base);
void        raptor_free_xml_element         (raptor_xml_element *element);
raptor_qname* raptor_xml_element_get_name   (raptor_xml_element *xml_element);
void        raptor_xml_element_set_attributes
                                            (raptor_xml_element *xml_element,
                                             raptor_qname **attributes,
                                             int count);
void        raptor_xml_element_declare_namespace
                                            (raptor_xml_element *xml_element,
                                             raptor_namespace *nspace);
raptor_xml_writer* raptor_new_xml_writer    (raptor_namespace_stack *nstack,
                                             raptor_uri_handler *uri_handler,
                                             void *uri_context,
                                             raptor_iostream *iostr,
                                             raptor_simple_message_handler error_handler,
                                             void *error_data,
                                             int canonicalize);
void        raptor_free_xml_writer          (raptor_xml_writer *xml_writer);
void        raptor_xml_writer_empty_element (raptor_xml_writer *xml_writer,
                                             raptor_xml_element *element);
void        raptor_xml_writer_start_element (raptor_xml_writer *xml_writer,
                                             raptor_xml_element *element);
void        raptor_xml_writer_end_element   (raptor_xml_writer *xml_writer,
                                             raptor_xml_element *element);
void        raptor_xml_writer_cdata         (raptor_xml_writer *xml_writer,
                                             unsigned char *s);
void        raptor_xml_writer_cdata_counted (raptor_xml_writer *xml_writer,
                                             unsigned char *s,
                                             unsigned int len);
void        raptor_xml_writer_raw           (raptor_xml_writer *xml_writer,
                                             unsigned char *s);
void        raptor_xml_writer_raw_counted   (raptor_xml_writer *xml_writer,
                                             unsigned char *s,
                                             unsigned int len);
void        raptor_xml_writer_comment       (raptor_xml_writer *xml_writer,
                                             unsigned char *s);
void        raptor_xml_writer_comment_counted
                                            (raptor_xml_writer *xml_writer,
                                             unsigned char *s,
                                             unsigned int len);
int         raptor_xml_writer_features_enumerate
                                            (const raptor_feature feature,
                                             const char **name,
                                             raptor_uri **uri,
                                             const char **label);
int         raptor_xml_writer_set_feature   (raptor_xml_writer *xml_writer,
                                             raptor_feature feature,
                                             int value);
int         raptor_xml_writer_set_feature_string
                                            (raptor_xml_writer *xml_writer,
                                             raptor_feature feature,
                                             unsigned char *value);
int         raptor_xml_writer_get_feature   (raptor_xml_writer *xml_writer,
                                             raptor_feature feature);
const unsigned char* raptor_xml_writer_get_feature_string
                                            (raptor_xml_writer *xml_writer,
                                             raptor_feature feature);
int         raptor_iostream_write_xml_element
                                            (raptor_iostream *iostr,
                                             raptor_xml_element *element,
                                             raptor_namespace_stack *nstack,
                                             int is_empty,
                                             int is_end,
                                             raptor_simple_message_handler error_handler,
                                             void *error_data,
                                             int depth);
typedef     raptor_xml_writer;
int         raptor_xml_any_escape_string    (unsigned char *string,
                                             size_t len,
                                             unsigned char *buffer,
                                             size_t length,
                                             char quote,
                                             int xml_version,
                                             raptor_simple_message_handler error_handler,
                                             void *error_data);
int         raptor_xml_escape_string        (unsigned char *string,
                                             size_t len,
                                             unsigned char *buffer,
                                             size_t length,
                                             char quote,
                                             raptor_simple_message_handler error_handler,
                                             void *error_data);
int         raptor_iostream_write_xml_any_escaped_string
                                            (raptor_iostream *iostr,
                                             unsigned char *string,
                                             size_t len,
                                             char quote,
                                             int xml_version,
                                             raptor_simple_message_handler error_handler,
                                             void *error_data);
int         raptor_iostream_write_xml_escaped_string
                                            (raptor_iostream *iostr,
                                             unsigned char *string,
                                             size_t len,
                                             char quote,
                                             raptor_simple_message_handler error_handler,
                                             void *error_data);
int         raptor_xml_name_check           (unsigned char *string,
                                             size_t length,
                                             int xml_version);

Description

XML elements with optional attributes and an XML Writer class that can format raptor_xml_element into output forms, with optional "pretty printing" features such as indenting and collapsing empty elements.

Also includes a utility function raptor_xml_name_check for checking a name is legal in some XML version.

Details

raptor_xml_element

typedef struct raptor_xml_element_s raptor_xml_element;


raptor_new_xml_element ()

raptor_xml_element* raptor_new_xml_element  (raptor_qname *name,
                                             unsigned char *xml_language,
                                             raptor_uri *xml_base);

name :
xml_language :
xml_base :
Returns :

raptor_free_xml_element ()

void        raptor_free_xml_element         (raptor_xml_element *element);

element :

raptor_xml_element_get_name ()

raptor_qname* raptor_xml_element_get_name   (raptor_xml_element *xml_element);

xml_element :
Returns :

raptor_xml_element_set_attributes ()

void        raptor_xml_element_set_attributes
                                            (raptor_xml_element *xml_element,
                                             raptor_qname **attributes,
                                             int count);

xml_element :
attributes :
count :

raptor_xml_element_declare_namespace ()

void        raptor_xml_element_declare_namespace
                                            (raptor_xml_element *xml_element,
                                             raptor_namespace *nspace);

xml_element :
nspace :

raptor_new_xml_writer ()

raptor_xml_writer* raptor_new_xml_writer    (raptor_namespace_stack *nstack,
                                             raptor_uri_handler *uri_handler,
                                             void *uri_context,
                                             raptor_iostream *iostr,
                                             raptor_simple_message_handler error_handler,
                                             void *error_data,
                                             int canonicalize);

nstack :
uri_handler :
uri_context :
iostr :
error_handler :
error_data :
canonicalize :
Returns :

raptor_free_xml_writer ()

void        raptor_free_xml_writer          (raptor_xml_writer *xml_writer);

Free XML writer content.

xml_writer : XML writer object

raptor_xml_writer_empty_element ()

void        raptor_xml_writer_empty_element (raptor_xml_writer *xml_writer,
                                             raptor_xml_element *element);

Write an empty XML element to the XML writer.

Closes any previous empty element if XML writer feature AUTO_EMPTY is enabled.

xml_writer : XML writer object
element : XML element object

raptor_xml_writer_start_element ()

void        raptor_xml_writer_start_element (raptor_xml_writer *xml_writer,
                                             raptor_xml_element *element);

Write a start XML element to the XML writer.

Closes any previous empty element if XML writer feature AUTO_EMPTY is enabled.

Indents the start element if XML writer feature AUTO_INDENT is enabled.

xml_writer : XML writer object
element : XML element object

raptor_xml_writer_end_element ()

void        raptor_xml_writer_end_element   (raptor_xml_writer *xml_writer,
                                             raptor_xml_element *element);

Write an end XML element to the XML writer.

Indents the end element if XML writer feature AUTO_INDENT is enabled.

xml_writer : XML writer object
element : XML element object

raptor_xml_writer_cdata ()

void        raptor_xml_writer_cdata         (raptor_xml_writer *xml_writer,
                                             unsigned char *s);

Write CDATA XML-escaped to the XML writer.

Closes any previous empty element if XML writer feature AUTO_EMPTY is enabled.

xml_writer : XML writer object
s : string to XML escape and write

raptor_xml_writer_cdata_counted ()

void        raptor_xml_writer_cdata_counted (raptor_xml_writer *xml_writer,
                                             unsigned char *s,
                                             unsigned int len);

Write counted CDATA XML-escaped to the XML writer.

Closes any previous empty element if XML writer feature AUTO_EMPTY is enabled.

xml_writer : XML writer object
s : string to XML escape and write
len : length of string

raptor_xml_writer_raw ()

void        raptor_xml_writer_raw           (raptor_xml_writer *xml_writer,
                                             unsigned char *s);

Write a string raw to the XML writer.

Closes any previous empty element if XML writer feature AUTO_EMPTY is enabled.

xml_writer : XML writer object
s : string to write

raptor_xml_writer_raw_counted ()

void        raptor_xml_writer_raw_counted   (raptor_xml_writer *xml_writer,
                                             unsigned char *s,
                                             unsigned int len);

Write a counted string raw to the XML writer.

Closes any previous empty element if XML writer feature AUTO_EMPTY is enabled.

xml_writer : XML writer object
s : string to write
len : length of string

raptor_xml_writer_comment ()

void        raptor_xml_writer_comment       (raptor_xml_writer *xml_writer,
                                             unsigned char *s);

Write an XML comment to the XML writer.

Closes any previous empty element if XML writer feature AUTO_EMPTY is enabled.

xml_writer : XML writer object
s : comment string to write

raptor_xml_writer_comment_counted ()

void        raptor_xml_writer_comment_counted
                                            (raptor_xml_writer *xml_writer,
                                             unsigned char *s,
                                             unsigned int len);

Write a counted XML comment to the XML writer.

Closes any previous empty element if XML writer feature AUTO_EMPTY is enabled.

xml_writer : XML writer object
s : comment string to write
len : length of string

raptor_xml_writer_features_enumerate ()

int         raptor_xml_writer_features_enumerate
                                            (const raptor_feature feature,
                                             const char **name,
                                             raptor_uri **uri,
                                             const char **label);

Get list of xml_writer features.

If uri is not NULL, a pointer toa new raptor_uri is returned that must be freed by the caller with raptor_free_uri().

feature : feature enumeration (0+)
name : pointer to store feature short name (or NULL)
uri : pointer to store feature URI (or NULL)
label : pointer to feature label (or NULL)
Returns : 0 on success, <0 on failure, >0 if feature is unknown

raptor_xml_writer_set_feature ()

int         raptor_xml_writer_set_feature   (raptor_xml_writer *xml_writer,
                                             raptor_feature feature,
                                             int value);

xml_writer :
feature :
value :
Returns :

raptor_xml_writer_set_feature_string ()

int         raptor_xml_writer_set_feature_string
                                            (raptor_xml_writer *xml_writer,
                                             raptor_feature feature,
                                             unsigned char *value);

Set xml_writer features with string values.

The allowed features are available via raptor_xml_writer_features_enumerate(). If the feature type is integer, the value is interpreted as an integer.

xml_writer : raptor_xml_writer xml_writer object
feature : feature to set from enumerated raptor_feature values
value : feature value
Returns : non 0 on failure or if the feature is unknown

raptor_xml_writer_get_feature ()

int         raptor_xml_writer_get_feature   (raptor_xml_writer *xml_writer,
                                             raptor_feature feature);

Get various xml_writer features.

The allowed features are available via raptor_features_enumerate().

Note: no feature value is negative

xml_writer : raptor_xml_writer serializer object
feature : feature to get value
Returns : feature value or < 0 for an illegal feature

raptor_xml_writer_get_feature_string ()

const unsigned char* raptor_xml_writer_get_feature_string
                                            (raptor_xml_writer *xml_writer,
                                             raptor_feature feature);

Get xml_writer features with string values.

The allowed features are available via raptor_features_enumerate().

xml_writer : raptor_xml_writer serializer object
feature : feature to get value
Returns : feature value or NULL for an illegal feature or no value

raptor_iostream_write_xml_element ()

int         raptor_iostream_write_xml_element
                                            (raptor_iostream *iostr,
                                             raptor_xml_element *element,
                                             raptor_namespace_stack *nstack,
                                             int is_empty,
                                             int is_end,
                                             raptor_simple_message_handler error_handler,
                                             void *error_data,
                                             int depth);

Write a formatted XML element to a raptor_iostream

iostr : iostream object
element : XML element to format
nstack : Namespace stack context to use in formatting
is_empty : non-0 if element is empty
is_end : non-0 if this is an end element (else is a start element)
error_handler : error handler function
error_data : error handler function data
depth : XML element depth
Returns : non-0 on failure

raptor_xml_writer

typedef struct raptor_xml_writer_s raptor_xml_writer;


raptor_xml_any_escape_string ()

int         raptor_xml_any_escape_string    (unsigned char *string,
                                             size_t len,
                                             unsigned char *buffer,
                                             size_t length,
                                             char quote,
                                             int xml_version,
                                             raptor_simple_message_handler error_handler,
                                             void *error_data);

string :
len :
buffer :
length :
quote :
xml_version :
error_handler :
error_data :
Returns :

raptor_xml_escape_string ()

int         raptor_xml_escape_string        (unsigned char *string,
                                             size_t len,
                                             unsigned char *buffer,
                                             size_t length,
                                             char quote,
                                             raptor_simple_message_handler error_handler,
                                             void *error_data);

Return an XML 1.0-escaped version a string.

See raptor_xml_any_escape_string() for the conditions on parameters.

string : string to XML 1.0 escape (UTF-8)
len : length of string
buffer : the buffer to use for new string (UTF-8)
length : buffer size
quote : optional quote character to escape for attribute content, or 0
error_handler : error handler function
error_data : error handler user data
Returns : the number of bytes required / used or <0 on failure.

raptor_iostream_write_xml_any_escaped_string ()

int         raptor_iostream_write_xml_any_escaped_string
                                            (raptor_iostream *iostr,
                                             unsigned char *string,
                                             size_t len,
                                             char quote,
                                             int xml_version,
                                             raptor_simple_message_handler error_handler,
                                             void *error_data);

Write an XML-escaped version of a string to an iostream.

See raptor_xml_escape_string() for the escapes performed and the conditions on quote and string. XML 1.1 allows additional characters in XML such as U+0001 to U+001F inclusive.

iostr : the raptor_iostream to write to
string : string to XML escape (UTF-8)
len : length of string
quote : optional quote character to escape for attribute content, or 0
xml_version : XML version - 10 (XML 1.0) or 11 (XML 1.1)
error_handler : error handler function
error_data : error handler data
Returns : non 0 on failure

raptor_iostream_write_xml_escaped_string ()

int         raptor_iostream_write_xml_escaped_string
                                            (raptor_iostream *iostr,
                                             unsigned char *string,
                                             size_t len,
                                             char quote,
                                             raptor_simple_message_handler error_handler,
                                             void *error_data);

Write an XML 1.0-escaped version of a string to an iostream.

See raptor_iostream_write_xml_any_escaped_string() for the escapes performed and the conditions on quote and string.

iostr : the raptor_iostream to write to
string : string to XML 1.0 escape (UTF-8)
len : length of string
quote : optional quote character to escape for attribute content, or 0
error_handler : error handler function
error_data : error handler data
Returns : non 0 on failure

raptor_xml_name_check ()

int         raptor_xml_name_check           (unsigned char *string,
                                             size_t length,
                                             int xml_version);

Check a string is a legal XML name (and legal UTF8).

xml_version is either 10 (for XML 1.0) or 11 for (XML 1.1). Any other version fails.

string : UTF-8 name string
length : length of string
xml_version : XML version
Returns : Non 0 if the string is a legal XML name