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