 |
 |
 |
Raptor RDF Syntax Parsing and Serializing Library Manual |  |
|---|---|---|---|---|
| Top | Description | ||||
Synopsis
typedef raptor_xml_element; raptor_xml_element* raptor_new_xml_element (raptor_qname *name, unsigned char *xml_language, raptor_uri *xml_base); raptor_xml_element* raptor_new_xml_element_from_namespace_local_name (raptor_namespace *ns, unsigned char *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); const unsigned char* raptor_xml_element_get_language (raptor_xml_element *xml_element); raptor_xml_writer* raptor_new_xml_writer (raptor_namespace_stack *nstack, const 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); void raptor_xml_writer_flush (raptor_xml_writer *xml_writer); void raptor_xml_writer_newline (raptor_xml_writer *xml_writer); int raptor_xml_writer_features_enumerate (const raptor_feature feature, const char **name, raptor_uri **uri, const char **label); int raptor_xml_writer_get_depth (raptor_xml_writer *xml_writer); 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_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 from a QName
|
The XML element name |
|
the in-scope XML language (or NULL) |
|
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, unsigned char *name, 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.
|
namespace |
|
the XML element local name |
|
the in-scope XML language (or NULL) |
|
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.
|
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 |
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 |
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 |
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 |
|
Array of XML Qname attributes with values |
|
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 |
|
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 |
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 |
Returns : |
XML language or NULL if none in scope |
raptor_new_xml_writer ()
raptor_xml_writer* raptor_new_xml_writer (raptor_namespace_stack *nstack, const 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
uri_handler and uri_context parameters are ignored but are retained
in the API for backwards compatibility. Internally the same uri handler
as returned by raptor_uri_get_handler() will be used.
raptor_init() MUST have been called before calling this function.
Use raptor_new_xml_writer_v2() if using raptor_world APIs.
|
Namespace stack for the writer to start with (or NULL) |
|
URI handler function (ignored) |
|
URI handler context data (ignored) |
|
I/O stream to write to |
|
error handler function |
|
error handler data |
|
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 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 object |
|
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 object |
|
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 object |
|
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 object |
|
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 object |
|
string to XML escape and write |
|
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 object |
|
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 object |
|
string to write |
|
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 object |
|
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 object |
|
comment string to write |
|
length of string |
raptor_xml_writer_flush ()
void raptor_xml_writer_flush (raptor_xml_writer *xml_writer);
Finish the 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 feature AUTO_INDENT is enabled.
|
XML writer object |
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 to a new raptor_uri is returned
that must be freed by the caller with raptor_free_uri().
raptor_init() MUST have been called before calling this function.
Use raptor_xml_writer_features_enumerate_v2() if using raptor_world APIs.
|
feature enumeration (0+) |
|
pointer to store feature short name (or NULL) |
|
pointer to store feature URI (or NULL) |
|
pointer to feature label (or NULL) |
Returns : |
0 on success, <0 on failure, >0 if feature is unknown |
raptor_xml_writer_get_depth ()
int raptor_xml_writer_get_depth (raptor_xml_writer *xml_writer);
Get the current XML Writer element depth
|
raptor_xml_writer xml writer object |
Returns : |
element stack depth |
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().
|
raptor_xml_writer xml_writer object |
|
feature to set from enumerated raptor_feature values |
|
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.
|
raptor_xml_writer xml_writer object |
|
feature to set from enumerated raptor_feature values |
|
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
|
raptor_xml_writer xml writer object |
|
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().
|
raptor_xml_writer xml writer object |
|
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
|
iostream object |
|
XML element to format |
|
Namespace stack context to use in formatting |
|
non-0 if element is empty |
|
non-0 if this is an end element (else is a start element) |
|
error handler function |
|
error handler function data |
|
XML element depth |
Returns : |
non-0 on failure |
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 & and <
respectively, preserving other characters.
Text Nodes:
> is turned into >
#xD is turned into 
Attribute Nodes:
> is generated not >.
#x9, #xA and #xD are turned into
	,

 and

entities.
If quote is given it can be either of '\'' or '\"'
which will be turned into ' or
" 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 to XML escape (UTF-8) |
|
length of string |
|
the buffer to use for new string (UTF-8) |
|
buffer size |
|
optional quote character to escape for attribute content, or 0 |
|
XML 1.0 (10) or XML 1.1 (11) |
|
error handler function |
|
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 to XML 1.0 escape (UTF-8) |
|
length of string |
|
the buffer to use for new string (UTF-8) |
|
buffer size |
|
optional quote character to escape for attribute content, or 0 |
|
error handler function |
|
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.
|
the raptor_iostream to write to |
|
string to XML escape (UTF-8) |
|
length of string |
|
optional quote character to escape for attribute content, or 0 |
|
XML version - 10 (XML 1.0) or 11 (XML 1.1) |
|
error handler function |
|
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.
|
the raptor_iostream to write to |
|
string to XML 1.0 escape (UTF-8) |
|
length of string |
|
optional quote character to escape for attribute content, or 0 |
|
error handler function |
|
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.
|
UTF-8 name string |
|
length of string |
|
XML version |
Returns : |
Non 0 if the string is a legal XML name |