XbNode: libxmlb Reference Manual

## XbNode XbNode |

## Functions

gboolean | (*XbNodeTransmogrifyFunc) ()
gboolean | xb_node_transmogrify ()
gchar * | xb_node_export ()
GBytes * | xb_node_get_data ()
void | xb_node_set_data ()
XbNode * | xb_node_get_root ()
XbNode * | xb_node_get_parent ()
XbNode * | xb_node_get_next ()
XbNode * | xb_node_get_child ()
GPtrArray * | xb_node_get_children ()
const gchar * | xb_node_get_element ()
const gchar * | xb_node_get_text ()
guint64 | xb_node_get_text_as_uint ()
const gchar * | xb_node_get_tail ()
const gchar * | xb_node_get_attr ()
guint64 | xb_node_get_attr_as_uint ()
guint | xb_node_get_depth ()
void | xb_node_attr_iter_init ()
gboolean | xb_node_attr_iter_next ()
void | xb_node_child_iter_init ()
gboolean | xb_node_child_iter_next ()
gboolean | xb_node_child_iter_loop ()

## Types and Values

#define | XB_TYPE_NODE
struct | XbNodeClass
enum | XbNodeExportFlags
| XbNodeAttrIter
| XbNodeChildIter
| XbNode

## Description

## Functions

### XbNodeTransmogrifyFunc ()

    gboolean
    (*XbNodeTransmogrifyFunc) (XbNode *self,
                               gpointer user_data);

### xb_node_transmogrify ()

    gboolean
    xb_node_transmogrify (XbNode *self,
                          XbNodeTransmogrifyFunc func_text,
                          XbNodeTransmogrifyFunc func_tail,
                          gpointer user_data);

Traverses a tree starting from `self` . It calls the given functions for each node visited. This allows transmogrification of the source, for instance converting the XML description to PangoMarkup or even something completely different like markdown.

The traversal can be halted at any point by returning TRUE from `func` .

#### Parameters

self | a XbNode |
func_text | (allow-none): a XbBuilderNodeTraverseFunc. | [scope call]
func_tail | (allow-none): a XbBuilderNodeTraverseFunc. | [scope call]
user_data | user pointer to pass to `func` , or `NULL` |

#### Returns

`TRUE` if all nodes were visited

Since: 0.1.12

### xb_node_export ()

    gchar *
    xb_node_export (XbNode *self,
                    XbNodeExportFlags flags,
                    GError **error);

Exports the node back to XML.

#### Parameters

self | a XbNode |
flags | some XbNodeExportFlags, e.g. XB_NODE_EXPORT_FLAG_NONE |
error | the GError, or `NULL` |

#### Returns

XML data, or `NULL` for an error

Since: 0.1.0

### xb_node_get_data ()

    GBytes *
    xb_node_get_data (XbNode *self,
                      const gchar *key);

Gets any data that has been set on the node using `xb_node_set_data()`.

This will only work across queries to the associated silo if the silo has its “enable-node-cache” property set to `TRUE`. Otherwise a new XbNode may be constructed for future queries which return the same element as a result.

#### Parameters

self | a XbNode |
key | a string key, e.g. `fwupd::RemoteId` |

#### Returns

a GBytes, or `NULL` if not found.

[transfer none]

Since: 0.1.0

### xb_node_set_data ()

    void
    xb_node_set_data (XbNode *self,
                      const gchar *key,
                      GBytes *data);

Sets some data on the node which can be retrieved using `xb_node_get_data()`.

This will only work across queries to the associated silo if the silo has its “enable-node-cache” property set to `TRUE`. Otherwise a new XbNode may be constructed for future queries which return the same element as a result.

#### Parameters

self | a XbNode |
key | a string key, e.g. `fwupd::RemoteId` |
data | a GBytes |

Since: 0.1.0

### xb_node_get_root ()

    XbNode *
    xb_node_get_root (XbNode *self);

Gets the root node for the node.

#### Parameters

self | a XbNode |

#### Returns

a XbNode, or `NULL`.

[transfer full]

Since: 0.1.0

### xb_node_get_parent ()

    XbNode *
    xb_node_get_parent (XbNode *self);

Gets the parent node for the current node.

#### Parameters

self | a XbNode |

#### Returns

a XbNode, or `NULL`.

[transfer full]

Since: 0.1.0

### xb_node_get_next ()

    XbNode *
    xb_node_get_next (XbNode *self);

Gets the next sibling node for the current node.

#### Parameters

self | a XbNode |

#### Returns

a XbNode, or `NULL`.

[transfer full]

Since: 0.1.0

### xb_node_get_child ()

    XbNode *
    xb_node_get_child (XbNode *self);

Gets the first child node for the current node.

#### Parameters

self | a XbNode |

#### Returns

a XbNode, or `NULL`.

[transfer full]

Since: 0.1.0

### xb_node_get_children ()

    GPtrArray *
    xb_node_get_children (XbNode *self);

Gets all the children for the current node.

#### Parameters

self | a XbNode |

#### Returns

an array of children.

[transfer container][element-type XbNode]

Since: 0.1.0

### xb_node_get_element ()

    const gchar *
    xb_node_get_element (XbNode *self);

Gets the element name for a specific node.

#### Parameters

self | a XbNode |

#### Returns

a string, or `NULL` for the root node

Since: 0.1.0

### xb_node_get_text ()

    const gchar *
    xb_node_get_text (XbNode *self);

Gets the text data for a specific node.

#### Parameters

self | a XbNode |

#### Returns

a string, or `NULL` for unset

Since: 0.1.0

### xb_node_get_text_as_uint ()

    guint64
    xb_node_get_text_as_uint (XbNode *self);

Gets some attribute text data for a specific node.

#### Parameters

self | a XbNode |

#### Returns

a guint64, or `G_MAXUINT64` if unfound

Since: 0.1.0

### xb_node_get_tail ()

    const gchar *
    xb_node_get_tail (XbNode *self);

Gets the tail data for a specific node.

#### Parameters

self | a XbNode |

#### Returns

a string, or `NULL` for unset

Since: 0.1.12

### xb_node_get_attr ()

    const gchar *
    xb_node_get_attr (XbNode *self,
                      const gchar *name);

Gets some attribute text data for a specific node.

#### Parameters

self | a XbNode |
name | an attribute name, e.g. "type" |

#### Returns

a string, or `NULL` for unset

Since: 0.1.0

### xb_node_get_attr_as_uint ()

    guint64
    xb_node_get_attr_as_uint (XbNode *self,
                              const gchar *name);

Gets some attribute text data for a specific node.

#### Parameters

self | a XbNode |
name | an attribute name, e.g. `type` |

#### Returns

a guint64, or `G_MAXUINT64` if unfound

Since: 0.1.0

### xb_node_get_depth ()

    guint
    xb_node_get_depth (XbNode *self);

Gets the depth of the node to a root.

#### Parameters

self | a XbNode |

#### Returns

a integer, where 0 is the root node itself.

Since: 0.1.0

### xb_node_attr_iter_init ()

    void
    xb_node_attr_iter_init (XbNodeAttrIter *iter,
                            XbNode *self);

Initializes a name/value pair iterator for the node attributes and associates it with `self` . The XbNodeAttrIter structure is typically allocated on the stack and does not need to be freed explicitly.

#### Parameters

iter | an uninitialized XbNodeAttrIter |
self | a XbNode |

Since: 0.3.4

### xb_node_attr_iter_next ()

    gboolean
    xb_node_attr_iter_next (XbNodeAttrIter *iter,
                            const gchar **name,
                            const gchar **value);

Returns the current attribute name and value and advances the iterator. Example:

    1
    2
    3
    4
    5
    6
    7
    8
    XbNodeAttrIter iter;
    const gchar *attr_name;
    const gchar *attr_value;

    xb_node_attr_iter_init (&iter, node);
    while (xb_node_attr_iter_next (&iter, &attr_name, &attr_value)) {
        // use attr_name and attr_value; no need to free them
    }

#### Parameters

iter | an initialized XbNodeAttrIter |
name | Destination of the returned attribute name. | [out][optional][not nullable]
value | Destination of the returned attribute value. | [out][optional][not nullable]

#### Returns

`TRUE` if there are more attributes.

Since: 0.3.4

### xb_node_child_iter_init ()

    void
    xb_node_child_iter_init (XbNodeChildIter *iter,
                             XbNode *self);

Initializes a child iterator for the node's children and associates it with `self` . The XbNodeChildIter structure is typically allocated on the stack and does not need to be freed explicitly.

#### Parameters

iter | an uninitialized XbNodeChildIter |
self | a XbNode |

Since: 0.3.4

### xb_node_child_iter_next ()

    gboolean
    xb_node_child_iter_next (XbNodeChildIter *iter,
                             XbNode **child);

Returns the current child and advances the iterator. The retrieved XbNode child needs to be dereferenced with `g_object_unref()`. Example:

    1
    2
    3
    4
    5
    6
    7
    8
    XbNodeChildIter iter;
    g_autoptr(XbNode) child = NULL;

    xb_node_child_iter_init (&iter, node);
    while (xb_node_child_iter_next (&iter, &child)) {
        // do something with the node child
        g_clear_pointer (&child, g_object_unref);
    }

#### Parameters

iter | an initialized XbNodeAttrIter |
child | Destination of the returned child. | [out][optional][not nullable]

#### Returns

`FALSE` if the last child has been reached.

Since: 0.3.4

### xb_node_child_iter_loop ()

    gboolean
    xb_node_child_iter_loop (XbNodeChildIter *iter,
                             XbNode **child);

Returns the current child and advances the iterator. On the first call to this function, the `child` pointer is assumed to point at uninitialised memory. On any later calls, it is assumed that the same pointers will be given and that they will point to the memory as set by the previous call to this function. This allows the previous values to be freed, as appropriate.

Example:

    1
    2
    3
    4
    5
    6
    7
    8
    XbNodeChildIter iter;
    XbNode *child;

    xb_node_child_iter_init (&iter, node);
    while (xb_node_child_iter_loop (&iter, &child)) {
        // do something with the node child
        // no need to free 'child' unless breaking out of this loop
    }

[skip]

#### Parameters

iter | an initialized XbNodeAttrIter |
child | Destination of the returned child. | [out][optional][nullable]

#### Returns

`FALSE` if the last child has been reached.

Since: 0.3.4

## Types and Values

### XB_TYPE_NODE

    #define             XB_TYPE_NODE

### struct XbNodeClass

    struct XbNodeClass {
    	GObjectClass parent_class;
    };

### enum XbNodeExportFlags

The flags for converting to XML.

#### Members

XB_NODE_EXPORT_FLAG_NONE |  |
XB_NODE_EXPORT_FLAG_ADD_HEADER |  |
XB_NODE_EXPORT_FLAG_FORMAT_MULTILINE |  |
XB_NODE_EXPORT_FLAG_FORMAT_INDENT |  |
XB_NODE_EXPORT_FLAG_INCLUDE_SIBLINGS |  |
XB_NODE_EXPORT_FLAG_ONLY_CHILDREN |  |
XB_NODE_EXPORT_FLAG_COLLAPSE_EMPTY |  |

### XbNodeAttrIter

    typedef struct {
    } XbNodeAttrIter;

A XbNodeAttrIter structure represents an iterator that can be used to iterate over the attributes of a XbNode. XbNodeAttrIter structures are typically allocated on the stack and then initialized with `xb_node_attr_iter_init()`.

The iteration order of a XbNodeAttrIter is not defined.

Since: 0.3.4

### XbNodeChildIter

    typedef struct {
    } XbNodeChildIter;

A XbNodeChildIter structure represents an iterator that can be used to iterate over the children of a XbNode. XbNodeChildIter structures are typically allocated on the stack and then initialized with `xb_node_child_iter_init()`.

Since: 0.3.4

### XbNode

    typedef struct _XbNode XbNode;