e-xml-utils

e-xml-utils

Functions

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