Strophe  0.8
XMPP client library
Functions
Stanza creation and manipulation

Functions

xmpp_stanza_t * xmpp_stanza_new (xmpp_ctx_t *ctx)
 Create a stanza object.
xmpp_stanza_t * xmpp_stanza_clone (xmpp_stanza_t *const stanza)
 Clone a stanza object.
xmpp_stanza_t * xmpp_stanza_copy (const xmpp_stanza_t *const stanza)
 Copy a stanza and its children.
int xmpp_stanza_release (xmpp_stanza_t *const stanza)
 Release a stanza object and all of its children.
int xmpp_stanza_is_text (xmpp_stanza_t *const stanza)
 Determine if a stanza is a text node.
int xmpp_stanza_is_tag (xmpp_stanza_t *const stanza)
 Determine if a stanza is a tag node.
int xmpp_stanza_to_text (xmpp_stanza_t *stanza, char **const buf, size_t *const buflen)
 Render a stanza object to text.
int xmpp_stanza_set_name (xmpp_stanza_t *stanza, const char *const name)
 Set the name of a stanza.
char * xmpp_stanza_get_name (xmpp_stanza_t *const stanza)
 Get the stanza name.
int xmpp_stanza_get_attribute_count (xmpp_stanza_t *const stanza)
 Count the attributes in a stanza object.
int xmpp_stanza_get_attributes (xmpp_stanza_t *const stanza, const char **attr, int attrlen)
 Get all attributes for a stanza object.
int xmpp_stanza_set_attribute (xmpp_stanza_t *const stanza, const char *const key, const char *const value)
 Set an attribute for a stanza object.
int xmpp_stanza_set_ns (xmpp_stanza_t *const stanza, const char *const ns)
 Set the stanza namespace.
int xmpp_stanza_add_child (xmpp_stanza_t *stanza, xmpp_stanza_t *child)
 Add a child stanza to a stanza object.
int xmpp_stanza_set_text (xmpp_stanza_t *stanza, const char *const text)
 Set the text data for a text stanza.
int xmpp_stanza_set_text_with_size (xmpp_stanza_t *stanza, const char *const text, const size_t size)
 Set the text data for a text stanza.
char * xmpp_stanza_get_id (xmpp_stanza_t *const stanza)
 Get the 'id' attribute of the stanza object.
char * xmpp_stanza_get_ns (xmpp_stanza_t *const stanza)
 Get the namespace attribute of the stanza object.
char * xmpp_stanza_get_type (xmpp_stanza_t *const stanza)
 Get the 'type' attribute of the stanza object.
xmpp_stanza_t * xmpp_stanza_get_child_by_name (xmpp_stanza_t *const stanza, const char *const name)
 Get the first child of stanza with name.
xmpp_stanza_t * xmpp_stanza_get_child_by_ns (xmpp_stanza_t *const stanza, const char *const ns)
 Get the first child of a stanza with a given namespace.
xmpp_stanza_t * xmpp_stanza_get_children (xmpp_stanza_t *const stanza)
 Get the list of children.
xmpp_stanza_t * xmpp_stanza_get_next (xmpp_stanza_t *const stanza)
 Get the next sibling of a stanza.
char * xmpp_stanza_get_text (xmpp_stanza_t *const stanza)
 Get the text data for a text stanza.
char * xmpp_stanza_get_text_ptr (xmpp_stanza_t *const stanza)
 Get the text data pointer for a text stanza.
int xmpp_stanza_set_id (xmpp_stanza_t *const stanza, const char *const id)
 Set the 'id' attribute of a stanza.
int xmpp_stanza_set_type (xmpp_stanza_t *const stanza, const char *const type)
 Set the 'type' attribute of a stanza.
char * xmpp_stanza_get_attribute (xmpp_stanza_t *const stanza, const char *const name)
 Get an attribute from a stanza.

Function Documentation

xmpp_stanza_t* xmpp_stanza_new ( xmpp_ctx_t *  ctx)

Create a stanza object.

stanzas

This function allocates and initializes and blank stanza object. The stanza will have a reference count of one, so the caller does not need to clone it.

Parameters:
ctxa Strophe context object
Returns:
a stanza object
xmpp_stanza_t* xmpp_stanza_clone ( xmpp_stanza_t *const  stanza)

Clone a stanza object.

clone a stanza

This function increments the reference count of the stanza object.

Parameters:
stanzaa Strophe stanza object
Returns:
the stanza object with it's reference count incremented
xmpp_stanza_t* xmpp_stanza_copy ( const xmpp_stanza_t *const  stanza)

Copy a stanza and its children.

copies a stanza and all children

This function copies a stanza along with all its children and returns the new stanza and children with a reference count of 1. The returned stanza will have no parent and no siblings. This function is useful for extracting a child stanza for inclusion in another tree.

Parameters:
stanzaa Strophe stanza object
Returns:
a new Strophe stanza object
int xmpp_stanza_release ( xmpp_stanza_t *const  stanza)

Release a stanza object and all of its children.

free a stanza object and it's contents

This function releases a stanza object and potentially all of its children, which may cause the object(s) to be freed.

Parameters:
stanzaa Strophe stanza object
Returns:
TRUE if the object was freed and FALSE otherwise
int xmpp_stanza_is_text ( xmpp_stanza_t *const  stanza)

Determine if a stanza is a text node.

Parameters:
stanzaa Strophe stanza object
Returns:
TRUE if the stanza is a text node, FALSE otherwise
int xmpp_stanza_is_tag ( xmpp_stanza_t *const  stanza)

Determine if a stanza is a tag node.

Parameters:
stanzaa Strophe stanza object
Returns:
TRUE if the stanza is a tag node, FALSE otherwise
int xmpp_stanza_to_text ( xmpp_stanza_t *  stanza,
char **const  buf,
size_t *const  buflen 
)

Render a stanza object to text.

marshall a stanza into text for transmission or display

This function renders a given stanza object, along with its children, to text. The text is returned in an allocated, null-terminated buffer. It starts by allocating a 1024 byte buffer and reallocates more memory if that is not large enough.

Parameters:
stanzaa Strophe stanza object
bufa reference to a string pointer
buflena reference to a size_t
Returns:
0 on success (XMPP_EOK), and a number less than 0 on failure (XMPP_EMEM, XMPP_EINVOP)
int xmpp_stanza_set_name ( xmpp_stanza_t *  stanza,
const char *const  name 
)

Set the name of a stanza.

Parameters:
stanzaa Strophe stanza object
namea string with the name of the stanza
Returns:
XMPP_EOK on success, a number less than 0 on failure (XMPP_EMEM, XMPP_EINVOP)
char* xmpp_stanza_get_name ( xmpp_stanza_t *const  stanza)

Get the stanza name.

This function returns a pointer to the stanza name. If the caller needs to store this data, it must make a copy.

Parameters:
stanzaa Strophe stanza object
Returns:
a string with the stanza name
int xmpp_stanza_get_attribute_count ( xmpp_stanza_t *const  stanza)

Count the attributes in a stanza object.

Parameters:
stanzaa Strophe stanza object
Returns:
the number of attributes for the stanza object
int xmpp_stanza_get_attributes ( xmpp_stanza_t *const  stanza,
const char **  attr,
int  attrlen 
)

Get all attributes for a stanza object.

This function populates the array with attributes from the stanza. The attr array will be in the format: attr[i] = attribute name, attr[i+1] = attribute value.

Parameters:
stanzaa Strophe stanza object
attrthe string array to populate
attrlenthe size of the array
Returns:
the number of slots used in the array, which will be 2 times the number of attributes in the stanza
int xmpp_stanza_set_attribute ( xmpp_stanza_t *const  stanza,
const char *const  key,
const char *const  value 
)

Set an attribute for a stanza object.

Parameters:
stanzaa Strophe stanza object
keya string with the attribute name
valuea string with the attribute value
Returns:
XMPP_EOK (0) on success or a number less than 0 on failure
int xmpp_stanza_set_ns ( xmpp_stanza_t *const  stanza,
const char *const  ns 
)

Set the stanza namespace.

This is a convenience function equivalent to calling: xmpp_stanza_set_attribute(stanza, "xmlns", ns);

Parameters:
stanzaa Strophe stanza object
nsa string with the namespace
Returns:
XMPP_EOK (0) on success or a number less than 0 on failure
int xmpp_stanza_add_child ( xmpp_stanza_t *  stanza,
xmpp_stanza_t *  child 
)

Add a child stanza to a stanza object.

This function clones the child and appends it to the stanza object's children.

Parameters:
stanzaa Strophe stanza object
childthe child stanza object
Returns:
XMPP_EOK (0) on success or a number less than 0 on failure
int xmpp_stanza_set_text ( xmpp_stanza_t *  stanza,
const char *const  text 
)

Set the text data for a text stanza.

This function copies the text given and sets the stanza object's text to it. Attempting to use this function on a stanza that has a name will fail with XMPP_EINVOP. This function takes the text as a null-terminated string.

Parameters:
stanzaa Strophe stanza object
texta string with the text
Returns:
XMPP_EOK (0) on success or a number less than zero on failure
int xmpp_stanza_set_text_with_size ( xmpp_stanza_t *  stanza,
const char *const  text,
const size_t  size 
)

Set the text data for a text stanza.

This function copies the text given and sets teh stanza object's text to it. Attempting to use this function on a stanza that has a name will fail with XMPP_EINVOP. This function takes the text as buffer and a length as opposed to a null-terminated string.

Parameters:
stanzaa Strophe stanza object
texta buffer with the text
sizethe length of the text
Returns:
XMPP_EOK (0) on success and a number less than 0 on failure
char* xmpp_stanza_get_id ( xmpp_stanza_t *const  stanza)

Get the 'id' attribute of the stanza object.

This is a convenience function equivalent to: xmpp_stanza_get_attribute(stanza, "id");

Parameters:
stanzaa Strophe stanza object
Returns:
a string with the 'id' attribute value
char* xmpp_stanza_get_ns ( xmpp_stanza_t *const  stanza)

Get the namespace attribute of the stanza object.

This is a convenience function equivalent to: xmpp_stanza_get_attribute(stanza, "xmlns");

Parameters:
stanzaa Strophe stanza object
Returns:
a string with the 'xmlns' attribute value
char* xmpp_stanza_get_type ( xmpp_stanza_t *const  stanza)

Get the 'type' attribute of the stanza object.

This is a convenience function equivalent to: xmpp_stanza_get_attribute(stanza, "type");

Parameters:
stanzaa Strophe stanza object
Returns:
a string with the 'type' attribute value
xmpp_stanza_t* xmpp_stanza_get_child_by_name ( xmpp_stanza_t *const  stanza,
const char *const  name 
)

Get the first child of stanza with name.

This function searches all the immediate children of stanza for a child stanza that matches the name. The first matching child is returned.

Parameters:
stanzaa Strophe stanza object
namea string with the name to match
Returns:
the matching child stanza object or NULL if no match was found
xmpp_stanza_t* xmpp_stanza_get_child_by_ns ( xmpp_stanza_t *const  stanza,
const char *const  ns 
)

Get the first child of a stanza with a given namespace.

This function searches all the immediate children of a stanza for a child stanza that matches the namespace provided. The first matching child is returned.

Parameters:
stanzaa Strophe stanza object
nsa string with the namespace to match
Returns:
the matching child stanza object or NULL if no match was found
xmpp_stanza_t* xmpp_stanza_get_children ( xmpp_stanza_t *const  stanza)

Get the list of children.

This function returns the first child of the stanza object. The rest of the children can be obtained by calling xmpp_stanza_get_next() to iterate over the siblings.

Parameters:
stanzaa Strophe stanza object
Returns:
the first child stanza or NULL if there are no children
xmpp_stanza_t* xmpp_stanza_get_next ( xmpp_stanza_t *const  stanza)

Get the next sibling of a stanza.

Parameters:
stanzaa Strophe stanza object
Returns:
the next sibling stanza or NULL if there are no more siblings
char* xmpp_stanza_get_text ( xmpp_stanza_t *const  stanza)

Get the text data for a text stanza.

This function copies the text data from a stanza and returns the new allocated string. The caller is responsible for freeing this string with xmpp_free().

Parameters:
stanzaa Strophe stanza object
Returns:
an allocated string with the text data
char* xmpp_stanza_get_text_ptr ( xmpp_stanza_t *const  stanza)

Get the text data pointer for a text stanza.

This function copies returns the raw pointer to the text data in the stanza. This should only be used in very special cases where the caller needs to translate the datatype as this will save a double allocation. The caller should not hold onto this pointer, and is responsible for allocating a copy if it needs one.

Parameters:
stanzaa Strophe stanza object
Returns:
an string pointer to the data or NULL
int xmpp_stanza_set_id ( xmpp_stanza_t *const  stanza,
const char *const  id 
)

Set the 'id' attribute of a stanza.

This is a convenience function for: xmpp_stanza_set_attribute(stanza, 'id', id);

Parameters:
stanzaa Strophe stanza object
ida string containing the 'id' value
Returns:
XMPP_EOK (0) on success or a number less than 0 on failure
int xmpp_stanza_set_type ( xmpp_stanza_t *const  stanza,
const char *const  type 
)

Set the 'type' attribute of a stanza.

This is a convenience function for: xmpp_stanza_set_attribute(stanza, 'type', type);

Parameters:
stanzaa Strophe stanza object
typea string containing the 'type' value
Returns:
XMPP_EOK (0) on success or a number less than 0 on failure
char* xmpp_stanza_get_attribute ( xmpp_stanza_t *const  stanza,
const char *const  name 
)

Get an attribute from a stanza.

This function returns a pointer to the attribute value. If the caller wishes to save this value it must make its own copy.

Parameters:
stanzaa Strophe stanza object
namea string containing attribute name
Returns:
a string with the attribute value or NULL on an error