WockyNode

WockyNode — representation of a XMPP node

Functions

gboolean (*wocky_node_each_attr_func) ()
gboolean (*wocky_node_each_child_func) ()
void wocky_node_each_attribute ()
void wocky_node_each_child ()
const gchar * wocky_node_get_attribute ()
const gchar * wocky_node_get_attribute_ns ()
void wocky_node_set_attribute ()
void wocky_node_set_attributes ()
void wocky_node_set_attribute_ns ()
void wocky_node_set_attribute_n ()
void wocky_node_set_attribute_n_ns ()
const gchar * wocky_node_attribute_ns_get_prefix_from_urn ()
const gchar * wocky_node_attribute_ns_get_prefix_from_quark ()
void wocky_node_attribute_ns_set_prefix ()
WockyNode * wocky_node_get_child ()
WockyNode * wocky_node_get_child_ns ()
WockyNode * wocky_node_get_first_child ()
WockyNode * wocky_node_get_first_child_ns ()
const gchar * wocky_node_get_content_from_child ()
const gchar * wocky_node_get_content_from_child_ns ()
WockyNode * wocky_node_add_child ()
WockyNode * wocky_node_add_child_ns ()
WockyNode * wocky_node_add_child_ns_q ()
WockyNode * wocky_node_add_child_with_content ()
WockyNode * wocky_node_add_child_with_content_ns ()
WockyNode * wocky_node_add_child_with_content_ns_q ()
const gchar * wocky_node_get_ns ()
gboolean wocky_node_has_ns ()
gboolean wocky_node_has_ns_q ()
gboolean wocky_node_matches_q ()
gboolean wocky_node_matches ()
const gchar * wocky_node_get_language ()
void wocky_node_set_language ()
void wocky_node_set_language_n ()
void wocky_node_set_content ()
void wocky_node_append_content ()
void wocky_node_append_content_n ()
gchar * wocky_node_to_string ()
WockyNode * wocky_node_new ()
void wocky_node_free ()
gboolean wocky_node_equal ()
gboolean wocky_node_is_superset ()
void wocky_node_iter_init ()
gboolean wocky_node_iter_next ()
void wocky_node_iter_remove ()
void wocky_node_add_build ()
void wocky_node_add_build_va ()
WockyNode * wocky_node_add_node_tree ()
WockyNode * wocky_node_prepend_node_tree ()
void wocky_node_init ()
void wocky_node_deinit ()

Types and Values

Includes

#include <wocky/wocky-node.h>

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.

Functions

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

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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

Parameters

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.

Parameters

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

Parameters

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

Parameters

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

Parameters

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_matches_q ()

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

Checks whether a node has a particular name and namespace.

Parameters

node

a WockyNode

 

name

the expected element name, which may not be NULL

 

ns

the expected element namespace, which may not be 0

 

Returns

TRUE if node is named name , in namespace ns .


wocky_node_matches ()

gboolean
wocky_node_matches (WockyNode *node,
                    const gchar *name,
                    const gchar *ns);

Checks whether a node has a particular name and namespace.

Parameters

node

a WockyNode

 

name

the expected element name, which may not be NULL

 

ns

the expected element namespace, which may not be NULL

 

Returns

TRUE if node is named name , in namespace ns .


wocky_node_get_language ()

const gchar *
wocky_node_get_language (WockyNode *node);

Gets the language of a WockyNode

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

node

a WockyNode.

 

wocky_node_equal ()

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

Compares two WockyNodes for equality.

Parameters

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

Parameters

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 *<!-- -->/
  }

Parameters

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

Parameters

iter

an initialized WockyNodeIter

 

next

a location to store the next child

 

Returns

FALSE if the last child has been reached


wocky_node_iter_remove ()

void
wocky_node_iter_remove (WockyNodeIter *iter);

Removes and frees the node returned by the last call to wocky_node_iter_next() from its parent. Can only be called after wocky_node_iter_next() returned TRUE, and cannot be called more than once per successful call to wocky_node_iter_next().

Parameters

iter

an initialized WockyNodeIter

 

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>

Parameters

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

wocky_node_add_node_tree ()

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

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

Parameters

node

A node

 

tree

The node tree to add

 

Returns

the root of the copy of tree added to node .


wocky_node_prepend_node_tree ()

WockyNode *
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.

Parameters

node

a node

 

tree

the node tree to prepend to node 's children

 

Returns

the root of the copy of tree added to node .


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.

Types and Values

enum WockyNodeBuildTag

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

Members

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

xml:lang of a node

 

struct WockyNode

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

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

Members

gchar *name;

name of the node

 

gchar *content;

content of the node

 

WockyNodeIter

typedef struct {
} WockyNodeIter;

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