devs/libstrophe-gh
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Most public API points are now documented.

Browse Source
This commit is contained in:
Jack Moffitt
2008-06-24 14:43:54 +00:00
parent b6027cfd7f
commit 65a174ee7e
22 changed files with 1256 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

302
src/stanza.c
View File

@@ -12,6 +12,13 @@
** distribution.
*/
/** @file
* XMPP stanza creation and manipulation.
*/
/** @defgroup Stanza Stanza creation and manipulation
*/
#include <stdio.h>
#include <string.h>
@@ -23,7 +30,17 @@
#define inline __inline
#endif
/* allocate an initialize a blank stanza */
/** Create a stanza object.
* 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.
*
* @param ctx a Strophe context object
*
* @return a stanza object
*
* @ingroup Stanza
*/
xmpp_stanza_t *xmpp_stanza_new(xmpp_ctx_t *ctx)
{
xmpp_stanza_t *stanza;
@@ -44,7 +61,16 @@ xmpp_stanza_t *xmpp_stanza_new(xmpp_ctx_t *ctx)
return stanza;
}
/* clone a stanza */
/** Clone a stanza object.
* This function increments the reference count of the stanza and all its
* children.
*
* @param stanza a Strophe stanza object
*
* @return the stanza object with it's reference count incremented
*
* @ingroup Stanza
*/
xmpp_stanza_t *xmpp_stanza_clone(xmpp_stanza_t * const stanza)
{
xmpp_stanza_t *child;
@@ -58,11 +84,18 @@ xmpp_stanza_t *xmpp_stanza_clone(xmpp_stanza_t * const stanza)
return stanza;
}
/* copies and stanza and all children
* this function returns a new stanza copied from stanza. the new
* stanza will have no parent and no siblings. the caller is given
* a reference to this new stanza. this function is used to extract
* a child from one stanza for inclusion in another. */
/** Copy a stanza and its 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.
*
* @param stanza a Strophe stanza object
*
* @return a new Strophe stanza object
*
* @ingroup Stanza
*/
xmpp_stanza_t *xmpp_stanza_copy(const xmpp_stanza_t * const stanza)
{
xmpp_stanza_t *copy, *child, *copychild, *tail;
@@ -118,7 +151,16 @@ copy_error:
return NULL;
}
/* free a stanza object and it's contents */
/** Release a stanza object and all of its children.
* This function releases a stanza object and all of its children, which may
* cause the object to be freed.
*
* @param stanza a Strophe stanza object
*
* @return TRUE if the object was freed and FALSE otherwise
*
* @ingroup Stanza
*/
int xmpp_stanza_release(xmpp_stanza_t * const stanza)
{
int released = 0;
@@ -240,12 +282,20 @@ static int _render_stanza_recursive(xmpp_stanza_t *stanza,
return written;
}
/* render a stanza to text
* a buffer is allocated big enough to hold the stanza
* and *buf = buffer. the size of buffer filled with data
* is returned in *buflen (does not include trailing \0).
* the returned buffer contains a trailing \0 so the result is
* a valid string.
/** Render a stanza object to text.
* 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.
*
* @param stanza a Strophe stanza object
* @param buf a reference to a string pointer
* @param buflen a reference to a size_t
*
* @return 0 on success (XMPP_EOK), and a number less than 0 on failure
* (XMPP_EMEM, XMPP_EINVOP)
*
* @ingroup Stanza
*/
int xmpp_stanza_to_text(xmpp_stanza_t *stanza,
char ** const buf,
@@ -290,6 +340,16 @@ int xmpp_stanza_to_text(xmpp_stanza_t *stanza,
return XMPP_EOK;
}
/** Set the name of a stanza.
*
* @param stanza a Strophe stanza object
* @param name a string with the name of the stanza
*
* @return XMPP_EOK on success, a number less than 0 on failure (XMPP_EMEM,
* XMPP_EINVOP)
*
* @ingroup Stanza
*/
int xmpp_stanza_set_name(xmpp_stanza_t *stanza,
const char * const name)
{
@@ -303,14 +363,37 @@ int xmpp_stanza_set_name(xmpp_stanza_t *stanza,
return XMPP_EOK;
}
/** 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.
*
* @param stanza a Strophe stanza object
*
* @return a string with the stanza name
*
* @ingroup Stanza
*/
char *xmpp_stanza_get_name(xmpp_stanza_t * const stanza)
{
if (stanza->type == XMPP_STANZA_TEXT) return NULL;
return stanza->data;
}
/* convinience function to copy attributes from the xml parser
* callback into a stanza. this replaces all previous attributes */
/** Set or replace attributes on a stanza.
* This function replaces all previous attributes (if any) with the
* attributes given. It is used primarily by the XML parser during
* stanza creation. All strings in the array are copied before placing them
* inside the stanza object.
*
* @param stanza a Strophe stanza object
* @param attr an array of strings with the attributes in the following
* format: attr[i] = attribute name, attr[i+1] = attribute value
*
* @return XMPP_EOK on success, a number less than 0 on failure (XMPP_EMEM,
* XMPP_EINVOP)
*
* @ingroup Stanza
*/
int xmpp_stanza_set_attributes(xmpp_stanza_t * const stanza,
const char * const * const attr)
{
@@ -335,6 +418,14 @@ int xmpp_stanza_set_attributes(xmpp_stanza_t * const stanza,
return XMPP_EOK;
}
/** Count the attributes in a stanza object.
*
* @param stanza a Strophe stanza object
*
* @return the number of attributes for the stanza object
*
* @ingroup Stanza
*/
int xmpp_stanza_get_attribute_count(xmpp_stanza_t * const stanza)
{
if (stanza->attributes == NULL) {
@@ -344,6 +435,20 @@ int xmpp_stanza_get_attribute_count(xmpp_stanza_t * const stanza)
return hash_num_keys(stanza->attributes);
}
/** 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.
*
* @param stanza a Strophe stanza object
* @param attr the string array to populate
* @param attrlen the size of the array
*
* @return the number of slots used in the array, which will be 2 times the
* number of attributes in the stanza
*
* @ingroup Stanza
*/
int xmpp_stanza_get_attributes(xmpp_stanza_t * const stanza,
const char **attr, int attrlen)
{
@@ -375,7 +480,16 @@ int xmpp_stanza_get_attributes(xmpp_stanza_t * const stanza,
return num;
}
/** Set an attribute for a stanza object.
*
* @param stanza a Strophe stanza object
* @param key a string with the attribute name
* @param value a string with the attribute value
*
* @return XMPP_EOK (0) on success or a number less than 0 on failure
*
* @ingroup Stanza
*/
int xmpp_stanza_set_attribute(xmpp_stanza_t * const stanza,
const char * const key,
const char * const value)
@@ -397,12 +511,34 @@ int xmpp_stanza_set_attribute(xmpp_stanza_t * const stanza,
return XMPP_EOK;
}
/** Set the stanza namespace.
* This is a convenience function equivalent to calling:
* xmpp_stanza_set_attribute(stanza, "xmlns", ns);
*
* @param stanza a Strophe stanza object
* @param ns a string with the namespace
*
* @return XMPP_EOK (0) on success or a number less than 0 on failure
*
* @ingroup Stanza
*/
int xmpp_stanza_set_ns(xmpp_stanza_t * const stanza,
const char * const ns)
{
return xmpp_stanza_set_attribute(stanza, "xmlns", ns);
}
/** Add a child stanza to a stanza object.
* This function clones the child and appends it to the stanza object's
* children.
*
* @param stanza a Strophe stanza object
* @param child the child stanza object
*
* @return XMPP_EOK (0) on success or a number less than 0 on failure
*
* @ingroup Stanza
*/
int xmpp_stanza_add_child(xmpp_stanza_t *stanza, xmpp_stanza_t *child)
{
xmpp_stanza_t *s;
@@ -424,6 +560,19 @@ int xmpp_stanza_add_child(xmpp_stanza_t *stanza, xmpp_stanza_t *child)
return XMPP_EOK;
}
/** 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.
*
* @param stanza a Strophe stanza object
* @param text a string with the text
*
* @return XMPP_EOK (0) on success or a number less than zero on failure
*
* @ingroup Stanza
*/
int xmpp_stanza_set_text(xmpp_stanza_t *stanza,
const char * const text)
{
@@ -437,6 +586,20 @@ int xmpp_stanza_set_text(xmpp_stanza_t *stanza,
return XMPP_EOK;
}
/** 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.
*
* @param stanza a Strophe stanza object
* @param text a buffer with the text
* @param size the length of the text
*
* @return XMPP_EOK (0) on success and a number less than 0 on failure
*
* @ingroup Stanza
*/
int xmpp_stanza_set_text_with_size(xmpp_stanza_t *stanza,
const char * const text,
const size_t size)
@@ -455,6 +618,16 @@ int xmpp_stanza_set_text_with_size(xmpp_stanza_t *stanza,
return XMPP_EOK;
}
/** Get the 'id' attribute of the stanza object.
* This is a convenience function equivalent to:
* xmpp_stanza_get_attribute(stanza, "id");
*
* @param stanza a Strophe stanza object
*
* @return a string with the 'id' attribute value
*
* @ingroup Stanza
*/
char *xmpp_stanza_get_id(xmpp_stanza_t * const stanza)
{
if (stanza->type != XMPP_STANZA_TAG)
@@ -466,6 +639,16 @@ char *xmpp_stanza_get_id(xmpp_stanza_t * const stanza)
return (char *)hash_get(stanza->attributes, "id");
}
/** Get the namespace attribute of the stanza object.
* This is a convenience function equivalent to:
* xmpp_stanza_get_attribute(stanza, "xmlns");
*
* @param stanza a Strophe stanza object
*
* @return a string with the 'xmlns' attribute value
*
* @ingroup Stanza
*/
char *xmpp_stanza_get_ns(xmpp_stanza_t * const stanza)
{
if (stanza->type != XMPP_STANZA_TAG)
@@ -477,6 +660,16 @@ char *xmpp_stanza_get_ns(xmpp_stanza_t * const stanza)
return (char *)hash_get(stanza->attributes, "xmlns");
}
/** Get the 'type' attribute of the stanza object.
* This is a convenience function equivalent to:
* xmpp_stanza_get_attribute(stanza, "type");
*
* @param stanza a Strophe stanza object
*
* @return a string with the 'type' attribute value
*
* @ingroup Stanza
*/
char *xmpp_stanza_get_type(xmpp_stanza_t * const stanza)
{
if (stanza->type != XMPP_STANZA_TAG)
@@ -488,6 +681,17 @@ char *xmpp_stanza_get_type(xmpp_stanza_t * const stanza)
return (char *)hash_get(stanza->attributes, "type");
}
/** 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.
*
* @param stanza a Strophe stanza object
* @param name a string with the name to match
*
* @return the matching child stanza object or NULL if no match was found
*
* @ingroup Stanza
*/
xmpp_stanza_t *xmpp_stanza_get_child_by_name(xmpp_stanza_t * const stanza,
const char * const name)
{
@@ -502,16 +706,46 @@ xmpp_stanza_t *xmpp_stanza_get_child_by_name(xmpp_stanza_t * const stanza,
return child;
}
/** 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.
*
* @param stanza a Strophe stanza object
*
* @return the first child stanza or NULL if there are no children
*
* @ingroup Stanza
*/
xmpp_stanza_t *xmpp_stanza_get_children(xmpp_stanza_t * const stanza)
{
return stanza->children;
}
/** Get the next sibling of a stanza.
*
* @param stanza a Strophe stanza object
*
* @return the next sibling stanza or NULL if there are no more siblings
*
* @ingroup Stanza
*/
xmpp_stanza_t *xmpp_stanza_get_next(xmpp_stanza_t * const stanza)
{
return stanza->next;
}
/** 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().
*
* @param stanza a Strophe stanza object
*
* @return an allocated string with the text data
*
* @ingroup Stanza
*/
char *xmpp_stanza_get_text(xmpp_stanza_t * const stanza)
{
size_t len, clen;
@@ -539,18 +773,52 @@ char *xmpp_stanza_get_text(xmpp_stanza_t * const stanza)
return text;
}
/** Set the 'id' attribute of a stanza.
*
* This is a convenience function for:
* xmpp_stanza_set_attribute(stanza, 'id', id);
*
* @param stanza a Strophe stanza object
* @param id a string containing the 'id' value
*
* @return XMPP_EOK (0) on success or a number less than 0 on failure
*
* @ingroup Stanza
*/
int xmpp_stanza_set_id(xmpp_stanza_t * const stanza,
const char * const id)
{
return xmpp_stanza_set_attribute(stanza, "id", id);
}
/** Set the 'type' attribute of a stanza.
* This is a convenience function for:
* xmpp_stanza_set_attribute(stanza, 'type', type);
*
* @param stanza a Strophe stanza object
* @param type a string containing the 'type' value
*
* @return XMPP_EOK (0) on success or a number less than 0 on failure
*
* @ingroup Stanza
*/
int xmpp_stanza_set_type(xmpp_stanza_t * const stanza,
const char * const type)
{
return xmpp_stanza_set_attribute(stanza, "type", type);
}
/** 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.
*
* @param stanza a Strophe stanza object
* @param name a string containing attribute name
*
* @return a string with the attribute value or NULL on an error
*
* @ingroup Stanza
*/
char *xmpp_stanza_get_attribute(xmpp_stanza_t * const stanza,
const char * const name)
{