XML

XML — XML and XML Writer

Synopsis

typedef             raptor_xml_element;
raptor_xml_element * raptor_new_xml_element             (raptor_qname *name,
                                                         const unsigned char *xml_language,
                                                         raptor_uri *xml_base);
raptor_xml_element * raptor_new_xml_element_from_namespace_local_name
                                                        (raptor_namespace *ns,
                                                         const unsigned char *name,
                                                         const 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);
const unsigned char * raptor_xml_element_get_language   (raptor_xml_element *xml_element);
int                 raptor_xml_element_write            (raptor_xml_element *element,
                                                         raptor_namespace_stack *nstack,
                                                         int is_empty,
                                                         int is_end,
                                                         int depth,
                                                         raptor_iostream *iostr);
raptor_xml_writer * raptor_new_xml_writer               (raptor_world *world,
                                                         raptor_namespace_stack *nstack,
                                                         raptor_iostream *iostr);
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,
                                                         const unsigned char *s);
void                raptor_xml_writer_cdata_counted     (raptor_xml_writer *xml_writer,
                                                         const unsigned char *s,
                                                         unsigned int len);
void                raptor_xml_writer_raw               (raptor_xml_writer *xml_writer,
                                                         const unsigned char *s);
void                raptor_xml_writer_raw_counted       (raptor_xml_writer *xml_writer,
                                                         const unsigned char *s,
                                                         unsigned int len);
void                raptor_xml_writer_comment           (raptor_xml_writer *xml_writer,
                                                         const unsigned char *s);
void                raptor_xml_writer_comment_counted   (raptor_xml_writer *xml_writer,
                                                         const unsigned char *s,
                                                         unsigned int len);
void                raptor_xml_writer_flush             (raptor_xml_writer *xml_writer);
void                raptor_xml_writer_newline           (raptor_xml_writer *xml_writer);
int                 raptor_xml_writer_get_depth         (raptor_xml_writer *xml_writer);
int                 raptor_xml_writer_set_option        (raptor_xml_writer *xml_writer,
                                                         raptor_option option,
                                                         char *string,
                                                         int integer);
int                 raptor_xml_writer_get_option        (raptor_xml_writer *xml_writer,
                                                         raptor_option option,
                                                         char **string_p,
                                                         int *integer_p);
typedef             raptor_xml_writer;
int                 raptor_xml_escape_string_any        (raptor_world *world,
                                                         const unsigned char *string,
                                                         size_t len,
                                                         unsigned char *buffer,
                                                         size_t length,
                                                         char quote,
                                                         int xml_version);
int                 raptor_xml_escape_string_any_write  (const unsigned char *string,
                                                         size_t len,
                                                         char quote,
                                                         int xml_version,
                                                         raptor_iostream *iostr);
int                 raptor_xml_escape_string            (raptor_world *world,
                                                         const unsigned char *string,
                                                         size_t len,
                                                         unsigned char *buffer,
                                                         size_t length,
                                                         char quote);
int                 raptor_xml_escape_string_write      (const unsigned char *string,
                                                         size_t len,
                                                         char quote,
                                                         raptor_iostream *iostr);
int                 raptor_xml_name_check               (const 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,
                                                         const unsigned char *xml_language,
                                                         raptor_uri *xml_base);

Constructor - create a new XML element from a QName

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_new_xml_element_from_namespace_local_name ()

raptor_xml_element * raptor_new_xml_element_from_namespace_local_name
                                                        (raptor_namespace *ns,
                                                         const unsigned char *name,
                                                         const unsigned char *xml_language,
                                                         raptor_uri *xml_base);

Constructor - create a new XML element from an XML namespace and a local name

Added in 1.4.16.

ns :

 namespace

name :

 the XML element local name

xml_language :

 the in-scope XML language (or NULL)

xml_base :

 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.

The attributes array becomes owned by the element after this function.

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_xml_element_get_language ()

const unsigned char * raptor_xml_element_get_language   (raptor_xml_element *xml_element);

Get the XML language of the element.

xml_element :

 XML Element

Returns :

 XML language or NULL if none in scope

raptor_xml_element_write ()

int                 raptor_xml_element_write            (raptor_xml_element *element,
                                                         raptor_namespace_stack *nstack,
                                                         int is_empty,
                                                         int is_end,
                                                         int depth,
                                                         raptor_iostream *iostr);

Write a formatted XML element to a raptor_iostream

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)

depth :

 XML element depth

iostr :

 iostream object

Returns :

 non-0 on failure

raptor_new_xml_writer ()

raptor_xml_writer * raptor_new_xml_writer               (raptor_world *world,
                                                         raptor_namespace_stack *nstack,
                                                         raptor_iostream *iostr);

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

world :

 raptor_world object

nstack :

 Namespace stack for the writer to start with (or NULL)

iostr :

 I/O stream to write to

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 option 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 option AUTO_EMPTY is enabled.

Indents the start element if XML writer option 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 option 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,
                                                         const unsigned char *s);

Write CDATA XML-escaped to the XML writer.

Closes any previous empty element if XML writer option 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,
                                                         const unsigned char *s,
                                                         unsigned int len);

Write counted CDATA XML-escaped to the XML writer.

Closes any previous empty element if XML writer option 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,
                                                         const unsigned char *s);

Write a string raw to the XML writer.

Closes any previous empty element if XML writer option 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,
                                                         const unsigned char *s,
                                                         unsigned int len);

Write a counted string raw to the XML writer.

Closes any previous empty element if XML writer option 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,
                                                         const unsigned char *s);

Write an XML comment to the XML writer.

Closes any previous empty element if XML writer option 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,
                                                         const unsigned char *s,
                                                         unsigned int len);

Write a counted XML comment to the XML writer.

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

xml_writer :

 XML writer object

s :

 comment string to write

len :

 length of string

raptor_xml_writer_flush ()

void                raptor_xml_writer_flush             (raptor_xml_writer *xml_writer);

Finish the XML writer.

xml_writer :

 XML writer object

raptor_xml_writer_newline ()

void                raptor_xml_writer_newline           (raptor_xml_writer *xml_writer);

Write a newline to the XML writer.

Indents the next line if XML writer option AUTO_INDENT is enabled.

xml_writer :

 XML writer object

raptor_xml_writer_get_depth ()

int                 raptor_xml_writer_get_depth         (raptor_xml_writer *xml_writer);

Get the current XML Writer element depth

xml_writer :

 raptor_xml_writer xml writer object

Returns :

 element stack depth

raptor_xml_writer_set_option ()

int                 raptor_xml_writer_set_option        (raptor_xml_writer *xml_writer,
                                                         raptor_option option,
                                                         char *string,
                                                         int integer);

Set xml_writer option.

If string is not NULL and the option type is numeric, the string value is converted to an integer and used in preference to integer.

If string is NULL and the option type is not numeric, an error is returned.

The string values used are copied.

The allowed options are available via raptor_world_get_option_description().

xml_writer :

 raptor_xml_writer xml_writer object

option :

 option to set from enumerated raptor_option values

string :

 string option value (or NULL)

integer :

 integer option value

Returns :

 non 0 on failure or if the option is unknown

raptor_xml_writer_get_option ()

int                 raptor_xml_writer_get_option        (raptor_xml_writer *xml_writer,
                                                         raptor_option option,
                                                         char **string_p,
                                                         int *integer_p);

Get xml_writer option.

Any string value returned in *string_p is shared and must be copied by the caller.

The allowed options are available via raptor_world_get_option_description().

xml_writer :

 raptor_xml_writer xml_writer object

option :

 option to get value

string_p :

 pointer to where to store string value

integer_p :

 pointer to where to store integer value

Returns :

 option value or < 0 for an illegal option

raptor_xml_writer

raptor_xml_writer* raptor_xml_writer;

Raptor XML Writer class

raptor_xml_escape_string_any ()

int                 raptor_xml_escape_string_any        (raptor_world *world,
                                                         const unsigned char *string,
                                                         size_t len,
                                                         unsigned char *buffer,
                                                         size_t length,
                                                         char quote,
                                                         int xml_version);

Return an XML-escaped version a string.

Follows Canonical XML rules on Text Nodes and Attribute Nodes

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.

world :

 raptor world

string :

 string to XML escape (UTF-8)

len :

 length of string

buffer :

 the buffer to use for new string (UTF-8) or NULL to just calculate expected length

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)

Returns :

 the number of bytes required / used or <0 on failure.

raptor_xml_escape_string_any_write ()

int                 raptor_xml_escape_string_any_write  (const unsigned char *string,
                                                         size_t len,
                                                         char quote,
                                                         int xml_version,
                                                         raptor_iostream *iostr);

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.

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)

iostr :

 the raptor_iostream to write to

Returns :

 non 0 on failure

raptor_xml_escape_string ()

int                 raptor_xml_escape_string            (raptor_world *world,
                                                         const unsigned char *string,
                                                         size_t len,
                                                         unsigned char *buffer,
                                                         size_t length,
                                                         char quote);

Return an XML 1.0-escaped version a string.

See raptor_xml_escape_string_any() for the conditions on parameters.

world :

 raptor world

string :

 string to XML 1.0 escape (UTF-8)

len :

 length of string

buffer :

 the buffer to use for new string (UTF-8) or NULL to just calculate expected length.

length :

 buffer size

quote :

 optional quote character to escape for attribute content, or 0

Returns :

 the number of bytes required / used or <0 on failure.

raptor_xml_escape_string_write ()

int                 raptor_xml_escape_string_write      (const unsigned char *string,
                                                         size_t len,
                                                         char quote,
                                                         raptor_iostream *iostr);

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

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

string :

 string to XML 1.0 escape (UTF-8)

len :

 length of string

quote :

 optional quote character to escape for attribute content, or 0

iostr :

 the raptor_iostream to write to

Returns :

 non 0 on failure

raptor_xml_name_check ()

int                 raptor_xml_name_check               (const 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
Generated by GTK-Doc V1.18