WockyNode

WockyNode — representation of a XMPP node

Synopsis

#include <wocky/wocky-node.h>

struct              WockyNode;
enum                WockyNodeBuildTag;
                    WockyNodeIter;
void                wocky_node_add_build                (WockyNode *node,
                                                         ...);
void                wocky_node_add_build_va             (WockyNode *node,
                                                         va_list va);
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);
void                wocky_node_add_node_tree            (WockyNode *node,
                                                         WockyNodeTree *tree);
void                wocky_node_append_content           (WockyNode *node,
                                                         const gchar *content);
void                wocky_node_append_content_n         (WockyNode *node,
                                                         const gchar *content,
                                                         gsize size);
const gchar *       wocky_node_attribute_ns_get_prefix_from_quark
                                                        (GQuark ns);
const gchar *       wocky_node_attribute_ns_get_prefix_from_urn
                                                        (const gchar *urn);
void                wocky_node_attribute_ns_set_prefix  (GQuark ns,
                                                         const gchar *prefix);
void                wocky_node_deinit                   (void);
gboolean            (*wocky_node_each_attr_func)        (const gchar *key,
                                                         const gchar *value,
                                                         const gchar *pref,
                                                         const gchar *ns,
                                                         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);
gboolean            (*wocky_node_each_child_func)       (WockyNode *node,
                                                         gpointer user_data);
gboolean            wocky_node_equal                    (WockyNode *node0,
                                                         WockyNode *node1);
void                wocky_node_free                     (WockyNode *node);
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);
WockyNode *         wocky_node_get_child                (WockyNode *node,
                                                         const gchar *name);
WockyNode *         wocky_node_get_child_ns             (WockyNode *node,
                                                         const gchar *name,
                                                         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_get_first_child          (WockyNode *node);
WockyNode *         wocky_node_get_first_child_ns       (WockyNode *node,
                                                         const gchar *ns);
const gchar *       wocky_node_get_language             (WockyNode *node);
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);
void                wocky_node_init                     (void);
gboolean            wocky_node_is_superset              (WockyNode *node,
                                                         WockyNode *subset);
void                wocky_node_iter_init                (WockyNodeIter *iter,
                                                         WockyNode *node,
                                                         const gchar *name,
                                                         const gchar *ns);
gboolean            wocky_node_iter_next                (WockyNodeIter *iter,
                                                         WockyNode **next);
WockyNode *         wocky_node_new                      (const char *name,
                                                         const gchar *ns);
void                wocky_node_prepend_node_tree        (WockyNode *node,
                                                         WockyNodeTree *tree);
void                wocky_node_set_attribute            (WockyNode *node,
                                                         const gchar *key,
                                                         const gchar *value);
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);
void                wocky_node_set_attribute_ns         (WockyNode *node,
                                                         const gchar *key,
                                                         const gchar *value,
                                                         const gchar *ns);
void                wocky_node_set_attributes           (WockyNode *node,
                                                         const gchar *key,
                                                         ...);
void                wocky_node_set_content              (WockyNode *node,
                                                         const gchar *content);
void                wocky_node_set_language             (WockyNode *node,
                                                         const gchar *lang);
void                wocky_node_set_language_n           (WockyNode *node,
                                                         const gchar *lang,
                                                         gsize lang_size);
gchar *             wocky_node_to_string                (WockyNode *node);

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

struct WockyNode

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

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

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 = '*',
  WOCKY_NODE_LANGUAGE = '#'
} 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
`WOCKY_NODE_LANGUAGE`

WockyNodeIter

typedef struct {
} WockyNodeIter;

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

wocky_node_add_build ()

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

Add a node subtree to an existing parent node.

Example 1.

wocky_node_add_build (node,
   '(', "body",
       '$', "Telepathy rocks!",
   ')',
  NULL);

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
`Varargs` :	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);

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_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_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_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_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_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_deinit ()

void                wocky_node_deinit                   (void);

Releases all the resources used by the WockyNode caches.

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_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_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_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_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_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_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_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_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_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_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);

wocky_node_has_ns_q ()

gboolean            wocky_node_has_ns_q                 (WockyNode *node,
                                                         GQuark ns);

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_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`.

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

WockyNodeIter iter;
WockyNode *child;

wocky_node_iter_init (&iter, wocky_stanza_get_top_node (stanza),
   "payload-type",
   WOCKY_XMPP_NS_JINGLE_RTP);
while (wocky_node_iter_next (iter, &child))
  {
    /* do something with the child */
  }

`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_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_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_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_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_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_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
`Varargs` :	pairs of keys and values, terminated by `NULL`

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_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_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 Reference Manual
Top \| Description