XML utility functions

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

Stability Level

Unstable, unless otherwise indicated

Synopsis

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

void                inf_xml_util_add_child_text         (xmlNodePtr xml,
                                                         const gchar *text,
                                                         gsize bytes);
gchar *             inf_xml_util_get_child_text         (xmlNodePtr xml,
                                                         gsize *bytes,
                                                         guint *chars,
                                                         GError **error);
xmlChar *           inf_xml_util_get_attribute          (xmlNodePtr xml,
                                                         const gchar *attribute);
xmlChar *           inf_xml_util_get_attribute_required (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         GError **error);
gboolean            inf_xml_util_get_attribute_int      (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         gint *result,
                                                         GError **error);
gboolean            inf_xml_util_get_attribute_int_required
                                                        (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         gint *result,
                                                         GError **error);
gboolean            inf_xml_util_get_attribute_long     (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         glong *result,
                                                         GError **error);
gboolean            inf_xml_util_get_attribute_long_required
                                                        (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         glong *result,
                                                         GError **error);
gboolean            inf_xml_util_get_attribute_uint     (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         guint *result,
                                                         GError **error);
gboolean            inf_xml_util_get_attribute_uint_required
                                                        (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         guint *result,
                                                         GError **error);
gboolean            inf_xml_util_get_attribute_ulong    (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         gulong *result,
                                                         GError **error);
gboolean            inf_xml_util_get_attribute_ulong_required
                                                        (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         gulong *result,
                                                         GError **error);
gboolean            inf_xml_util_get_attribute_double   (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         gdouble *result,
                                                         GError **error);
gboolean            inf_xml_util_get_attribute_double_required
                                                        (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         gdouble *result,
                                                         GError **error);
void                inf_xml_util_set_attribute          (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         const gchar *value);
void                inf_xml_util_set_attribute_int      (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         gint value);
void                inf_xml_util_set_attribute_long     (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         glong value);
void                inf_xml_util_set_attribute_uint     (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         guint value);
void                inf_xml_util_set_attribute_ulong    (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         gulong value);
void                inf_xml_util_set_attribute_double   (xmlNodePtr xml,
                                                         const gchar *attribute,
                                                         gdouble value);
GError *            inf_xml_util_new_error_from_node    (xmlNodePtr xml);
xmlNodePtr          inf_xml_util_new_node_from_error    (GError *error,
                                                         xmlNsPtr name_space,
                                                         const gchar *name);

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.

Details

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.

xml :

A xmlNodePtr.

text :

The child text to add.

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.

xml :

A xmlNodePtr

bytes :

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

chars :

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

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.

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.

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.

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.

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.

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 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, 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.

xml :

A xmlNodePtr.

attribute :

The name of the attribute to query.

result :

Location to store the read value.

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.

xml :

A xmlNodePtr.

attribute :

The name of the attribute to query.

result :

Location to store the read value.

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.

xml :

A xmlNodePtr.

attribute :

The name of the attribute to query.

result :

Location to store the read value.

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.

xml :

A xmlNodePtr.

attribute :

The name of the attribute to query.

result :

Location to store the read value.

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.

xml :

A xmlNodePtr.

attribute :

The name of the attribute to query.

result :

Location to store the read value.

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.

xml :

A xmlNodePtr.

attribute :

The name of the attribute to query.

result :

Location to store the read value.

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.

xml :

A xmlNodePtr.

attribute :

The name of the attribute to query.

result :

Location to store the read value.

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.

xml :

A xmlNodePtr.

attribute :

The name of the attribute to query.

result :

Location to store the read value.

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.

xml :

A xmlNodePtr.

attribute :

The name of the attribute to query.

result :

Location to store the read value.

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.

xml :

A xmlNodePtr.

attribute :

The name of the attribute to query.

result :

Location to store the read value.

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*.

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.

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.

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.

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.

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.

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.

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

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.

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