XML utility functions

XML utility functions — Helper functions to read basic data types from XML

Stability Level

Unstable, unless otherwise indicated

Functions

Includes

#include <libinfinity/common/inf-xml-util.h>

Description

In the infinote protocol XML attributes are often required to contain numbers. These function provide some convenience to set and retrieve them. They are mostly used in libinfinity itself but can also be useful when implementing new session types so they are public API.

Functions

inf_xml_util_add_child_text ()

void
inf_xml_util_add_child_text (xmlNodePtr xml,
                             const gchar *text,
                             gsize bytes);

Adds the given text as child text to xml in the same way xmlNodeAddContentLen() would do. The difference is that text is allowed to contain characters that are not valid in

XML text, such

as formfeed characters \f. In case one occurs in text , the function adds an <uchar /> element node instead to xml as specified in the infinote protocol.

Parameters

xml

A xmlNodePtr.

 

text

The child text to add.

[array length=bytes]

bytes

The number of bytes of text .

 

inf_xml_util_get_child_text ()

gchar *
inf_xml_util_get_child_text (xmlNodePtr xml,
                             gsize *bytes,
                             guint *chars,
                             GError **error);

Reads a node's child text. If there are <uchar /> child elements, as added by inf_xml_util_add_child_text() this function will convert them back to character codes. There should not be any other child elements in xml .

Parameters

xml

A xmlNodePtr

 

bytes

Location to store number of bytes of child text, or NULL.

[out][allow-none]

chars

Location to store number of characters of child text, or NULL.

[out][allow-none]

error

Locatian to store error information, if any, or NULL.

 

Returns

The node's child text, or NULL on error. Free with g_free() when no longer needed.

[array length=bytes][transfer full]


inf_xml_util_get_attribute ()

xmlChar *
inf_xml_util_get_attribute (xmlNodePtr xml,
                            const gchar *attribute);

Returns the value of the attribute called attribute in the XML element xml . This function is a thin wrapper around xmlGetProp() which exists mostly for consistency, and for not having to cast the attribute argument from char* to xmlChar*. The return value is a xmlChar*, though.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to query.

 

Returns

The value of the attribute, or NULL. Free with xmlFree() when no longer needed.

[transfer full]


inf_xml_util_get_attribute_required ()

xmlChar *
inf_xml_util_get_attribute_required (xmlNodePtr xml,
                                     const gchar *attribute,
                                     GError **error);

Returns the value of the attribute called attribute in the XML element xml . If there is no such attribute then the function returns NULL and error is set.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to query.

 

error

Location to store error information, if any.

 

Returns

The attribute's value, or NULL on error. Free with xmlFree() when no longer needed.

[transfer full]


inf_xml_util_get_attribute_int ()

gboolean
inf_xml_util_get_attribute_int (xmlNodePtr xml,
                                const gchar *attribute,
                                gint *result,
                                GError **error);

Reads the attribute named attribute from the XML element xml . The attribute value is expected to be a signed integral number. If it is the function converts the text to an integer and stores the result into result . In this case, TRUE is returned and error is left untouched.

If the value is not a signed integral number, then the function returns FALSE, error is set and result is left untouched.

If the attribute does not exist the function returns FALSE but error is not set.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to query.

 

result

Location to store the read value.

[out]

error

Location to store error information, if any.

 

Returns

Whether result was set.


inf_xml_util_get_attribute_int_required ()

gboolean
inf_xml_util_get_attribute_int_required
                               (xmlNodePtr xml,
                                const gchar *attribute,
                                gint *result,
                                GError **error);

Reads the attribute named attribute from the XML element xml . The attribute value is expected to be a signed integral number. If it is the function converts the text to an integere and stores the result into result . In this case, TRUE is returned and error is left untouched.

If the value is not a signed integral number or the attribute does not exist, then the function returns FALSE, error is set and result is left untouched.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to query.

 

result

Location to store the read value.

[out]

error

Location to store error information, if any.

 

Returns

Whether result was set.


inf_xml_util_get_attribute_long ()

gboolean
inf_xml_util_get_attribute_long (xmlNodePtr xml,
                                 const gchar *attribute,
                                 glong *result,
                                 GError **error);

Behaves exactly like inf_xml_util_get_attribute_int(). The only difference is that the function reads a signed long integral number.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to query.

 

result

Location to store the read value.

[out]

error

Location to store error information, if any.

 

Returns

Whether result was set.


inf_xml_util_get_attribute_long_required ()

gboolean
inf_xml_util_get_attribute_long_required
                               (xmlNodePtr xml,
                                const gchar *attribute,
                                glong *result,
                                GError **error);

Behaves exactly like inf_xml_util_get_attribute_int_required(). The only difference is that the function reads a signed long integral number.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to query.

 

result

Location to store the read value.

[out]

error

Location to store error information, if any.

 

Returns

Whether result was set.


inf_xml_util_get_attribute_uint ()

gboolean
inf_xml_util_get_attribute_uint (xmlNodePtr xml,
                                 const gchar *attribute,
                                 guint *result,
                                 GError **error);

Behaves exactly like inf_xml_util_get_attribute_int(). The only difference is that the function reads an unsigned integral number.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to query.

 

result

Location to store the read value.

[out]

error

Location to store error information, if any.

 

Returns

Whether result was set.


inf_xml_util_get_attribute_uint_required ()

gboolean
inf_xml_util_get_attribute_uint_required
                               (xmlNodePtr xml,
                                const gchar *attribute,
                                guint *result,
                                GError **error);

Behaves exactly like inf_xml_util_get_attribute_int_required(). The only difference is that the function reads an unsigned integral number.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to query.

 

result

Location to store the read value.

[out]

error

Location to store error information, if any.

 

Returns

Whether result was set.


inf_xml_util_get_attribute_ulong ()

gboolean
inf_xml_util_get_attribute_ulong (xmlNodePtr xml,
                                  const gchar *attribute,
                                  gulong *result,
                                  GError **error);

Behaves exactly like inf_xml_util_get_attribute_int(). The only difference is that the function reads an unsigned long integral number.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to query.

 

result

Location to store the read value.

[out]

error

Location to store error information, if any.

 

Returns

Whether result was set.


inf_xml_util_get_attribute_ulong_required ()

gboolean
inf_xml_util_get_attribute_ulong_required
                               (xmlNodePtr xml,
                                const gchar *attribute,
                                gulong *result,
                                GError **error);

Behaves exactly like inf_xml_util_get_attribute_int_required(). The only difference is that the function reads an unsigned long integral number.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to query.

 

result

Location to store the read value.

[out]

error

Location to store error information, if any.

 

Returns

Whether result was set.


inf_xml_util_get_attribute_double ()

gboolean
inf_xml_util_get_attribute_double (xmlNodePtr xml,
                                   const gchar *attribute,
                                   gdouble *result,
                                   GError **error);

Behaves exactly like inf_xml_util_get_attribute_int(). The only difference is that the function reads a double-precision floating point number.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to query.

 

result

Location to store the read value.

[out]

error

Location to store error information, if any.

 

Returns

Whether result was set.


inf_xml_util_get_attribute_double_required ()

gboolean
inf_xml_util_get_attribute_double_required
                               (xmlNodePtr xml,
                                const gchar *attribute,
                                gdouble *result,
                                GError **error);

Behaves exactly like inf_xml_util_get_attribute_int_required(). The only difference is that the function reads a double-precision floating point number.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to query.

 

result

Location to store the read value.

[out]

error

Location to store error information, if any.

 

Returns

Whether result was set.


inf_xml_util_set_attribute ()

void
inf_xml_util_set_attribute (xmlNodePtr xml,
                            const gchar *attribute,
                            const gchar *value);

Sets the attribute named attribute to the given value of the XML element xml . This is a thin wrapper around xmlSetProp(), mainly provided for consistency and for not having to cast the arguments to xmlChar*.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to set.

 

value

The value to set.

 

inf_xml_util_set_attribute_int ()

void
inf_xml_util_set_attribute_int (xmlNodePtr xml,
                                const gchar *attribute,
                                gint value);

Sets the attribute named attribute to the given signed integral value converted to text.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to set.

 

value

The value to set.

 

inf_xml_util_set_attribute_long ()

void
inf_xml_util_set_attribute_long (xmlNodePtr xml,
                                 const gchar *attribute,
                                 glong value);

Sets the attribute named attribute to the given signed long integral value converted to text.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to set.

 

value

The value to set.

 

inf_xml_util_set_attribute_uint ()

void
inf_xml_util_set_attribute_uint (xmlNodePtr xml,
                                 const gchar *attribute,
                                 guint value);

Sets the attribute named attribute to the given unsigned integral value converted to text.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to set.

 

value

The value to set.

 

inf_xml_util_set_attribute_ulong ()

void
inf_xml_util_set_attribute_ulong (xmlNodePtr xml,
                                  const gchar *attribute,
                                  gulong value);

Sets the attribute named attribute to the given unsigned long integral value converted to text.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to set.

 

value

The value to set.

 

inf_xml_util_set_attribute_double ()

void
inf_xml_util_set_attribute_double (xmlNodePtr xml,
                                   const gchar *attribute,
                                   gdouble value);

Sets the attribute named attribute to the given double-precision floating point number converted to text.

Parameters

xml

A xmlNodePtr.

 

attribute

The name of the attribute to set.

 

value

The value to set.

 

inf_xml_util_new_error_from_node ()

GError *
inf_xml_util_new_error_from_node (xmlNodePtr xml);

Creates a new GError with the domain and erro code given in xml 's attributes. The message is parsed from the child text as with inf_xml_util_get_child_text(). The element name and namespace are ignored. If xml does not have the attributes as expected, NULL is returned.

Parameters

xml

A xmlNodePtr as returned by inf_xml_util_new_node_from_error().

 

Returns

A pointer to a new GError, or NULL on failure. It is the caller's responsibility to dispose the GError object using g_error_free().

[transfer full]


inf_xml_util_new_node_from_error ()

xmlNodePtr
inf_xml_util_new_node_from_error (GError *error,
                                  xmlNsPtr name_space,
                                  const gchar *name);

Creates a new xmlNode that encodes error . The element's name is optionally specified by name , or "error" by default, error 's domain and code are set as attributes and its message is set as child text using inf_xml_util_add_child_text(). name_space is set as the element's namespace, if not NULL.

Parameters

error

The error object to represent in xml.

 

name_space

The element's namespace, or NULL.

 

name

An element name, or NULL.

 

Returns

A new xmlNodePtr. It is the caller's responsibility to dispose it using xmlFreeNode().

[transfer full]