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);
raptor_qname** raptor_xml_element_get_attributes
                                            (raptor_xml_element *xml_element);
int         raptor_xml_element_get_attributes_count
                                            (raptor_xml_element *xml_element);
void        raptor_xml_element_set_attributes
                                            (raptor_xml_element *xml_element,
                                             raptor_qname **attributes,
                                             int count);
int         raptor_xml_element_declare_namespace
                                            (raptor_xml_element *xml_element,
                                             raptor_namespace *nspace);
int         raptor_xml_element_is_empty     (raptor_xml_element *xml_element);
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

raptor_xml_element* raptor_xml_element;

Raptor XML Element class


raptor_new_xml_element ()

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

Constructor - create a new XML element

name : The XML element name
xml_language : the in-scope XML language (or NULL)
xml_base : the in-scope XML base URI (or NULL)
Returns : a new raptor_xml_element or NULL on failure

raptor_free_xml_element ()

void        raptor_free_xml_element         (raptor_xml_element *element);

Destructor - destroy a raptor_xml_element object.

element : XML Element

raptor_xml_element_get_name ()

raptor_qname* raptor_xml_element_get_name   (raptor_xml_element *xml_element);

Get the XML Name of an XML element

xml_element : XML Element
Returns : The Name.

raptor_xml_element_get_attributes ()

raptor_qname** raptor_xml_element_get_attributes
                                            (raptor_xml_element *xml_element);

Get the array of attributes on the XML element.

Use raptor_xml_element_get_attributes_count() to get the count of the array size.

xml_element : XML Element
Returns : the array of qnames or NULL if none are present.

raptor_xml_element_get_attributes_count ()

int         raptor_xml_element_get_attributes_count
                                            (raptor_xml_element *xml_element);

Get the number of attributes on the XML element.

xml_element : XML Element
Returns : Integer number of attributes - 0 or more.

raptor_xml_element_set_attributes ()

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

Set the attributes on an XML element.

xml_element : XML Element
attributes : Array of XML Qname attributes with values
count : Length of array

raptor_xml_element_declare_namespace ()

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

Declare a namespace on the XML Element.

xml_element : XML Element
nspace : raptor_namespace to declare
Returns : non-0 if namespace cannot be declared

raptor_xml_element_is_empty ()

int         raptor_xml_element_is_empty     (raptor_xml_element *xml_element);

Check if an XML Element is empty.

xml_element : XML Element
Returns : non-0 if the element is empty.

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);

Constructor - Create a new XML Writer writing XML to a raptor_iostream

nstack : Namespace stack for the writer to start with (or NULL)
uri_handler : URI handler function
uri_context : URI handler context data
iostr : I/O stream to write to
error_handler : error handler function
error_data : error handler data
canonicalize : unused
Returns : a new raptor_xml_writer object or NULL on failure

raptor_free_xml_writer ()

void        raptor_free_xml_writer          (raptor_xml_writer *xml_writer);

Destructor - Free XML Writer

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);

Set xml_writer features with integer values.

The allowed features are available via raptor_features_enumerate().

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

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

raptor_xml_writer* raptor_xml_writer;

Raptor XML Writer class


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);

Return an XML-escaped version a string.

Follows Canonical XML rules on Text Nodes and Attribute Nodes http://www.w3.org/TR/xml-c14nProcessingModel

Both: Replaces & and < with &amp; and &lt; respectively, preserving other characters.

Text Nodes: > is turned into &gt; #xD is turned into &#xD;

Attribute Nodes: > is generated not &gt. #x9, #xA and #xD are turned into &#x9;, &#xA; and &#xD; entities.

If quote is given it can be either of '\'' or '\"' which will be turned into &apos; or &quot; respectively. ASCII NUL ('\0') or any other character will not be escaped.

If buffer is NULL, no work is done but the size of buffer required is returned. The output in buffer remains in UTF-8.

If the input string is empty, a single NUL will be written to the buffer.

string : string to XML 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
xml_version : XML 1.0 (10) or XML 1.1 (11)
error_handler : error handler function
error_data : error handler user data
Returns : the number of bytes required / used or <0 on failure.

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