WockyNode

## WockyNode WockyNode — representation of a XMPP node |

## Synopsis

    #include <wocky/wocky-node.h>

    enum                WockyNodeBuildTag;
                        WockyNode;
    gboolean            (*wocky_node_each_attr_func)        (const gchar *key,
                                                             const gchar *value,
                                                             const gchar *pref,
                                                             const gchar *ns,
                                                             gpointer user_data);
    gboolean            (*wocky_node_each_child_func)       (WockyNode *node,
                                                             gpointer user_data);
    void                wocky_node_each_attribute           (WockyNode *node,
                                                             wocky_node_each_attr_func func,
                                                             gpointer user_data);
    void                wocky_node_each_child               (WockyNode *node,
                                                             wocky_node_each_child_func func,
                                                             gpointer user_data);
    const gchar *       wocky_node_get_attribute            (WockyNode *node,
                                                             const gchar *key);
    const gchar *       wocky_node_get_attribute_ns         (WockyNode *node,
                                                             const gchar *key,
                                                             const gchar *ns);
    void                wocky_node_set_attribute            (WockyNode *node,
                                                             const gchar *key,
                                                             const gchar *value);
    void                wocky_node_set_attributes           (WockyNode *node,
                                                             const gchar *key,
                                                             ...);
    void                wocky_node_set_attribute_ns         (WockyNode *node,
                                                             const gchar *key,
                                                             const gchar *value,
                                                             const gchar *ns);
    void                wocky_node_set_attribute_n          (WockyNode *node,
                                                             const gchar *key,
                                                             const gchar *value,
                                                             gsize value_size);
    void                wocky_node_set_attribute_n_ns       (WockyNode *node,
                                                             const gchar *key,
                                                             const gchar *value,
                                                             gsize value_size,
                                                             const gchar *ns);
    const gchar *       wocky_node_attribute_ns_get_prefix_from_urn
                                                            (const gchar *urn);
    const gchar *       wocky_node_attribute_ns_get_prefix_from_quark
                                                            (GQuark ns);
    void                wocky_node_attribute_ns_set_prefix  (GQuark ns,
                                                             const gchar *prefix);
    WockyNode *         wocky_node_get_child                (WockyNode *node,
                                                             const gchar *name);
    WockyNode *         wocky_node_get_child_ns             (WockyNode *node,
                                                             const gchar *name,
                                                             const gchar *ns);
    WockyNode *         wocky_node_get_first_child          (WockyNode *node);
    WockyNode *         wocky_node_get_first_child_ns       (WockyNode *node,
                                                             const gchar *ns);
    const gchar *       wocky_node_get_content_from_child   (WockyNode *node,
                                                             const gchar *name);
    const gchar *       wocky_node_get_content_from_child_ns
                                                            (WockyNode *node,
                                                             const gchar *name,
                                                             const gchar *ns);
    WockyNode *         wocky_node_add_child                (WockyNode *node,
                                                             const gchar *name);
    WockyNode *         wocky_node_add_child_ns             (WockyNode *node,
                                                             const gchar *name,
                                                             const gchar *ns);
    WockyNode *         wocky_node_add_child_ns_q           (WockyNode *node,
                                                             const gchar *name,
                                                             GQuark ns);
    WockyNode *         wocky_node_add_child_with_content   (WockyNode *node,
                                                             const gchar *name,
                                                             const char *content);
    WockyNode *         wocky_node_add_child_with_content_ns
                                                            (WockyNode *node,
                                                             const gchar *name,
                                                             const gchar *content,
                                                             const gchar *ns);
    WockyNode *         wocky_node_add_child_with_content_ns_q
                                                            (WockyNode *node,
                                                             const gchar *name,
                                                             const gchar *content,
                                                             GQuark ns);
    const gchar *       wocky_node_get_ns                   (WockyNode *node);
    gboolean            wocky_node_has_ns                   (WockyNode *node,
                                                             const gchar *ns);
    gboolean            wocky_node_has_ns_q                 (WockyNode *node,
                                                             GQuark ns);
    const gchar *       wocky_node_get_language             (WockyNode *node);
    void                wocky_node_set_language             (WockyNode *node,
                                                             const gchar *lang);
    void                wocky_node_set_language_n           (WockyNode *node,
                                                             const gchar *lang,
                                                             gsize lang_size);
    void                wocky_node_set_content              (WockyNode *node,
                                                             const gchar *content);
    void                wocky_node_append_content           (WockyNode *node,
                                                             const gchar *content);
    void                wocky_node_append_content_n         (WockyNode *node,
                                                             const gchar *content,
                                                             gsize size);
    gchar *             wocky_node_to_string                (WockyNode *node);
    WockyNode *         wocky_node_new                      (const char *name,
                                                             const gchar *ns);
    void                wocky_node_free                     (WockyNode *node);
    gboolean            wocky_node_equal                    (WockyNode *node0,
                                                             WockyNode *node1);
    gboolean            wocky_node_is_superset              (WockyNode *node,
                                                             WockyNode *subset);
                        WockyNodeIter;
    void                wocky_node_iter_init                (WockyNodeIter *iter,
                                                             WockyNode *node,
                                                             const gchar *name,
                                                             const gchar *ns);
    gboolean            wocky_node_iter_next                (WockyNodeIter *iter,
                                                             WockyNode **next);
    void                wocky_node_add_build                (WockyNode *node,
                                                             ...);
    void                wocky_node_add_build_va             (WockyNode *node,
                                                             va_list va);
    void                wocky_node_add_node_tree            (WockyNode *node,
                                                             WockyNodeTree *tree);
    void                wocky_node_prepend_node_tree        (WockyNode *node,
                                                             WockyNodeTree *tree);
    void                wocky_node_init                     (void);
    void                wocky_node_deinit                   (void);

## Description

Low level representation of a XMPP node. Provides ways to set various parameters on the node, such as content, language, namespaces and prefixes. It also offers methods to lookup children of a node.

## Details

### enum WockyNodeBuildTag

    typedef enum
    {
      WOCKY_NODE_START = '(',
      WOCKY_NODE_TEXT = '$',
      WOCKY_NODE_END = 41, /* this is actually ')', but gtk-doc is broken: bgo#644291 */
      WOCKY_NODE_ATTRIBUTE = '@',
      WOCKY_NODE_XMLNS = ':',
      WOCKY_NODE_ASSIGN_TO = '*'
    } WockyNodeBuildTag;

Tags for building a stanza using `wocky_stanza_build()` or `wocky_node_add_build()`.

`WOCKY_NODE_START` | Start of a node
`WOCKY_NODE_TEXT` | Text content of a node
`WOCKY_NODE_END` | End of a node
`WOCKY_NODE_ATTRIBUTE` | A node attribute
`WOCKY_NODE_XMLNS` | A node XML namespace
`WOCKY_NODE_ASSIGN_TO` | a WockyNode to assign

### WockyNode

    typedef struct {
      gchar *name;
      gchar *content;
    } WockyNode;

A single WockyNode structure that relates to an element in an XMPP stanza.

gchar *`name`; | name of the node
gchar *`content`; | content of the node

### wocky_node_each_attr_func ()

    gboolean            (*wocky_node_each_attr_func)        (const gchar *key,
                                                             const gchar *value,
                                                             const gchar *pref,
                                                             const gchar *ns,
                                                             gpointer user_data);

Specifies the type of functions passed to `wocky_node_each_attribute()`.

`key` : | the attribute's key
`value` : | the attribute's value
`pref` : | the attribute's prefix
`ns` : | the attribute's namespace
`user_data` : | user data passed to `wocky_node_each_attribute()`
Returns : | `FALSE` to stop further attributes from being examined.

### wocky_node_each_child_func ()

    gboolean            (*wocky_node_each_child_func)       (WockyNode *node,
                                                             gpointer user_data);

Specifies the type of functions passed to `wocky_node_each_child()`.

`node` : | a WockyNode
`user_data` : | user data passed to `wocky_node_each_child()`
Returns : | `FALSE` to stop further children from being examined.

### wocky_node_each_attribute ()

    void                wocky_node_each_attribute           (WockyNode *node,
                                                             wocky_node_each_attr_func func,
                                                             gpointer user_data);

Calls a function for each attribute of a WockyNode.

`node` : | a WockyNode
`func` : | the function to be called on each node's attribute
`user_data` : | user data to pass to the function

### wocky_node_each_child ()

    void                wocky_node_each_child               (WockyNode *node,
                                                             wocky_node_each_child_func func,
                                                             gpointer user_data);

Calls a function for each child of a WockyNode.

`node` : | a WockyNode
`func` : | the function to be called on each node's child
`user_data` : | user data to pass to the function

### wocky_node_get_attribute ()

    const gchar *       wocky_node_get_attribute            (WockyNode *node,
                                                             const gchar *key);

Returns the value of an attribute in a WockyNode.

`node` : | a WockyNode
`key` : | the attribute name
Returns : | the value of the attribute `key`, or `NULL` if `node` doesn't have such attribute.

### wocky_node_get_attribute_ns ()

    const gchar *       wocky_node_get_attribute_ns         (WockyNode *node,
                                                             const gchar *key,
                                                             const gchar *ns);

Returns the value of an attribute in a WockyNode, limiting the search within a specific namespace. If the namespace is `NULL`, this is equivalent to `wocky_node_get_attribute()`.

`node` : | a WockyNode
`key` : | the attribute name
`ns` : | the namespace to search within, or `NULL`
Returns : | the value of the attribute `key`, or `NULL` if `node` doesn't have such attribute in `ns`.

### wocky_node_set_attribute ()

    void                wocky_node_set_attribute            (WockyNode *node,
                                                             const gchar *key,
                                                             const gchar *value);

Sets an attribute in a WockyNode to a specific value.

`node` : | a WockyNode
`key` : | the attribute name to set
`value` : | the value to set

### wocky_node_set_attributes ()

    void                wocky_node_set_attributes           (WockyNode *node,
                                                             const gchar *key,
                                                             ...);

Sets attributes in a WockyNode to specific values.

`node` : | a WockyNode
`key` : | the attribute name to set
`...` : | pairs of keys and values, terminated by `NULL`

### wocky_node_set_attribute_ns ()

    void                wocky_node_set_attribute_ns         (WockyNode *node,
                                                             const gchar *key,
                                                             const gchar *value,
                                                             const gchar *ns);

Sets an attribute in a WockyNode, within a specific namespace. If the namespace is `NULL`, this is equivalent to `wocky_node_set_attribute()`.

`node` : | a WockyNode
`key` : | the attribute name to set
`value` : | the value to set
`ns` : | a namespace, or `NULL`

### wocky_node_set_attribute_n ()

    void                wocky_node_set_attribute_n          (WockyNode *node,
                                                             const gchar *key,
                                                             const gchar *value,
                                                             gsize value_size);

Sets a new attribute to a WockyNode, with the supplied values.

`node` : | a WockyNode
`key` : | the attribute to set
`value` : | the value to set
`value_size` : | the number of bytes of `value` to set as a value

### wocky_node_set_attribute_n_ns ()

    void                wocky_node_set_attribute_n_ns       (WockyNode *node,
                                                             const gchar *key,
                                                             const gchar *value,
                                                             gsize value_size,
                                                             const gchar *ns);

Sets a new attribute to a WockyNode, with the supplied values. If the namespace is `NULL`, this is equivalent to `wocky_node_set_attribute_n()`.

`node` : | a WockyNode
`key` : | the attribute to set
`value` : | the value to set
`value_size` : | the number of bytes of `value` to set as a value
`ns` : | a namespace, or `NULL`

### wocky_node_attribute_ns_get_prefix_from_urn ()

    const gchar *       wocky_node_attribute_ns_get_prefix_from_urn
                                                            (const gchar *urn);

Gets the prefix of the namespace identified by the URN.

`urn` : | a string containing an URN
Returns : | a string containing the prefix of the namespace `urn`.

### wocky_node_attribute_ns_get_prefix_from_quark ()

    const gchar *       wocky_node_attribute_ns_get_prefix_from_quark
                                                            (GQuark ns);

Gets the prefix of the namespace identified by the quark.

`ns` : | a quark corresponding to an XML namespace URN
Returns : | a string containing the prefix of the namespace `ns`.

### wocky_node_attribute_ns_set_prefix ()

    void                wocky_node_attribute_ns_set_prefix  (GQuark ns,
                                                             const gchar *prefix);

Sets a desired prefix for a namespace.

`ns` : | a GQuark
`prefix` : | a string containing the desired prefix

### wocky_node_get_child ()

    WockyNode *         wocky_node_get_child                (WockyNode *node,
                                                             const gchar *name);

Gets a child of a node, searching by name.

`node` : | a WockyNode
`name` : | the name of the child to get
Returns : | a WockyNode.

### wocky_node_get_child_ns ()

    WockyNode *         wocky_node_get_child_ns             (WockyNode *node,
                                                             const gchar *name,
                                                             const gchar *ns);

Gets the child of a node, searching by name and limiting the search to the specified namespace. If the namespace is `NULL`, this is equivalent to `wocky_node_get_child()`

`node` : | a WockyNode
`name` : | the name of the child to get
`ns` : | the namespace of the child to get, or `NULL`
Returns : | a WockyNode.

### wocky_node_get_first_child ()

    WockyNode *         wocky_node_get_first_child          (WockyNode *node);

Convenience function to return the first child of a WockyNode.

`node` : | a WockyNode
Returns : | a WockyNode, or `NULL` if `node` has no children.

### wocky_node_get_first_child_ns ()

    WockyNode *         wocky_node_get_first_child_ns       (WockyNode *node,
                                                             const gchar *ns);

Returns the first child of `node` whose namespace is `ns`, saving you the bother of faffing around with a WockyNodeIter.

`node` : | a WockyNode
`ns` : | the namespace of the child node you seek.
Returns : | the first child of `node` whose namespace is `ns`, or `NULL` if none is found.

### wocky_node_get_content_from_child ()

    const gchar *       wocky_node_get_content_from_child   (WockyNode *node,
                                                             const gchar *name);

Retrieves the content from a child of a node, if it exists.

`node` : | a WockyNode
`name` : | the name of the child whose content to retrieve
Returns : | the content of the child of `node` named `name`, or `NULL` if `node` has no such child.

### wocky_node_get_content_from_child_ns ()

    const gchar *       wocky_node_get_content_from_child_ns
                                                            (WockyNode *node,
                                                             const gchar *name,
                                                             const gchar *ns);

Retrieves the content from a child of a node, if it exists.

`node` : | a WockyNode
`name` : | the name of the child whose content to retrieve
`ns` : | the namespace of the child whose content to retrieve
Returns : | the content of the child of `node` named `name` in `ns`, or `NULL` if `node` has no such child.

### wocky_node_add_child ()

    WockyNode *         wocky_node_add_child                (WockyNode *node,
                                                             const gchar *name);

Adds a WockyNode with the specified name to an already existing node.

`node` : | a WockyNode
`name` : | the name of the child to add
Returns : | the newly added WockyNode.

### wocky_node_add_child_ns ()

    WockyNode *         wocky_node_add_child_ns             (WockyNode *node,
                                                             const gchar *name,
                                                             const gchar *ns);

Adds a WockyNode with the specified name to an already existing node, under the specified namespace. If the namespace is `NULL`, this is equivalent to `wocky_node_add_child()`.

`node` : | a WockyNode
`name` : | the name of the child to add
`ns` : | a namespace
Returns : | the newly added WockyNode.

### wocky_node_add_child_ns_q ()

    WockyNode *         wocky_node_add_child_ns_q           (WockyNode *node,
                                                             const gchar *name,
                                                             GQuark ns);

Adds a WockyNode with the specified name to an already existing node, under the specified namespace. If the namespace is 0, this is equivalent to `wocky_node_add_child()`.

`node` : | a WockyNode
`name` : | the name of the child to add
`ns` : | a namespace
Returns : | the newly added WockyNode.

### wocky_node_add_child_with_content ()

    WockyNode *         wocky_node_add_child_with_content   (WockyNode *node,
                                                             const gchar *name,
                                                             const char *content);

Adds a WockyNode with the specified name and containing the specified content to an already existing node.

`node` : | a WockyNode
`name` : | the name of the child to add
`content` : | the content of the child to add
Returns : | the newly added WockyNode.

### wocky_node_add_child_with_content_ns ()

    WockyNode *         wocky_node_add_child_with_content_ns
                                                            (WockyNode *node,
                                                             const gchar *name,
                                                             const gchar *content,
                                                             const gchar *ns);

Adds a WockyNode with the specified name and the specified content to an already existing node, under the specified namespace. If the namespace is `NULL`, this is equivalent to `wocky_node_add_child_with_content()`.

`node` : | a WockyNode
`name` : | the name of the child to add
`content` : | the content of the child to add
`ns` : | a namespace
Returns : | the newly added WockyNode.

### wocky_node_add_child_with_content_ns_q ()

    WockyNode *         wocky_node_add_child_with_content_ns_q
                                                            (WockyNode *node,
                                                             const gchar *name,
                                                             const gchar *content,
                                                             GQuark ns);

Adds a WockyNode with the specified name and the specified content to an already existing node, under the specified namespace. If the namespace is 0, this is equivalent to `wocky_node_add_child_with_content()`.

`node` : | a WockyNode
`name` : | the name of the child to add
`content` : | the content of the child to add
`ns` : | a namespace
Returns : | the newly added WockyNode.

### wocky_node_get_ns ()

    const gchar *       wocky_node_get_ns                   (WockyNode *node);

Gets the namespace of a WockyNode

`node` : | a WockyNode
Returns : | a string containing the namespace of the node.

### wocky_node_has_ns ()

    gboolean            wocky_node_has_ns                   (WockyNode *node,
                                                             const gchar *ns);

`node` : |
`ns` : |
Returns : |

### wocky_node_has_ns_q ()

    gboolean            wocky_node_has_ns_q                 (WockyNode *node,
                                                             GQuark ns);

`node` : |
`ns` : |
Returns : |

### wocky_node_get_language ()

    const gchar *       wocky_node_get_language             (WockyNode *node);

Gets the language of a WockyNode

`node` : | a WockyNode
Returns : | a string containing the language of the node.

### wocky_node_set_language ()

    void                wocky_node_set_language             (WockyNode *node,
                                                             const gchar *lang);

Sets the language of a WockyNode.

`node` : | a WockyNode
`lang` : | a `NULL`-terminated string containing the language

### wocky_node_set_language_n ()

    void                wocky_node_set_language_n           (WockyNode *node,
                                                             const gchar *lang,
                                                             gsize lang_size);

Sets the language of a WockyNode.

`node` : | a WockyNode
`lang` : | a language
`lang_size` : | the length of `lang`, in bytes.

### wocky_node_set_content ()

    void                wocky_node_set_content              (WockyNode *node,
                                                             const gchar *content);

Sets the content of a WockyNode.

`node` : | a WockyNode
`content` : | the content to set to the node

### wocky_node_append_content ()

    void                wocky_node_append_content           (WockyNode *node,
                                                             const gchar *content);

Appends some content to the content of a WockyNode.

`node` : | a WockyNode
`content` : | the content to append to the node

### wocky_node_append_content_n ()

    void                wocky_node_append_content_n         (WockyNode *node,
                                                             const gchar *content,
                                                             gsize size);

Appends a specified number of content bytes to the content of a WockyNode.

`node` : | a WockyNode
`content` : | the content to append to the node
`size` : | the size of the content to append

### wocky_node_to_string ()

    gchar *             wocky_node_to_string                (WockyNode *node);

Obtains a string representation of a WockyNode.

`node` : | a WockyNode
Returns : | a newly allocated string containing a serialization of the node.

### wocky_node_new ()

    WockyNode *         wocky_node_new                      (const char *name,
                                                             const gchar *ns);

Convenience function which creates a WockyNode and sets its name to `name`.

`name` : | the node's name (may not be NULL)
`ns` : | the nodes namespace (may not be NULL)
Returns : | a newly allocated WockyNode.

### wocky_node_free ()

    void                wocky_node_free                     (WockyNode *node);

Convenience function that frees the passed in WockyNode and all of its children.

`node` : | a WockyNode.

### wocky_node_equal ()

    gboolean            wocky_node_equal                    (WockyNode *node0,
                                                             WockyNode *node1);

Compares two WockyNodes for equality.

`node0` : | a WockyNode
`node1` : | a WockyNode to compare to `node0`
Returns : | `TRUE` if the two nodes are equal.

### wocky_node_is_superset ()

    gboolean            wocky_node_is_superset              (WockyNode *node,
                                                             WockyNode *subset);

`node` : | the WockyNode to test
`subset` : | the supposed subset
Returns : | `TRUE` if `node` is a superset of `subset`.

### WockyNodeIter

    typedef struct {
    } WockyNodeIter;

Iterate over a node's children. See `wocky_node_iter_init()` for more details.

### wocky_node_iter_init ()

    void                wocky_node_iter_init                (WockyNodeIter *iter,
                                                             WockyNode *node,
                                                             const gchar *name,
                                                             const gchar *ns);

Initializes an iterator that can be used to iterate over the children of `node`, filtered by `name` and `ns`

    1

`iter` : | unitialized iterator
`node` : | Node whose children to iterate over
`name` : | Name to filter on or `NULL`
`ns` : | namespace to filter on or `NULL`

### wocky_node_iter_next ()

    gboolean            wocky_node_iter_next                (WockyNodeIter *iter,
                                                             WockyNode **next);

Advances iter to the next child that matches its filter. if `FALSE` is returned next is not set and the iterator becomes invalid

`iter` : | an initialized WockyNodeIter
`next` : | a location to store the next child
Returns : | `FALSE` if the last child has been reached

### wocky_node_add_build ()

    void                wocky_node_add_build                (WockyNode *node,
                                                             ...);

Add a node subtree to an existing parent node.

Example 1.

    1

The above examples adds the following subtree under the given node:

    <body>
       Telepathy rocks!
    </body>

`node` : | The node under which to add a new subtree
`...` : | the description of the stanza to build, terminated with `NULL`

### wocky_node_add_build_va ()

    void                wocky_node_add_build_va             (WockyNode *node,
                                                             va_list va);

`node` : |
`va` : |

### wocky_node_add_node_tree ()

    void                wocky_node_add_node_tree            (WockyNode *node,
                                                             WockyNodeTree *tree);

Copies the nodes from `tree`, and appends them to `node`'s children.

`node` : | A node
`tree` : | The node tree to add

### wocky_node_prepend_node_tree ()

    void                wocky_node_prepend_node_tree        (WockyNode *node,
                                                             WockyNodeTree *tree);

Copies the nodes from `tree`, and inserts them as the first child of `node`, before any existing children.

`node` : | a node
`tree` : | the node tree to prepend to `node`'s children

### wocky_node_init ()

    void                wocky_node_init                     (void);

Initializes the caches used by WockyNode. This should be always called before using WockyNode structs.

### wocky_node_deinit ()

    void                wocky_node_deinit                   (void);

Releases all the resources used by the WockyNode caches.