IpatchXml

IpatchXml — XML tree functions

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

Description

Functions for manipulating XML node trees and saving/loading to/from XML content in strings or files. XML node trees use the glib GNode N-ary tree data type for added flexibility.

Functions

ipatch_xml_new_node ()

GNode *
ipatch_xml_new_node (GNode *parent,
                     const char *name,
                     const char *value,
                     const char *attr_name,
                     ...);

Create a new XML tree node and append it to the given parent , if supplied. Note that the returned GNode can be used with other N-Array glib operations.

[skip]

Parameters

parent

Parent node to add new node to as a child, or NULL to create new root node.

[nullable]

name

Name of the new XML node

 

value

Text value to assign to the new node or NULL.

[nullable]

attr_name

First attribute name to assign or NULL.

[nullable]

...

If attr_name was supplied first string value to be assigned should be the first parameter, additional name/value attribute string pairs may follow terminated by a NULL name.

[type char*]

Returns

New XML tree node


ipatch_xml_new_node_strv ()

GNode *
ipatch_xml_new_node_strv (GNode *parent,
                          const char *name,
                          const char *value,
                          const char **attr_names,
                          const char **attr_values);

Like ipatch_xml_new_node() but takes attribute name/values as separate strv arrays.

[skip]

Parameters

parent

Parent node to add new node to as a child, or NULL to create new root node.

[nullable]

name

Name of the new XML node

 

value

Text value to assign to the new node or NULL.

[nullable]

attr_names

NULL terminated array of attribute names or NULL.

[array zero-terminated=1][nullable]

attr_values

NULL terminated array of attribute values or NULL.

[array zero-terminated=1][nullable]

Returns

New XML tree node


ipatch_xml_get_data ()

gpointer
ipatch_xml_get_data (GNode *node,
                     const char *key);

Lookup data assigned to an XML node.

[skip]

Parameters

node

XML node

 

key

Name of the key

 

Returns

The data pointer or NULL if not set


ipatch_xml_set_data ()

void
ipatch_xml_set_data (GNode *node,
                     const char *key,
                     gpointer data);

Assigns arbitrary data to an XML node specified by a key .

[skip]

Parameters

node

XML node

 

key

Name of the key

 

data

Data to associate with the key

 

ipatch_xml_set_data_full ()

void
ipatch_xml_set_data_full (GNode *node,
                          const char *key,
                          gpointer data,
                          GDestroyNotify destroy_func);

Assigns arbitrary data to an XML node specified by a key . Also assigns a destroy_func callback to destroy the data when it is removed.

[skip]

Parameters

node

XML node

 

key

Name of the key

 

data

Data to associate with the key

 

destroy_func

Destroy function or NULL.

[nullable]

ipatch_xml_steal_data ()

gpointer
ipatch_xml_steal_data (GNode *node,
                       const char *key);

Remove keyed data from an XML node, but don't call the data's destroy notify. Caller is thus given the ownership of the data.

[skip]

Parameters

node

XML node

 

key

Name of the key

 

Returns

The data pointer or NULL if not set.

[transfer none]


ipatch_xml_get_qdata ()

gpointer
ipatch_xml_get_qdata (GNode *node,
                      GQuark quark);

Lookup data assigned to an XML node using a quark. This is faster than ipatch_xml_get_data() since the key must be converted to a quark anyways.

[skip]

Parameters

node

XML node

 

quark

Quark key

 

Returns

The data pointer or NULL if not set.

[transfer none]


ipatch_xml_set_qdata ()

void
ipatch_xml_set_qdata (GNode *node,
                      GQuark quark,
                      gpointer data);

Assigns arbitrary data to an XML node specified by a quark key. This is faster than ipatch_xml_set_data() since the key must be converted to a quark anyways.

[skip]

Parameters

node

XML node

 

quark

Quark key

 

data

Data to associate with the key

 

ipatch_xml_set_qdata_full ()

void
ipatch_xml_set_qdata_full (GNode *node,
                           GQuark quark,
                           gpointer data,
                           GDestroyNotify destroy_func);

Assigns arbitrary data to an XML node specified by a key . Also assigns a destroy_func callback to destroy the data when it is removed. This is faster than ipatch_xml_set_data_full() since the key must be converted to a quark anyways.

[skip]

Parameters

node

XML node

 

quark

Quark key

 

data

Data to associate with the key

 

destroy_func

Destroy function or NULL.

[nullable]

ipatch_xml_steal_qdata ()

gpointer
ipatch_xml_steal_qdata (GNode *node,
                        GQuark quark);

Remove keyed data from an XML node, but don't call the data's destroy notify. Caller is thus given the ownership of the data. This is faster than ipatch_xml_steal_data() since the key must be converted to a quark anyways.

[skip]

Parameters

node

XML node

 

quark

Quark key

 

Returns

The data pointer or NULL if not set.

[transfer none]


ipatch_xml_destroy ()

void
ipatch_xml_destroy (GNode *node);

Free an XML tree (a root node and all its children). Does not need to be the actual root of a tree, i.e., can remove a sub tree.

[skip]

Parameters

node

Root of XML tree/sub tree to destroy

 

ipatch_xml_copy ()

GNode *
ipatch_xml_copy (GNode *node);

Perform a deep copy on an XML tree.

[skip]

Parameters

node

XML tree to copy

 

Returns

New duplicate XML tree.


ipatch_xml_set_name ()

void
ipatch_xml_set_name (GNode *node,
                     const char *name);

Set the name of an XML node.

[skip]

Parameters

node

XML node

 

name

Name to assign

 

ipatch_xml_set_value ()

void
ipatch_xml_set_value (GNode *node,
                      const char *value);

Set the text value of an XML node.

[skip]

Parameters

node

XML node

 

value

Text value to assign or NULL to clear it

 

ipatch_xml_set_value_printf ()

void
ipatch_xml_set_value_printf (GNode *node,
                             const char *format,
                             ...);

Assign a value to an XML node using a printf format and arguments.

[skip]

Parameters

node

XML node

 

format

Printf format

 

...

Printf arguments

 

ipatch_xml_take_name ()

void
ipatch_xml_take_name (GNode *node,
                      char *name);

Like ipatch_xml_set_name() but takes over the allocation of name rather than duplicating it.

[skip]

Parameters

node

XML node

 

name

Name to assign or NULL to clear it.

[nullable][transfer full]

ipatch_xml_take_value ()

void
ipatch_xml_take_value (GNode *node,
                       char *value);

Like ipatch_xml_set_value() but takes over the allocation of value rather than duplicating it.

[skip]

Parameters

node

XML node

 

value

Text value to assign.

[transfer full]

ipatch_xml_get_name ()

const char *
ipatch_xml_get_name (GNode *node);

Get the name of an XML node.

[skip]

Parameters

node

XML node to get name of

 

Returns

Name of XML node which is internal and should not be modified or freed.


ipatch_xml_test_name ()

gboolean
ipatch_xml_test_name (GNode *node,
                      const char *cmpname);

Test if the node has the given name.

[skip]

Parameters

node

XML node to get name of

 

cmpname

Name to compare to

 

Returns

TRUE if the node has the given name, FALSE otherwise


ipatch_xml_get_value ()

const char *
ipatch_xml_get_value (GNode *node);

Get the text value of an XML node.

[skip]

Parameters

node

XML node to get value of

 

Returns

Value of XML node or NULL, which is internal and should not be modified or freed.


ipatch_xml_dup_value ()

char *
ipatch_xml_dup_value (GNode *node);

Duplicate the text value of an XML node. Like ipatch_xml_get_value() but makes a copy of the value which the caller owns.

[skip]

Parameters

node

XML node to duplicate value of

 

Returns

Newly allocated duplicate value of XML node or NULL.


ipatch_xml_test_value ()

gboolean
ipatch_xml_test_value (GNode *node,
                       const char *cmpvalue);

Test if the node has the given value.

[skip]

Parameters

node

XML node to get name of

 

cmpvalue

Value to compare to

 

Returns

TRUE if the node has the given value, FALSE otherwise


ipatch_xml_set_attribute ()

void
ipatch_xml_set_attribute (GNode *node,
                          const char *attr_name,
                          const char *attr_value);

Set or unset an attribute of an XML node. If there is already an existing attribute with the given attr_name , its value will be replaced.

[skip]

Parameters

node

XML node

 

attr_name

Attribute name to assign to

 

attr_value

Attribute value to assign or NULL to unset.

[nullable]

ipatch_xml_set_attributes ()

void
ipatch_xml_set_attributes (GNode *node,
                           const char *attr_name,
                           const char *attr_value,
                           const char *attr2_name,
                           ...);

Set one or more attributes of an XML node.

[skip]

Parameters

node

XML node

 

attr_name

First attribute name

 

attr_value

First attribute value

 

...

Additional name/value attribute strings, terminated by a NULL name

 

ipatch_xml_get_attribute ()

const char *
ipatch_xml_get_attribute (GNode *node,
                          const char *attr_name);

Get the value of an attribute of an XML node.

[skip]

Parameters

node

XML node

 

attr_name

Name of attribute

 

Returns

Value of the named attribute or NULL if not found, value is internal and should not be modified or freed.


ipatch_xml_test_attribute ()

gboolean
ipatch_xml_test_attribute (GNode *node,
                           const char *attr_name,
                           const char *cmpval);

Test if an attribute of an XML node is a given value or exists (cmpval = NULL).

[skip]

Parameters

node

XML node

 

attr_name

Name of attribute

 

cmpval

Value to compare attribute to (NULL to just check existence).

 

Returns

TRUE if attribute exists and matches cmpval (if set).


ipatch_xml_find_child ()

GNode *
ipatch_xml_find_child (GNode *node,
                       const char *name);

Find a child node with the given name . Only searches the children of node and does not search recursively.

[skip]

Parameters

node

XML node

 

name

Node name of child to find

 

Returns

Matching node or NULL if not found.

[transfer none]


ipatch_xml_find_by_path ()

GNode *
ipatch_xml_find_by_path (GNode *node,
                         const char *path);

Get a node in a tree from a path string.

[skip]

Parameters

node

XML node

 

path

Path specification in the form "name1.name2.name3" where each child of a node is separated by a '.' character.

 

Returns

Matching node or NULL if not found.

[transfer none]


ipatch_xml_to_str ()

char *
ipatch_xml_to_str (GNode *node,
                   guint indent);

Render an XML tree to a string.

[skip]

Parameters

node

XML node

 

indent

Number of spaces of indent per level (0 for no indent)

 

Returns

Newly allocated string of XML content representing node , free with g_free() when done using it.


ipatch_xml_save_to_file ()

gboolean
ipatch_xml_save_to_file (GNode *node,
                         guint indent,
                         const char *filename,
                         GError **err);

Store an XML tree to a file.

[skip]

Parameters

node

XML tree to save

 

indent

Number of spaces to indent per level

 

filename

File name to save to

 

err

Location to store error info or NULL to ignore

 

Returns

TRUE on success, FALSE otherwise (in which case err may be set)


ipatch_xml_from_str ()

GNode *
ipatch_xml_from_str (const char *str,
                     GError **err);

Parse XML content into an XML node tree.

[skip]

Parameters

str

XML content to parse

 

err

Location to store error info or NULL to ignore

 

Returns

Newly allocated XML node tree or NULL on error (err may be set), can be freed with ipatch_xml_destroy().


ipatch_xml_load_from_file ()

GNode *
ipatch_xml_load_from_file (const char *filename,
                           GError **err);

Parse an XML file into an XML node tree.

[skip]

Parameters

filename

File name containing XML content to parse

 

err

Location to store error info or NULL to ignore

 

Returns

Newly allocated XML node tree or NULL on error (err may be set), can be freed with ipatch_xml_destroy().


ipatch_xml_node_new ()

IpatchXmlNode *
ipatch_xml_node_new (void);

Create a new XML node structure. Not normally used.

[skip]

Returns

New XML node structure, which should be added to a GNode.


ipatch_xml_node_free ()

void
ipatch_xml_node_free (IpatchXmlNode *xmlnode);

Free an XML node structure and its contents. Not normally used.

[skip]

Parameters

xmlnode

XML node structure to free

 

ipatch_xml_node_duplicate ()

IpatchXmlNode *
ipatch_xml_node_duplicate (const IpatchXmlNode *xmlnode);

Duplicate an XML node structure and its contents. Not normally used. Note that arbitrary user data assigned to the XML node will not be duplicated.

[skip]

Parameters

xmlnode

XML node structure to duplicate

 

Returns

New duplicate of xmlnode .


ipatch_xml_attr_new ()

IpatchXmlAttr *
ipatch_xml_attr_new (void);

Create a new XML attribute structure. Not normally used.

[skip]

Returns

New XML attribute structure which should be added to an IpatchXmlNode attributes list.


ipatch_xml_attr_free ()

void
ipatch_xml_attr_free (IpatchXmlAttr *attr);

Free an XML attribute structure. Not normally used.

[skip]

Parameters

attr

Attribute structure to free

 

ipatch_xml_attr_duplicate ()

IpatchXmlAttr *
ipatch_xml_attr_duplicate (const IpatchXmlAttr *attr);

Duplicate an XML attribute structure. Not normally used.

[skip]

Parameters

attr

Attribute structure to duplicate

 

Returns

New duplicate attribute structure

Types and Values

struct IpatchXmlAttr

struct IpatchXmlAttr {
    char *name;
    char *value;
};

Structure for storing an XML attribute.

Members

char *name;

Attribute name

 

char *value;

Attribute value

 

struct IpatchXmlNode

struct IpatchXmlNode {
    char *name;		/* XML element name */
    char *value;		/* Text content of element */
    GData *qdata;		/* To associate arbitrary data with XML nodes */
    GList *attributes; /* List of IpatchXmlAttr structures */
};

An XML element node. Note that a given node can contain only one text value.

Members

char *name;

XML element name

 

char *value;

XML text value or NULL

 

GData *qdata;

   

GList *attributes;

Linked list of IpatchXmlAttr structures

 

See Also

IpatchXmlObject