Functions
xmpp_stanza_t *	xmpp_stanza_new (xmpp_ctx_t *ctx)
	Create a stanza object. More...

xmpp_stanza_t *	xmpp_stanza_clone (xmpp_stanza_t *const stanza)
	Clone a stanza object. More...

xmpp_stanza_t *	xmpp_stanza_copy (const xmpp_stanza_t *const stanza)
	Copy a stanza and its children. More...

int	xmpp_stanza_release (xmpp_stanza_t *const stanza)
	Release a stanza object and all of its children. More...

int	xmpp_stanza_is_text (xmpp_stanza_t *const stanza)
	Determine if a stanza is a text node. More...

int	xmpp_stanza_is_tag (xmpp_stanza_t *const stanza)
	Determine if a stanza is a tag node. More...

int	xmpp_stanza_to_text (xmpp_stanza_t stanza, char const buf, size_t const buflen)
	Render a stanza object to text. More...

int	xmpp_stanza_set_name (xmpp_stanza_t stanza, const char const name)
	Set the name of a stanza. More...

const char *	xmpp_stanza_get_name (xmpp_stanza_t *const stanza)
	Get the stanza name. More...

int	xmpp_stanza_get_attribute_count (xmpp_stanza_t *const stanza)
	Count the attributes in a stanza object. More...

int	xmpp_stanza_get_attributes (xmpp_stanza_t const stanza, const char *attr, int attrlen)
	Get all attributes for a stanza object. More...

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. More...

int	xmpp_stanza_set_ns (xmpp_stanza_t const stanza, const char const ns)
	Set the stanza namespace. More...

int	xmpp_stanza_add_child (xmpp_stanza_t stanza, xmpp_stanza_t child)
	Add a child stanza to a stanza object. More...

int	xmpp_stanza_set_text (xmpp_stanza_t stanza, const char const text)
	Set the text data for a text stanza. More...

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. More...

const char *	xmpp_stanza_get_id (xmpp_stanza_t *const stanza)
	Get the 'id' attribute of the stanza object. More...

const char *	xmpp_stanza_get_ns (xmpp_stanza_t *const stanza)
	Get the namespace attribute of the stanza object. More...

const char *	xmpp_stanza_get_type (xmpp_stanza_t *const stanza)
	Get the 'type' attribute of the stanza object. More...

const char *	xmpp_stanza_get_to (xmpp_stanza_t *const stanza)
	Get the 'to' attribute of the stanza object. More...

const char *	xmpp_stanza_get_from (xmpp_stanza_t *const stanza)
	Get the 'from' attribute of the stanza object. More...

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. More...

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. More...

xmpp_stanza_t *	xmpp_stanza_get_children (xmpp_stanza_t *const stanza)
	Get the list of children. More...

xmpp_stanza_t *	xmpp_stanza_get_next (xmpp_stanza_t *const stanza)
	Get the next sibling of a stanza. More...

char *	xmpp_stanza_get_text (xmpp_stanza_t *const stanza)
	Get the text data for a text stanza. More...

const char *	xmpp_stanza_get_text_ptr (xmpp_stanza_t *const stanza)
	Get the text data pointer for a text stanza. More...

int	xmpp_stanza_set_id (xmpp_stanza_t const stanza, const char const id)
	Set the 'id' attribute of a stanza. More...

int	xmpp_stanza_set_type (xmpp_stanza_t const stanza, const char const type)
	Set the 'type' attribute of a stanza. More...

int	xmpp_stanza_set_to (xmpp_stanza_t const stanza, const char const to)
	Set the 'to' attribute of a stanza. More...

int	xmpp_stanza_set_from (xmpp_stanza_t const stanza, const char const from)
	Set the 'from' attribute of a stanza. More...

const char *	xmpp_stanza_get_attribute (xmpp_stanza_t const stanza, const char const name)
	Get an attribute from a stanza. More...

int	xmpp_stanza_del_attribute (xmpp_stanza_t const stanza, const char const name)
	Delete an attribute from a stanza. More...

xmpp_stanza_t *	xmpp_stanza_reply (xmpp_stanza_t *const stanza)
	Create a stanza object in reply to another. More...

xmpp_stanza_t *	xmpp_message_new (xmpp_ctx_t ctx, const char const type, const char const to, const char const id)
	Create a <message> stanza object with given attributes. More...

char *	xmpp_message_get_body (xmpp_stanza_t *msg)
	Get text from <body> child element. More...

int	xmpp_message_set_body (xmpp_stanza_t msg, const char const text)
	Add <body> child element to a <message> stanza with the given text. More...

xmpp_stanza_t *	xmpp_iq_new (xmpp_ctx_t ctx, const char const type, const char *const id)
	Create an <iq> stanza object with given attributes. More...

xmpp_stanza_t *	xmpp_presence_new (xmpp_ctx_t *ctx)
	Create a <presence> stanza object. More...

xmpp_stanza_t *	xmpp_error_new (xmpp_ctx_t ctx, xmpp_error_type_t const type, const char const text)
	Create an <stream:error/> stanza object with given type and error text. More...

Detailed Description

Function Documentation

◆ xmpp_stanza_new()

xmpp_stanza_t* xmpp_stanza_new ( xmpp_ctx_t * ctx )

Create a stanza object.

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

Parameters

ctx	a Strophe context object

Returns: a stanza object

◆ xmpp_stanza_clone()

xmpp_stanza_t* xmpp_stanza_clone ( xmpp_stanza_t *const stanza )

Clone a stanza object.

This function increments the reference count of the stanza object.

Parameters

stanza a Strophe stanza object

Returns: the stanza object with it's reference count incremented

◆ xmpp_stanza_copy()

xmpp_stanza_t* xmpp_stanza_copy ( const xmpp_stanza_t *const stanza )

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.

Parameters

stanza a Strophe stanza object

Returns: a new Strophe stanza object

◆ xmpp_stanza_release()

int xmpp_stanza_release ( xmpp_stanza_t *const stanza )

Release a stanza object and all of its children.

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

Parameters

stanza a Strophe stanza object

Returns: TRUE if the object was freed and FALSE otherwise

◆ xmpp_stanza_is_text()

int xmpp_stanza_is_text ( xmpp_stanza_t *const stanza )

Determine if a stanza is a text node.

Parameters

stanza a Strophe stanza object

Returns: TRUE if the stanza is a text node, FALSE otherwise

◆ xmpp_stanza_is_tag()

int xmpp_stanza_is_tag ( xmpp_stanza_t *const stanza )

Determine if a stanza is a tag node.

Parameters

stanza a Strophe stanza object

Returns: TRUE if the stanza is a tag node, FALSE otherwise

◆ xmpp_stanza_to_text()

int xmpp_stanza_to_text	(	xmpp_stanza_t *	stanza,
		char **const	buf,
		size_t *const	buflen
	)

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.

Parameters

stanza	a Strophe stanza object
buf	a reference to a string pointer
buflen	a reference to a size_t

Returns: 0 on success (XMPP_EOK), and a number less than 0 on failure (XMPP_EMEM, XMPP_EINVOP)

◆ xmpp_stanza_set_name()

int xmpp_stanza_set_name	(	xmpp_stanza_t *	stanza,
		const char *const	name
	)

Set the name of a stanza.

Parameters

stanza	a Strophe stanza object
name	a string with the name of the stanza

Returns: XMPP_EOK on success, a number less than 0 on failure (XMPP_EMEM, XMPP_EINVOP)

◆ xmpp_stanza_get_name()

const 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

stanza a Strophe stanza object

Returns: a string with the stanza name

◆ xmpp_stanza_get_attribute_count()

int xmpp_stanza_get_attribute_count ( xmpp_stanza_t *const stanza )

Count the attributes in a stanza object.

Parameters

stanza a Strophe stanza object

Returns: the number of attributes for the stanza object

◆ xmpp_stanza_get_attributes()

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

stanza	a Strophe stanza object
attr	the string array to populate
attrlen	the 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

◆ xmpp_stanza_set_attribute()

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

stanza	a Strophe stanza object
key	a string with the attribute name
value	a string with the attribute value

Returns: XMPP_EOK (0) on success or a number less than 0 on failure

◆ xmpp_stanza_set_ns()

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

stanza	a Strophe stanza object
ns	a string with the namespace

Returns: XMPP_EOK (0) on success or a number less than 0 on failure

◆ xmpp_stanza_add_child()

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

stanza	a Strophe stanza object
child	the child stanza object

Returns: XMPP_EOK (0) on success or a number less than 0 on failure

◆ xmpp_stanza_set_text()

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

stanza	a Strophe stanza object
text	a string with the text

Returns: XMPP_EOK (0) on success or a number less than zero on failure

◆ xmpp_stanza_set_text_with_size()

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 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 buffer and a length as opposed to a null-terminated string.

Parameters

stanza	a Strophe stanza object
text	a buffer with the text
size	the length of the text

Returns: XMPP_EOK (0) on success and a number less than 0 on failure

◆ xmpp_stanza_get_id()

const 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

stanza a Strophe stanza object

Returns: a string with the 'id' attribute value

◆ xmpp_stanza_get_ns()

const 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

stanza a Strophe stanza object

Returns: a string with the 'xmlns' attribute value

◆ xmpp_stanza_get_type()

const 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

stanza a Strophe stanza object

Returns: a string with the 'type' attribute value

◆ xmpp_stanza_get_to()

const char* xmpp_stanza_get_to ( xmpp_stanza_t *const stanza )

Get the 'to' attribute of the stanza object.

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

Parameters

stanza a Strophe stanza object

Returns: a string with the 'to' attribute value

◆ xmpp_stanza_get_from()

const char* xmpp_stanza_get_from ( xmpp_stanza_t *const stanza )

Get the 'from' attribute of the stanza object.

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

Parameters

stanza a Strophe stanza object

Returns: a string with the 'from' attribute value

◆ xmpp_stanza_get_child_by_name()

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

stanza	a Strophe stanza object
name	a string with the name to match

Returns: the matching child stanza object or NULL if no match was found

◆ xmpp_stanza_get_child_by_ns()

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

stanza	a Strophe stanza object
ns	a string with the namespace to match

Returns: the matching child stanza object or NULL if no match was found

◆ xmpp_stanza_get_children()

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

stanza a Strophe stanza object

Returns: the first child stanza or NULL if there are no children

◆ xmpp_stanza_get_next()

xmpp_stanza_t* xmpp_stanza_get_next ( xmpp_stanza_t *const stanza )

Get the next sibling of a stanza.

Parameters

stanza a Strophe stanza object

Returns: the next sibling stanza or NULL if there are no more siblings

◆ xmpp_stanza_get_text()

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

stanza a Strophe stanza object

Returns: an allocated string with the text data

◆ xmpp_stanza_get_text_ptr()

const 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

stanza a Strophe stanza object

Returns: an string pointer to the data or NULL

◆ xmpp_stanza_set_id()

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

stanza	a Strophe stanza object
id	a string containing the 'id' value

Returns: XMPP_EOK (0) on success or a number less than 0 on failure

◆ xmpp_stanza_set_type()

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

stanza	a Strophe stanza object
type	a string containing the 'type' value

Returns: XMPP_EOK (0) on success or a number less than 0 on failure

◆ xmpp_stanza_set_to()

int xmpp_stanza_set_to	(	xmpp_stanza_t *const	stanza,
		const char *const	to
	)

Set the 'to' attribute of a stanza.

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

Parameters

stanza	a Strophe stanza object
to	a string containing the 'to' value

Returns: XMPP_EOK (0) on success or a number less than 0 on failure

◆ xmpp_stanza_set_from()

int xmpp_stanza_set_from	(	xmpp_stanza_t *const	stanza,
		const char *const	from
	)

Set the 'from' attribute of a stanza.

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

Parameters

stanza	a Strophe stanza object
from	a string containing the 'from' value

Returns: XMPP_EOK (0) on success or a number less than 0 on failure

◆ xmpp_stanza_get_attribute()

const 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

stanza	a Strophe stanza object
name	a string containing attribute name

Returns: a string with the attribute value or NULL on an error

◆ xmpp_stanza_del_attribute()

int xmpp_stanza_del_attribute	(	xmpp_stanza_t *const	stanza,
		const char *const	name
	)

Delete an attribute from a stanza.

Parameters

stanza	a Strophe stanza object
name	a string containing attribute name

Returns: XMPP_EOK (0) on success or a number less than 0 on failure

◆ xmpp_stanza_reply()

xmpp_stanza_t* xmpp_stanza_reply ( xmpp_stanza_t *const stanza )

Create a stanza object in reply to another.

This function makes a copy of a stanza object with the attribute “to” set its original “from”. The stanza will have a reference count of one, so the caller does not need to clone it.

Parameters

stanza a Strophe stanza object

Returns: a new Strophe stanza object

◆ xmpp_message_new()

xmpp_stanza_t* xmpp_message_new	(	xmpp_ctx_t *	ctx,
		const char *const	type,
		const char *const	to,
		const char *const	id
	)

Create a <message> stanza object with given attributes.

Attributes are optional and may be NULL.

Parameters

ctx	a Strophe context object
type	attribute 'type'
to	attribute 'to'
id	attribute 'id'

Returns: a new Strophe stanza object

◆ xmpp_message_get_body()

char* xmpp_message_get_body ( xmpp_stanza_t * msg )

Get text from <body> child element.

This function returns new allocated string. The caller is responsible for freeing this string with xmpp_free().

Parameters

msg	well formed <message> stanza

Returns: allocated string or NULL on failure (no <body> element or memory allocation error)

◆ xmpp_message_set_body()

int xmpp_message_set_body	(	xmpp_stanza_t *	msg,
		const char *const	text
	)

Add <body> child element to a <message> stanza with the given text.

Parameters

msg	a <message> stanza object without <body> child element.

Returns: 0 on success (XMPP_EOK), and a number less than 0 on failure (XMPP_EMEM, XMPP_EINVOP)

◆ xmpp_iq_new()

xmpp_stanza_t* xmpp_iq_new	(	xmpp_ctx_t *	ctx,
		const char *const	type,
		const char *const	id
	)

Create an <iq> stanza object with given attributes.

Attributes are optional and may be NULL.

Parameters

ctx	a Strophe context object
type	attribute 'type'
id	attribute 'id'

Returns: a new Strophe stanza object

◆ xmpp_presence_new()

xmpp_stanza_t* xmpp_presence_new ( xmpp_ctx_t * ctx )

Create a <presence> stanza object.

Parameters

ctx	a Strophe context object

Returns: a new Strophe stanza object

◆ xmpp_error_new()

xmpp_stanza_t* xmpp_error_new	(	xmpp_ctx_t *	ctx,
		xmpp_error_type_t const	type,
		const char *const	text
	)

Create an <stream:error/> stanza object with given type and error text.

The error text is optional and may be NULL.

Parameters

ctx	a Strophe context object
type	enum of xmpp_error_type_t
text	content of a 'text'

Returns: a new Strophe stanza object

Todo:: Handle errors in this function

Functions

Detailed Description

Function Documentation

◆ xmpp_stanza_new()

◆ xmpp_stanza_clone()

◆ xmpp_stanza_copy()

◆ xmpp_stanza_release()

◆ xmpp_stanza_is_text()

◆ xmpp_stanza_is_tag()

◆ xmpp_stanza_to_text()

◆ xmpp_stanza_set_name()

◆ xmpp_stanza_get_name()

◆ xmpp_stanza_get_attribute_count()

◆ xmpp_stanza_get_attributes()

◆ xmpp_stanza_set_attribute()

◆ xmpp_stanza_set_ns()

◆ xmpp_stanza_add_child()

◆ xmpp_stanza_set_text()

◆ xmpp_stanza_set_text_with_size()

◆ xmpp_stanza_get_id()

◆ xmpp_stanza_get_ns()

◆ xmpp_stanza_get_type()

◆ xmpp_stanza_get_to()

◆ xmpp_stanza_get_from()

◆ xmpp_stanza_get_child_by_name()

◆ xmpp_stanza_get_child_by_ns()

◆ xmpp_stanza_get_children()

◆ xmpp_stanza_get_next()

◆ xmpp_stanza_get_text()

◆ xmpp_stanza_get_text_ptr()

◆ xmpp_stanza_set_id()

◆ xmpp_stanza_set_type()

◆ xmpp_stanza_set_to()

◆ xmpp_stanza_set_from()

◆ xmpp_stanza_get_attribute()

◆ xmpp_stanza_del_attribute()

◆ xmpp_stanza_reply()

◆ xmpp_message_new()

◆ xmpp_message_get_body()

◆ xmpp_message_set_body()

◆ xmpp_iq_new()

◆ xmpp_presence_new()

◆ xmpp_error_new()