## XML utility functions

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

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | inf_xml_util_add_child_text ()
gchar * | inf_xml_util_get_child_text ()
xmlChar * | inf_xml_util_get_attribute ()
xmlChar * | inf_xml_util_get_attribute_required ()
gboolean | inf_xml_util_get_attribute_int ()
gboolean | inf_xml_util_get_attribute_int_required ()
gboolean | inf_xml_util_get_attribute_long ()
gboolean | inf_xml_util_get_attribute_long_required ()
gboolean | inf_xml_util_get_attribute_uint ()
gboolean | inf_xml_util_get_attribute_uint_required ()
gboolean | inf_xml_util_get_attribute_ulong ()
gboolean | inf_xml_util_get_attribute_ulong_required ()
gboolean | inf_xml_util_get_attribute_double ()
gboolean | inf_xml_util_get_attribute_double_required ()
void | inf_xml_util_set_attribute ()
void | inf_xml_util_set_attribute_int ()
void | inf_xml_util_set_attribute_long ()
void | inf_xml_util_set_attribute_uint ()
void | inf_xml_util_set_attribute_ulong ()
void | inf_xml_util_set_attribute_double ()
GError * | inf_xml_util_new_error_from_node ()
xmlNodePtr | inf_xml_util_new_node_from_error ()

## 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]