WockyXmppNode

WockyXmppNode — representation of a XMPP node

Synopsis

#include <wocky/wocky-xmpp-node.h>

                    WockyXmppNode;
gboolean            (*wocky_xmpp_node_each_attr_func)   (const gchar *key,
                                                         const gchar *value,
                                                         const gchar *pref,
                                                         const gchar *ns,
                                                         gpointer user_data);
void                wocky_xmpp_node_each_attribute      (WockyXmppNode *node,
                                                         wocky_xmpp_node_each_attr_func func,
                                                         gpointer user_data);
gboolean            (*wocky_xmpp_node_each_child_func)  (WockyXmppNode *node,
                                                         gpointer user_data);
void                wocky_xmpp_node_each_child          (WockyXmppNode *node,
                                                         wocky_xmpp_node_each_child_func func,
                                                         gpointer user_data);
const gchar *       wocky_xmpp_node_get_attribute       (WockyXmppNode *node,
                                                         const gchar *key);
const gchar *       wocky_xmpp_node_get_attribute_ns    (WockyXmppNode *node,
                                                         const gchar *key,
                                                         const gchar *ns);
void                wocky_xmpp_node_set_attribute       (WockyXmppNode *node,
                                                         const gchar *key,
                                                         const gchar *value);
void                wocky_xmpp_node_set_attribute_ns    (WockyXmppNode *node,
                                                         const gchar *key,
                                                         const gchar *value,
                                                         const gchar *ns);
void                wocky_xmpp_node_set_attribute_n     (WockyXmppNode *node,
                                                         const gchar *key,
                                                         const gchar *value,
                                                         gsize value_size);
void                wocky_xmpp_node_set_attribute_n_ns  (WockyXmppNode *node,
                                                         const gchar *key,
                                                         const gchar *value,
                                                         gsize value_size,
                                                         const gchar *ns);
const gchar *       wocky_xmpp_node_attribute_ns_get_prefix_from_urn
                                                        (const gchar *urn);
const gchar *       wocky_xmpp_node_attribute_ns_get_prefix_from_quark
                                                        (GQuark ns);
void                wocky_xmpp_node_attribute_ns_set_prefix
                                                        (GQuark ns,
                                                         const gchar *prefix);
WockyXmppNode *     wocky_xmpp_node_get_child           (WockyXmppNode *node,
                                                         const gchar *name);
WockyXmppNode *     wocky_xmpp_node_get_child_ns        (WockyXmppNode *node,
                                                         const gchar *name,
                                                         const gchar *ns);
WockyXmppNode *     wocky_xmpp_node_get_first_child     (WockyXmppNode *node);
const gchar *       wocky_xmpp_node_get_content_from_child
                                                        (WockyXmppNode *node,
                                                         const gchar *name);
const gchar *       wocky_xmpp_node_get_content_from_child_ns
                                                        (WockyXmppNode *node,
                                                         const gchar *name,
                                                         const gchar *ns);
WockyXmppNode *     wocky_xmpp_node_add_child           (WockyXmppNode *node,
                                                         const gchar *name);
WockyXmppNode *     wocky_xmpp_node_add_child_ns        (WockyXmppNode *node,
                                                         const gchar *name,
                                                         const gchar *ns);
WockyXmppNode *     wocky_xmpp_node_add_child_with_content
                                                        (WockyXmppNode *node,
                                                         const gchar *name,
                                                         const char *content);
WockyXmppNode *     wocky_xmpp_node_add_child_with_content_ns
                                                        (WockyXmppNode *node,
                                                         const gchar *name,
                                                         const gchar *content,
                                                         const gchar *ns);
void                wocky_xmpp_node_set_ns              (WockyXmppNode *node,
                                                         const gchar *ns);
void                wocky_xmpp_node_set_ns_q            (WockyXmppNode *node,
                                                         GQuark ns);
const gchar *       wocky_xmpp_node_get_ns              (WockyXmppNode *node);
gboolean            wocky_xmpp_node_has_ns              (WockyXmppNode *node,
                                                         const gchar *ns);
gboolean            wocky_xmpp_node_has_ns_q            (WockyXmppNode *node,
                                                         GQuark ns);
const gchar *       wocky_xmpp_node_get_language        (WockyXmppNode *node);
void                wocky_xmpp_node_set_language        (WockyXmppNode *node,
                                                         const gchar *lang);
void                wocky_xmpp_node_set_language_n      (WockyXmppNode *node,
                                                         const gchar *lang,
                                                         gsize lang_size);
void                wocky_xmpp_node_set_content         (WockyXmppNode *node,
                                                         const gchar *content);
void                wocky_xmpp_node_append_content      (WockyXmppNode *node,
                                                         const gchar *content);
void                wocky_xmpp_node_append_content_n    (WockyXmppNode *node,
                                                         const gchar *content,
                                                         gsize size);
gchar *             wocky_xmpp_node_to_string           (WockyXmppNode *node);
WockyXmppNode *     wocky_xmpp_node_new                 (const char *name);
void                wocky_xmpp_node_free                (WockyXmppNode *node);
gboolean            wocky_xmpp_node_equal               (WockyXmppNode *node0,
                                                         WockyXmppNode *node1);
gboolean            wocky_xmpp_node_is_superset         (WockyXmppNode *node,
                                                         WockyXmppNode *subset);
void                wocky_xmpp_node_init                (void);
void                wocky_xmpp_node_deinit              (void);
                    WockyXmppNodeIter;
void                wocky_xmpp_node_iter_init           (WockyXmppNodeIter *iter,
                                                         WockyXmppNode *node,
                                                         const gchar *name,
                                                         const gchar *ns);
gboolean            wocky_xmpp_node_iter_next           (WockyXmppNodeIter *iter,
                                                         WockyXmppNode **next);

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

WockyXmppNode

typedef struct {
  gchar *name;
  gchar *content;

  /* Private */
  gchar *language;
  GQuark ns;
  GSList *attributes;
  GSList *children;
} WockyXmppNode;

wocky_xmpp_node_each_attr_func ()

gboolean            (*wocky_xmpp_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_xmpp_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_xmpp_node_each_attribute()

Returns :

 FALSE to stop further attributes from being examined.

wocky_xmpp_node_each_attribute ()

void                wocky_xmpp_node_each_attribute      (WockyXmppNode *node,
                                                         wocky_xmpp_node_each_attr_func func,
                                                         gpointer user_data);

Calls a function for each attribute of a WockyXmppNode.

node :

 a WockyXmppNode

func :

 the function to be called on each node's attribute

user_data :

 user data to pass to the function

wocky_xmpp_node_each_child_func ()

gboolean            (*wocky_xmpp_node_each_child_func)  (WockyXmppNode *node,
                                                         gpointer user_data);

Specifies the type of functions passed to wocky_xmpp_node_each_child().

node :

 a WockyXmppNode

user_data :

 user data passed to wocky_xmpp_node_each_child()

Returns :

 FALSE to stop further children from being examined.

wocky_xmpp_node_each_child ()

void                wocky_xmpp_node_each_child          (WockyXmppNode *node,
                                                         wocky_xmpp_node_each_child_func func,
                                                         gpointer user_data);

Calls a function for each child of a WockyXmppNode.

node :

 a WockyXmppNode

func :

 the function to be called on each node's child

user_data :

 user data to pass to the function

wocky_xmpp_node_get_attribute ()

const gchar *       wocky_xmpp_node_get_attribute       (WockyXmppNode *node,
                                                         const gchar *key);

Returns the value of an attribute in a WockyXmppNode.

node :

 a WockyXmppNode

key :

 the attribute name

Returns :

 the value of the attribute key, or NULL if node doesn't have such attribute.

wocky_xmpp_node_get_attribute_ns ()

const gchar *       wocky_xmpp_node_get_attribute_ns    (WockyXmppNode *node,
                                                         const gchar *key,
                                                         const gchar *ns);

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

node :

 a WockyXmppNode

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

void                wocky_xmpp_node_set_attribute       (WockyXmppNode *node,
                                                         const gchar *key,
                                                         const gchar *value);

Sets an attribute in a WockyXmppNode to a specific value.

node :

 a WockyXmppNode

key :

 the attribute name to set

value :

 the value to set

wocky_xmpp_node_set_attribute_ns ()

void                wocky_xmpp_node_set_attribute_ns    (WockyXmppNode *node,
                                                         const gchar *key,
                                                         const gchar *value,
                                                         const gchar *ns);

Sets an attribute in a WockyXmppNode, within a specific namespace. If the namespace is NULL, this is equivalent to wocky_xmpp_node_set_attribute().

node :

 a WockyXmppNode

key :

 the attribute name to set

value :

 the value to set

ns :

 a namespace, or NULL

wocky_xmpp_node_set_attribute_n ()

void                wocky_xmpp_node_set_attribute_n     (WockyXmppNode *node,
                                                         const gchar *key,
                                                         const gchar *value,
                                                         gsize value_size);

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

node :

 a WockyXmppNode

key :

 the attribute to set

value :

 the value to set

value_size :

 the number of bytes of value to set as a value

wocky_xmpp_node_set_attribute_n_ns ()

void                wocky_xmpp_node_set_attribute_n_ns  (WockyXmppNode *node,
                                                         const gchar *key,
                                                         const gchar *value,
                                                         gsize value_size,
                                                         const gchar *ns);

Sets a new attribute to a WockyXmppNode, with the supplied values. If the namespace is NULL, this is equivalent to wocky_xmpp_node_set_attribute_n().

node :

 a WockyXmppNode

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

const gchar *       wocky_xmpp_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_xmpp_node_attribute_ns_get_prefix_from_quark ()

const gchar *       wocky_xmpp_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_xmpp_node_attribute_ns_set_prefix ()

void                wocky_xmpp_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_xmpp_node_get_child ()

WockyXmppNode *     wocky_xmpp_node_get_child           (WockyXmppNode *node,
                                                         const gchar *name);

Gets a child of a node, searching by name.

node :

 a WockyXmppNode

name :

 the name of the child to get

Returns :

 a WockyXmppNode.

wocky_xmpp_node_get_child_ns ()

WockyXmppNode *     wocky_xmpp_node_get_child_ns        (WockyXmppNode *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_xmpp_node_get_child()

node :

 a WockyXmppNode

name :

 the name of the child to get

ns :

 the namespace of the child to get, or NULL

Returns :

 a WockyXmppNode.

wocky_xmpp_node_get_first_child ()

WockyXmppNode *     wocky_xmpp_node_get_first_child     (WockyXmppNode *node);

Convenience function to return the first child of a WockyXmppNode.

node :

 a WockyXmppNode

Returns :

 a WockyXmppNode.

wocky_xmpp_node_get_content_from_child ()

const gchar *       wocky_xmpp_node_get_content_from_child
                                                        (WockyXmppNode *node,
                                                         const gchar *name);

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

node :

 a WockyXmppNode

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

const gchar *       wocky_xmpp_node_get_content_from_child_ns
                                                        (WockyXmppNode *node,
                                                         const gchar *name,
                                                         const gchar *ns);

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

node :

 a WockyXmppNode

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

WockyXmppNode *     wocky_xmpp_node_add_child           (WockyXmppNode *node,
                                                         const gchar *name);

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

node :

 a WockyXmppNode

name :

 the name of the child to add

Returns :

 the newly added WockyXmppNode.

wocky_xmpp_node_add_child_ns ()

WockyXmppNode *     wocky_xmpp_node_add_child_ns        (WockyXmppNode *node,
                                                         const gchar *name,
                                                         const gchar *ns);

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

node :

 a WockyXmppNode

name :

 the name of the child to add

ns :

 a namespace

Returns :

 the newly added WockyXmppNode.

wocky_xmpp_node_add_child_with_content ()

WockyXmppNode *     wocky_xmpp_node_add_child_with_content
                                                        (WockyXmppNode *node,
                                                         const gchar *name,
                                                         const char *content);

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

node :

 a WockyXmppNode

name :

 the name of the child to add

content :

 the content of the child to add

Returns :

 the newly added WockyXmppNode.

wocky_xmpp_node_add_child_with_content_ns ()

WockyXmppNode *     wocky_xmpp_node_add_child_with_content_ns
                                                        (WockyXmppNode *node,
                                                         const gchar *name,
                                                         const gchar *content,
                                                         const gchar *ns);

Adds a WockyXmppNode 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_xmpp_node_add_child_with_content().

node :

 a WockyXmppNode

name :

 the name of the child to add

content :

 the content of the child to add

ns :

 a namespace

Returns :

 the newly added WockyXmppNode.

wocky_xmpp_node_set_ns ()

void                wocky_xmpp_node_set_ns              (WockyXmppNode *node,
                                                         const gchar *ns);

Sets the namespace of a WockyXmppNode.

node :

 a WockyXmppNode

ns :

 a namespace

wocky_xmpp_node_set_ns_q ()

void                wocky_xmpp_node_set_ns_q            (WockyXmppNode *node,
                                                         GQuark ns);

node :

ns :

wocky_xmpp_node_get_ns ()

const gchar *       wocky_xmpp_node_get_ns              (WockyXmppNode *node);

Gets the namespace of a WockyXmppNode

node :

 a WockyXmppNode

Returns :

 a string containing the namespace of the node.

wocky_xmpp_node_has_ns ()

gboolean            wocky_xmpp_node_has_ns              (WockyXmppNode *node,
                                                         const gchar *ns);

node :

ns :

Returns :

wocky_xmpp_node_has_ns_q ()

gboolean            wocky_xmpp_node_has_ns_q            (WockyXmppNode *node,
                                                         GQuark ns);

node :

ns :

Returns :

wocky_xmpp_node_get_language ()

const gchar *       wocky_xmpp_node_get_language        (WockyXmppNode *node);

Gets the language of a WockyXmppNode

node :

 a WockyXmppNode

Returns :

 a string containing the language of the node.

wocky_xmpp_node_set_language ()

void                wocky_xmpp_node_set_language        (WockyXmppNode *node,
                                                         const gchar *lang);

Sets the language of a WockyXmppNode.

node :

 a WockyXmppNode

lang :

 a NULL-terminated string containing the language

wocky_xmpp_node_set_language_n ()

void                wocky_xmpp_node_set_language_n      (WockyXmppNode *node,
                                                         const gchar *lang,
                                                         gsize lang_size);

Sets the language of a WockyXmppNode.

node :

 a WockyXmppNode

lang :

 a language

lang_size :

 the length of lang, in bytes.

wocky_xmpp_node_set_content ()

void                wocky_xmpp_node_set_content         (WockyXmppNode *node,
                                                         const gchar *content);

Sets the content of a WockyXmppNode.

node :

 a WockyXmppNode

content :

 the content to set to the node

wocky_xmpp_node_append_content ()

void                wocky_xmpp_node_append_content      (WockyXmppNode *node,
                                                         const gchar *content);

Appends some content to the content of a WockyXmppNode.

node :

 a WockyXmppNode

content :

 the content to append to the node

wocky_xmpp_node_append_content_n ()

void                wocky_xmpp_node_append_content_n    (WockyXmppNode *node,
                                                         const gchar *content,
                                                         gsize size);

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

node :

 a WockyXmppNode

content :

 the content to append to the node

size :

 the size of the content to append

wocky_xmpp_node_to_string ()

gchar *             wocky_xmpp_node_to_string           (WockyXmppNode *node);

Obtains a string representation of a WockyXmppNode.

node :

 a WockyXmppNode

Returns :

 a newly allocated string containing a serialization of the node.

wocky_xmpp_node_new ()

WockyXmppNode *     wocky_xmpp_node_new                 (const char *name);

Convenience function which creates a WockyXmppNode and sets its name to name.

name :

 the node's name

Returns :

 a newly allocated WockyXmppNode.

wocky_xmpp_node_free ()

void                wocky_xmpp_node_free                (WockyXmppNode *node);

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

node :

 a WockyXmppNode.

wocky_xmpp_node_equal ()

gboolean            wocky_xmpp_node_equal               (WockyXmppNode *node0,
                                                         WockyXmppNode *node1);

Compares two WockyXmppNodes for equality.

node0 :

 a WockyXmppNode

node1 :

 a WockyXmppNode to compare to node0

Returns :

 TRUE if the two nodes are equal.

wocky_xmpp_node_is_superset ()

gboolean            wocky_xmpp_node_is_superset         (WockyXmppNode *node,
                                                         WockyXmppNode *subset);

node :

 the WockyXmppNode to test

subset :

Returns :

 TRUE if node is a superset of subset.

wocky_xmpp_node_init ()

void                wocky_xmpp_node_init                (void);

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

wocky_xmpp_node_deinit ()

void                wocky_xmpp_node_deinit              (void);

Releases all the resources used by the WockyXmppNode caches.

WockyXmppNodeIter

typedef struct {
  GSList *pending;
  const gchar *name;
  GQuark ns;
} WockyXmppNodeIter;

wocky_xmpp_node_iter_init ()

void                wocky_xmpp_node_iter_init           (WockyXmppNodeIter *iter,
                                                         WockyXmppNode *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
2
3
4
5
6
7
8
9
10
 
WockyXmppNodeIter iter;
WockyXmppNode *child;

wocky_xmpp_node_iter_init (&iter, stanza->node,
   "payload-type",
   WOCKY_XMPP_NS_JINGLE_RTP);
while (wocky_xmpp_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_xmpp_node_iter_next ()

gboolean            wocky_xmpp_node_iter_next           (WockyXmppNodeIter *iter,
                                                         WockyXmppNode **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 WockyXmppNodeIter

next :

 a location to store the next child

Returns :

 FALSE if the last child has been reached
Generated by GTK-Doc V1.13