| libinstpatch Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | ||||
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);
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.
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 * |
XML element name |
char * |
XML text value or NULL
|
GData * |
|
GList * |
Linked list of IpatchXmlAttr structures |
typedef struct {
char *name;
char *value;
} IpatchXmlAttr;
Structure for storing an XML attribute.
char * |
Attribute name |
char * |
Attribute value |
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 node to add new node to as a child, or NULL to create new root node
|
|
Name of the new XML node |
|
Text value to assign to the new node or NULL
|
|
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 |
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 node to add new node to as a child, or NULL to create new root node
|
|
Name of the new XML node |
|
Text value to assign to the new node or NULL
|
|
NULL terminated array of attribute names or NULL
|
|
NULL terminated array of attribute values or NULL
|
Returns : |
New XML tree node |
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.
|
XML node |
|
Quark key |
Returns : |
The data pointer or NULL if not set
|
void ipatch_xml_set_data (GNode *node, const char *key, gpointer data);
Assigns arbitrary data to an XML node specified by a key.
|
XML node |
|
Name of the key |
|
Data to associate with the key |
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.
|
XML node |
|
Name of the key |
|
Data to associate with the key |
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.
|
XML node |
|
Name of the key |
Returns : |
The data pointer or NULL if not set
|
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.
|
XML node |
|
Quark key |
|
Data to associate with the key |
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.
|
XML node |
|
Quark key |
|
Data to associate with the key |
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.
|
XML node |
|
Quark key |
Returns : |
The data pointer or NULL if not set
|
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.
|
Root of XML tree/sub tree to destroy |
GNode * ipatch_xml_copy (GNode *node);
Perform a deep copy on an XML tree.
|
XML tree to copy |
Returns : |
New duplicate XML tree. |
void ipatch_xml_set_name (GNode *node, const char *name);
Set the name of an XML node.
|
XML node |
|
Name to assign |
void ipatch_xml_set_value (GNode *node, const char *value);
Set the text value of an XML node.
|
XML node |
|
Text value to assign or NULL to clear it
|
void ipatch_xml_set_value_printf (GNode *node, const char *format, ...);
Assign a value to an XML node using a printf format and arguments.
|
XML node |
|
Printf format |
|
Printf arguments |
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.
|
XML node |
|
Name to assign or NULL to clear it
|
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.
|
XML node |
|
Text value to assign |
const char * ipatch_xml_get_name (GNode *node);
Get the name of an XML node.
|
XML node to get name of |
Returns : |
Name of XML node which is internal and should not be modified or freed. |
gboolean ipatch_xml_test_name (GNode *node, const char *cmpname);
Test if the node has the given name.
|
XML node to get name of |
|
Name to compare to |
Returns : |
TRUE if the node has the given name, FALSE otherwise
|
const char * ipatch_xml_get_value (GNode *node);
Get the text value of an XML node.
|
XML node to get value of |
Returns : |
Value of XML node or NULL, which is internal and should not be
modified or freed.
|
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.
|
XML node to duplicate value of |
Returns : |
Newly allocated duplicate value of XML node or NULL.
|
gboolean ipatch_xml_test_value (GNode *node, const char *cmpvalue);
Test if the node has the given value.
|
XML node to get name of |
|
Value to compare to |
Returns : |
TRUE if the node has the given value, FALSE otherwise
|
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.
|
XML node |
|
Attribute name to assign to |
|
Attribute value to assign or NULL to unset
|
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.
|
XML node |
|
First attribute name |
|
First attribute value |
|
Additional name/value attribute strings, terminated by a NULL name
|
const char * ipatch_xml_get_attribute (GNode *node, const char *name);
Get the value of an attribute of an XML node.
|
XML node |
|
Name of attribute |
Returns : |
Value of the named attribute or NULL if not found, value is internal
and should not be modified or freed.
|
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).
|
XML node |
|
Name of attribute |
|
Value to compare attribute to (NULL to just check existence).
|
Returns : |
TRUE if attribute exists and matches cmpval (if set).
|
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.
|
XML node |
|
Node name of child to find |
Returns : |
Matching node or NULL if not found.
|
GNode * ipatch_xml_find_by_path (GNode *node, const char *path);
Get a node in a tree from a path string.
|
XML node |
|
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.
|
char * ipatch_xml_to_str (GNode *node, guint indent);
Render an XML tree to a string.
|
XML node |
|
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.
|
gboolean ipatch_xml_save_to_file (GNode *node, guint indent, const char *filename, GError **err);
Store an XML tree to a file.
|
XML tree to save |
|
Number of spaces to indent per level |
|
File name to save to |
|
Location to store error info or NULL to ignore
|
Returns : |
TRUE on success, FALSE otherwise (in which case err may be set)
|
GNode * ipatch_xml_from_str (const char *str, GError **err);
Parse XML content into an XML node tree.
|
XML content to parse |
|
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().
|
GNode * ipatch_xml_load_from_file (const char *filename, GError **err);
Parse an XML file into an XML node tree.
|
File name containing XML content to parse |
|
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().
|
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. |
void ipatch_xml_node_free (IpatchXmlNode *node);
Free an XML node structure and its contents. Not normally used.
|
XML node structure to free |
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.
|
XML node structure to duplicate |
Returns : |
New duplicate of xmlnode.
|
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. |
void ipatch_xml_attr_free (IpatchXmlAttr *attr);
Free an XML attribute structure. Not normally used.
|
Attribute structure to free |
IpatchXmlAttr * ipatch_xml_attr_duplicate (const IpatchXmlAttr *attr);
Duplicate an XML attribute structure. Not normally used.
|
Attribute structure to duplicate |
Returns : |
New duplicate attribute structure |