IpatchXml

IpatchXml — XML tree functions

Stability Level

Stable, unless otherwise indicated

Synopsis

                    IpatchXmlNode;
                    IpatchXmlAttr;
GNode *             ipatch_xml_new_node                 (GNode *parent,
                                                         const char *name,
                                                         const char *value,
                                                         const char *attr_name,
                                                         ...);
GNode *             ipatch_xml_new_node_strv            (GNode *parent,
                                                         const char *name,
                                                         const char *value,
                                                         const char **attr_names,
                                                         const char **attr_values);
gpointer            ipatch_xml_get_data                 (GNode *node,
                                                         const char *key);
void                ipatch_xml_set_data                 (GNode *node,
                                                         const char *key,
                                                         gpointer data);
void                ipatch_xml_set_data_full            (GNode *node,
                                                         const char *key,
                                                         gpointer data,
                                                         GDestroyNotify destroy_func);
gpointer            ipatch_xml_steal_data               (GNode *node,
                                                         const char *key);
gpointer            ipatch_xml_get_qdata                (GNode *node,
                                                         GQuark quark);
void                ipatch_xml_set_qdata                (GNode *node,
                                                         GQuark quark,
                                                         gpointer data);
void                ipatch_xml_set_qdata_full           (GNode *node,
                                                         GQuark quark,
                                                         gpointer data,
                                                         GDestroyNotify destroy_func);
gpointer            ipatch_xml_steal_qdata              (GNode *node,
                                                         GQuark quark);
void                ipatch_xml_destroy                  (GNode *node);
GNode *             ipatch_xml_copy                     (GNode *node);
void                ipatch_xml_set_name                 (GNode *node,
                                                         const char *name);
void                ipatch_xml_set_value                (GNode *node,
                                                         const char *value);
void                ipatch_xml_set_value_printf         (GNode *node,
                                                         const char *format,
                                                         ...);
void                ipatch_xml_take_name                (GNode *node,
                                                         char *name);
void                ipatch_xml_take_value               (GNode *node,
                                                         char *value);
const char *        ipatch_xml_get_name                 (GNode *node);
gboolean            ipatch_xml_test_name                (GNode *node,
                                                         const char *cmpname);
const char *        ipatch_xml_get_value                (GNode *node);
char *              ipatch_xml_dup_value                (GNode *node);
gboolean            ipatch_xml_test_value               (GNode *node,
                                                         const char *cmpvalue);
void                ipatch_xml_set_attribute            (GNode *node,
                                                         const char *attr_name,
                                                         const char *attr_value);
void                ipatch_xml_set_attributes           (GNode *node,
                                                         const char *attr_name,
                                                         const char *attr_value,
                                                         const char *attr2_name,
                                                         ...);
const char *        ipatch_xml_get_attribute            (GNode *node,
                                                         const char *name);
gboolean            ipatch_xml_test_attribute           (GNode *node,
                                                         const char *attr_name,
                                                         const char *cmpval);
GNode *             ipatch_xml_find_child               (GNode *node,
                                                         const char *name);
GNode *             ipatch_xml_find_by_path             (GNode *node,
                                                         const char *path);
char *              ipatch_xml_to_str                   (GNode *node,
                                                         guint indent);
gboolean            ipatch_xml_save_to_file             (GNode *node,
                                                         guint indent,
                                                         const char *filename,
                                                         GError **err);
GNode *             ipatch_xml_from_str                 (const char *str,
                                                         GError **err);
GNode *             ipatch_xml_load_from_file           (const char *filename,
                                                         GError **err);
IpatchXmlNode *     ipatch_xml_node_new                 (void);
void                ipatch_xml_node_free                (IpatchXmlNode *node);
IpatchXmlNode *     ipatch_xml_node_duplicate           (const IpatchXmlNode *xmlnode);
IpatchXmlAttr *     ipatch_xml_attr_new                 (void);
void                ipatch_xml_attr_free                (IpatchXmlAttr *attr);
IpatchXmlAttr *     ipatch_xml_attr_duplicate           (const IpatchXmlAttr *attr);

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.

Details

IpatchXmlNode

typedef struct {
  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 */
} IpatchXmlNode;

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

char *name;

 XML element name

char *value;

 XML text value or NULL

GData *qdata;

GList *attributes;

 Linked list of IpatchXmlAttr structures

IpatchXmlAttr

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

Structure for storing an XML attribute.

char *name;

 Attribute name

char *value;

 Attribute value

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.

parent :

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

name :

 Name of the new XML node

value :

 Text value to assign to the new node or NULL

attr_name :

 First attribute name to assign or NULL

... :

 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.

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.

parent :

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

name :

 Name of the new XML node

value :

 Text value to assign to the new node or NULL

attr_names :

 NULL terminated array of attribute names or NULL

attr_values :

 NULL terminated array of attribute values or NULL

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 using a quark. This is faster than ipatch_xml_get_data() since the key must be converted to a quark anyways.

node :

 XML node

quark :

 Quark 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.

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.

node :

 XML node

key :

 Name of the key

data :

 Data to associate with the key

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.

node :

 XML node

key :

 Name of the key

Returns :

 The data pointer or NULL if not set

ipatch_xml_get_qdata ()

gpointer            ipatch_xml_get_qdata                (GNode *node,
                                                         GQuark quark);

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.

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.

node :

 XML node

quark :

 Quark key

data :

 Data to associate with the key

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.

node :

 XML node

quark :

 Quark key

Returns :

 The data pointer or NULL if not set

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.

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.

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.

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.

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.

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.

node :

 XML node

name :

 Name to assign or NULL to clear it

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.

node :

 XML node

value :

 Text value to assign

ipatch_xml_get_name ()

const char *        ipatch_xml_get_name                 (GNode *node);

Get the name of an XML node.

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.

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.

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.

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.

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.

node :

 XML node

attr_name :

 Attribute name to assign to

attr_value :

 Attribute value to assign or NULL to unset

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.

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 *name);

Get the value of an attribute of an XML node.

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).

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.

node :

 XML node

name :

 Node name of child to find

Returns :

 Matching node or NULL if not found.

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.

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.

ipatch_xml_to_str ()

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

Render an XML tree to a string.

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.

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.

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.

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.

Returns :

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

ipatch_xml_node_free ()

void                ipatch_xml_node_free                (IpatchXmlNode *node);

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

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.

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.

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.

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.

attr :

 Attribute structure to duplicate

Returns :

 New duplicate attribute structure

See Also

IpatchXmlObject
Generated by GTK-Doc V1.15