## e-xml-utils

e-xml-utils

## Functions

void | e_xml_initialize_in_main ()
xmlDoc * | e_xml_parse_file ()
gint | e_xml_save_file ()
xmlNode * | e_xml_get_child_by_name ()
xmlDoc * | e_xml_parse_data ()
xmlXPathContext * | e_xml_new_xpath_context_with_namespaces ()
void | e_xml_xpath_context_register_namespaces ()
xmlXPathObject * | e_xml_xpath_eval ()
gchar * | e_xml_xpath_eval_as_string ()
gboolean | e_xml_xpath_eval_exists ()
gboolean | e_xml_is_element_name ()
xmlNode * | e_xml_find_sibling ()
xmlNode * | e_xml_find_next_sibling ()
xmlNode * | e_xml_find_child ()
xmlChar * | e_xml_dup_node_content ()
xmlChar * | e_xml_find_child_and_dup_content ()
const xmlChar * | e_xml_get_node_text ()
const xmlChar * | e_xml_find_child_and_get_text ()
void | e_xml_find_children_nodes ()
xmlNode * | e_xml_find_in_hierarchy ()

## Description

## Functions

### e_xml_initialize_in_main ()

    void
    e_xml_initialize_in_main (void);

Initializes libxml library global memory. This should be called in the main thread. The function does nothing, when it had been called already.

[skip]

Since: 3.28

### e_xml_parse_file ()

    xmlDoc *
    e_xml_parse_file (const gchar *filename);

Reads a local XML file and parses the contents into an XML document structure. If the XML file cannot be read or its contents are malformed, the function returns `NULL`.

[skip]

#### Parameters

filename | path to an XML file |

#### Returns

an XML document structure, or `NULL`.

[transfer full][nullable]

### e_xml_save_file ()

    gint
    e_xml_save_file (const gchar *filename,
                     xmlDoc *doc);

Writes the given XML document structure to the file given by `filename` . If an error occurs while saving, the function returns -1 and sets errno.

#### Parameters

filename | path to a file to save to |
doc | an XML document structure |

#### Returns

0 on success, -1 on failure

### e_xml_get_child_by_name ()

    xmlNode *
    e_xml_get_child_by_name (const xmlNode *parent,
                             const xmlChar *child_name);

Attempts to find a child element of `parent` named `child_name` . If no such child exists, the function returns `NULL`.

[skip]

#### Parameters

parent | an XML node structure |
child_name | element name of a child node |

#### Returns

a child XML node structure, or `NULL`.

[nullable]

### e_xml_parse_data ()

    xmlDoc *
    e_xml_parse_data (gconstpointer data,
                      gsize length);

Parses XML data into an xmlDocPtr. Free returned pointer with `xmlFreeDoc()`, when no longer needed.

[skip]

#### Parameters

data | an XML data. | [array length=length][element-type guint8]
length | length of data, should be greated than zero |

#### Returns

a new xmlDocPtr with parsed `data` , or `NULL` on error.

[nullable][transfer full]

Since: 3.26

### e_xml_new_xpath_context_with_namespaces ()

    xmlXPathContext *
    e_xml_new_xpath_context_with_namespaces
                                   (xmlDoc *doc,
                                    ...);

Creates a new xmlXPathContextPtr on `doc` with preregistered namespaces. The namepsaces are pair of (prefix, href), terminated by `NULL`.

[skip]

#### Parameters

doc | an xmlDocPtr |
... | `NULL`-terminated list of pairs (prefix, href) with namespaces |

#### Returns

a new xmlXPathContextPtr. Free the returned pointer with `xmlXPathFreeContext()` when no longer needed.

[transfer full]

Since: 3.26

### e_xml_xpath_context_register_namespaces ()

    void
    e_xml_xpath_context_register_namespaces
                                   (xmlXPathContext *xpath_ctx,
                                    const gchar *prefix,
                                    const gchar *href,
                                    ...);

Registers one or more additional namespaces. It's a caller's error to try to register a namespace with the same prefix again, unless the prefix uses the same namespace href.

[skip]

#### Parameters

xpath_ctx | an xmlXPathContextPtr |
prefix | namespace prefix |
href | namespace href |
... | `NULL`-terminated list of pairs (prefix, href) with additional namespaces |

Since: 3.26

### e_xml_xpath_eval ()

    xmlXPathObject *
    e_xml_xpath_eval (xmlXPathContext *xpath_ctx,
                      const gchar *format,
                      ...);

Evaluates path specified by `format` and returns its xmlXPathObjectPtr, in case the path evaluates to a non-empty node set. See also `e_xml_xpath_eval_as_string()` which evaluates the path to string.

[skip]

#### Parameters

xpath_ctx | an xmlXPathContextPtr |
format | printf-like format specifier of path to evaluate |
... | arguments for the `format` |

#### Returns

a new xmlXPathObjectPtr which references given path, or `NULL` if path cannot be found or when it evaluates to an empty nodeset. Free returned pointer with `xmlXPathFreeObject()`, when no longer needed.

[nullable][transfer full]

Since: 3.26

### e_xml_xpath_eval_as_string ()

    gchar *
    e_xml_xpath_eval_as_string (xmlXPathContext *xpath_ctx,
                                const gchar *format,
                                ...);

Evaluates path specified by `format` and returns its result as string, in case the path evaluates to a non-empty node set. See also `e_xml_xpath_eval()` which evaluates the path to an xmlXPathObjectPtr.

[skip]

#### Parameters

xpath_ctx | an xmlXPathContextPtr |
format | printf-like format specifier of path to evaluate |
... | arguments for the `format` |

#### Returns

a new string which contains value of the given path, or `NULL` if path cannot be found or when it evaluates to an empty nodeset. Free returned pointer with `g_free()`, when no longer needed.

[nullable][transfer full]

Since: 3.26

### e_xml_xpath_eval_exists ()

    gboolean
    e_xml_xpath_eval_exists (xmlXPathContext *xpath_ctx,
                             const gchar *format,
                             ...);

Evaluates path specified by `format` and returns whether it exists.

[skip]

#### Parameters

xpath_ctx | an xmlXPathContextPtr |
format | printf-like format specifier of path to evaluate |
... | arguments for the `format` |

#### Returns

`TRUE`, when the given XPath exists, `FALSE` otherwise.

Since: 3.26

### e_xml_is_element_name ()

    gboolean
    e_xml_is_element_name (xmlNode *node,
                           const gchar *ns_href,
                           const gchar *name);

[skip]

#### Parameters

node | an xmlNode. | [nullable]
ns_href | a namespace href the node should have set, or `NULL` for none namespace. | [nullable]
name | an element name to search for |

#### Returns

Whether the `node` is an element node of name `name` and with a namespace href set to `ns_href`

Since: 3.38

### e_xml_find_sibling ()

    xmlNode *
    e_xml_find_sibling (xmlNode *sibling,
                        const gchar *ns_href,
                        const gchar *name);

Searches the sibling nodes of the `sibling` for an element named `name` in namespace `ns_href` . It checks the `sibling` itself too, but it doesn't check the previous siblings of the `sibling` .

[skip]

#### Parameters

sibling | an xmlNode, where to start searching. | [nullable]
ns_href | a namespace href the node should have set, or `NULL` for none namespace. | [nullable]
name | an element name to search for |

#### Returns

an xmlNode of the given name, or `NULL`, if not found It also returns `NULL`, when the `sibling` is `NULL`.

See: `e_xml_find_next_sibling()`, `e_xml_find_child()`.

[transfer none][nullable]

Since: 3.38

### e_xml_find_next_sibling ()

    xmlNode *
    e_xml_find_next_sibling (xmlNode *sibling,
                             const gchar *ns_href,
                             const gchar *name);

Searches for the next sibling node of the `sibling` for an element named `name` in namespace `ns_href` . Unlike `e_xml_find_sibling()`, it skips the `sibling` itself.

[skip]

#### Parameters

sibling | an xmlNode, where to search from. | [nullable]
ns_href | a namespace href the node should have set, or `NULL` for none namespace. | [nullable]
name | an element name to search for |

#### Returns

an xmlNode of the given name, or `NULL`, if not found It also returns `NULL`, when the `sibling` is `NULL`.

See: `e_xml_find_sibling()`, `e_xml_find_child()`.

[transfer none][nullable]

Since: 3.38

### e_xml_find_child ()

    xmlNode *
    e_xml_find_child (xmlNode *parent,
                      const gchar *ns_href,
                      const gchar *name);

Searches the children nodes of the `parent` for an element named `name` in namespace `ns_href` .

[skip]

#### Parameters

parent | an xmlNode, parent of which immediate children to search. | [nullable]
ns_href | a namespace href the node should have set, or `NULL` for none namespace. | [nullable]
name | an element name to search for |

#### Returns

an xmlNode of the given name, or `NULL`, if not found. It also returns `NULL`, when the `parent` is `NULL`.

See: `e_xml_find_sibling()`, `e_xml_find_children_nodes()`.

[transfer none][nullable]

Since: 3.38

### e_xml_dup_node_content ()

    xmlChar *
    e_xml_dup_node_content (const xmlNode *node);

Duplicates content of the `node` . If the `node` is `NULL`, then the function does nothing and returns also `NULL`.

Unlike `e_xml_get_node_text()`, this includes also any element sub-structure of the `node` , if any such exists.

[skip]

#### Parameters

node | an xmlNode. | [nullable]

#### Returns

the `node` content as xmlChar string, or `NULL`, when the content could not be read or was not set. Free the non-`NULL` value with `xmlFree()`, when no longer needed.

See: `e_xml_find_child_and_dup_content()`, `e_xml_get_node_text()`.

[transfer full][nullable]

Since: 3.38

### e_xml_find_child_and_dup_content ()

    xmlChar *
    e_xml_find_child_and_dup_content (xmlNode *parent,
                                      const gchar *ns_href,
                                      const gchar *name);

Searches the children nodes of the `parent` for an element named `name` in namespace `ns_href` and returns its content. This combines `e_xml_find_child()` and `e_xml_dup_node_content()` calls.

[skip]

#### Parameters

parent | an xmlNode, parent of which immediate children to search. | [nullable]
ns_href | a namespace href the node should have set, or `NULL` for none namespace. | [nullable]
name | an element name to search for |

#### Returns

the found node content as xmlChar string, or `NULL`, when the node could not be found or the content could not be read or was not set. Free the non-`NULL` value with `xmlFree()`, when no longer needed.

See: `e_xml_find_child_and_get_text()`.

[transfer full][nullable]

Since: 3.38

### e_xml_get_node_text ()

    const xmlChar *
    e_xml_get_node_text (const xmlNode *node);

Retrieves content of the `node` . If the `node` is `NULL`, then the function does nothing and returns also `NULL`.

This is similar to `e_xml_dup_node_content()`, except it does not allocate new memory for the string. It also doesn't traverse the element structure, is returns the first text node's value only. It can be used to avoid unnecessary allocations, when reading element values with a single text node as a child.

[skip]

#### Parameters

node | an xmlNode. | [nullable]

#### Returns

The `node` content, or `NULL`.

See: `e_xml_dup_node_content()`.

[transfer none][nullable]

Since: 3.38

### e_xml_find_child_and_get_text ()

    const xmlChar *
    e_xml_find_child_and_get_text (xmlNode *parent,
                                   const gchar *ns_href,
                                   const gchar *name);

Searches the children nodes of the `parent` for an element named `name` in namespace `ns_href` and returns its text content.

It combines `e_xml_find_child()` and `e_xml_get_node_text()` calls.

[skip]

#### Parameters

parent | an xmlNode, parent of which immediate children to search. | [nullable]
ns_href | a namespace href the node should have set, or `NULL` for none namespace. | [nullable]
name | an element name to search for |

#### Returns

the found node text as xmlChar string, or `NULL`, when the node could not be found or the content could not be read or was not set.

See: `e_xml_find_child_and_dup_content()`, `e_xml_find_children_nodes()`.

[transfer none][nullable]

Since: 3.38

### e_xml_find_children_nodes ()

    void
    e_xml_find_children_nodes (xmlNode *parent,
                               guint count,
                               ...);

Retrieve multiple nodes in one go, in an efficient way. It can be quicker than traversing the children of the `parent` `count` times in certain circumstances.

The variable parameters expect triple of: const gchar *ns_href; const gchar *name; xmlNode **out_node; where the ns_href is a namespace href the node should have set, or `NULL` for none namespace; the name is an element name to search for. The names should not be included more than once.

[skip]

#### Parameters

parent | an xmlNode, whose children to search |
count | how many nodes will be read |
... | triple of arguments describing the nodes and their out variable |

Since: 3.38

### e_xml_find_in_hierarchy ()

    xmlNode *
    e_xml_find_in_hierarchy (xmlNode *parent,
                             const gchar *child_ns_href,
                             const gchar *child_name,
                             ...);

Checks whether the `parent` has a hierarchy of children described by pair of 'ns_href' and 'name'.

Note: It requires two `NULL`-s at the end of the arguments, because the `ns_href' can be `NULL`, thus it could not distinguish between no namespace href and the end of the hierarchy children, thus it stops only on the 'name' being `NULL`.

[skip]

#### Parameters

parent | an xmlNode, or `NULL`, in which case function does nothing and just returns `NULL`. | [nullable]
child_ns_href | a namespace href the node should have set, or `NULL` for none namespace. | [nullable]
child_name | an element name to search for |
... | a two-`NULL`-terminated pair of hierarchy children |

#### Returns

an xmlNode referencing the node in the hierarchy of the children of the `parent` , or `NULL`, when no such found.

[transfer none][nullable]

Since: 3.38