Strophe: Stanza and timed event handlers

Strophe 0.14 XMPP client library

Functions
Stanza and timed event handlers

## Functions
void | xmpp_timed_handler_delete (xmpp_conn_t *conn, xmpp_timed_handler handler)
| Delete a timed handler.
void | xmpp_id_handler_delete (xmpp_conn_t *conn, xmpp_handler handler, const char *id)
| Delete an id based stanza handler.
void | xmpp_handler_delete (xmpp_conn_t *conn, xmpp_handler handler)
| Delete a stanza handler.
void | xmpp_timed_handler_add (xmpp_conn_t *conn, xmpp_timed_handler handler, unsigned long period, void *userdata)
| Add a timed handler.
void | xmpp_id_handler_add (xmpp_conn_t *conn, xmpp_handler handler, const char *id, void *userdata)
| Add an id based stanza handler.
void | xmpp_handler_add (xmpp_conn_t *conn, xmpp_handler handler, const char *ns, const char *name, const char *type, void *userdata)
| Add a stanza handler.
void | xmpp_global_timed_handler_add (xmpp_ctx_t *ctx, xmpp_global_timed_handler handler, unsigned long period, void *userdata)
| Add a global timed handler.
void | xmpp_global_timed_handler_delete (xmpp_ctx_t *ctx, xmpp_global_timed_handler handler)
| Delete a global timed handler.

## Detailed Description

## Function Documentation

## ◆ xmpp_timed_handler_delete()

void xmpp_timed_handler_delete | ( | xmpp_conn_t * | conn,
|  | xmpp_timed_handler | handler )

Delete a timed handler.

Parameters

  conn | a Strophe connection object
  handler | function pointer to the handler

## ◆ xmpp_id_handler_delete()

void xmpp_id_handler_delete | ( | xmpp_conn_t * | conn,
|  | xmpp_handler | handler,
|  | const char * | id )

Delete an id based stanza handler.

Parameters

  conn | a Strophe connection object
  handler | a function pointer to a stanza handler
  id | a string containing the id the handler is for

## ◆ xmpp_handler_delete()

void xmpp_handler_delete | ( | xmpp_conn_t * | conn,
|  | xmpp_handler | handler )

Delete a stanza handler.

Parameters

  conn | a Strophe connection object
  handler | a function pointer to a stanza handler

## ◆ xmpp_timed_handler_add()

void xmpp_timed_handler_add | ( | xmpp_conn_t * | conn,
|  | xmpp_timed_handler | handler,
|  | unsigned long | period,
|  | void * | userdata )

Add a timed handler.

The handler will fire for the first time once the period has elapsed, and continue firing regularly after that. Strophe will try its best to fire handlers as close to the period times as it can, but accuracy will vary depending on the resolution of the event loop.

If the handler function returns true, it will be kept, and if it returns false, it will be deleted from the list of handlers.

Parameters

  conn | a Strophe connection object
  handler | a function pointer to a timed handler
  period | the time in milliseconds between firings
  userdata | an opaque data pointer that will be passed to the handler

## ◆ xmpp_id_handler_add()

void xmpp_id_handler_add | ( | xmpp_conn_t * | conn,
|  | xmpp_handler | handler,
|  | const char * | id,
|  | void * | userdata )

Add an id based stanza handler.

This function adds a stanza handler for an <iq/> stanza of type 'result' or 'error' with a specific id attribute. This can be used to handle responses to specific <iq/>s.

If the handler function returns true, it will be kept, and if it returns false, it will be deleted from the list of handlers.

Parameters

  conn | a Strophe connection object
  handler | a function pointer to a stanza handler
  id | a string with the id
  userdata | an opaque data pointer that will be passed to the handler

## ◆ xmpp_handler_add()

void xmpp_handler_add | ( | xmpp_conn_t * | conn,
|  | xmpp_handler | handler,
|  | const char * | ns,
|  | const char * | name,
|  | const char * | type,
|  | void * | userdata )

Add a stanza handler.

This function is used to add a stanza handler to a connection. The handler will be called when the any of the filters match. The name filter matches to the top level stanza name. The type filter matches the 'type' attribute of the top level stanza. The ns filter matches the namespace ('xmlns' attribute) of either the top level stanza or any of it's immediate children (this allows you do handle specific <iq/> stanzas based on the <query/> child namespace.

If the handler function returns true, it will be kept, and if it returns false, it will be deleted from the list of handlers.

Parameters

  conn | a Strophe connection object
  handler | a function pointer to a stanza handler
  ns | a string with the namespace to match
  name | a string with the stanza name to match
  type | a string with the 'type' attribute to match
  userdata | an opaque data pointer that will be passed to the handler

## ◆ xmpp_global_timed_handler_add()

void xmpp_global_timed_handler_add | ( | xmpp_ctx_t * | ctx,
|  | xmpp_global_timed_handler | handler,
|  | unsigned long | period,
|  | void * | userdata )

Add a global timed handler.

The handler will fire for the first time once the period has elapsed, and continue firing regularly after that. Strophe will try its best to fire handlers as close to the period times as it can, but accuracy will vary depending on the resolution of the event loop.

The main difference between global and ordinary handlers:

- Ordinary handler is related to a connection, fires only when the connection is in connected state and is removed once the connection is destroyed.
- Global handler fires regardless of connections state and is related to a Strophe context.

The handler is executed in context of the respective event loop.

If the handler function returns true, it will be kept, and if it returns false, it will be deleted from the list of handlers.

Notice, the same handler pointer may be added multiple times with different userdata pointers. However, xmpp_global_timed_handler_delete() deletes all occurrences.

Parameters

  ctx | a Strophe context object
  handler | a function pointer to a timed handler
  period | the time in milliseconds between firings
  userdata | an opaque data pointer that will be passed to the handler

## ◆ xmpp_global_timed_handler_delete()

void xmpp_global_timed_handler_delete | ( | xmpp_ctx_t * | ctx,
|  | xmpp_global_timed_handler | handler )

Delete a global timed handler.

Parameters

  ctx | a Strophe context object
  handler | function pointer to the handler