Strophe  0.8
XMPP client library
Data Structures | Defines | Typedefs | Enumerations | Functions
strophe.h File Reference

Strophe public C API definitions. More...

Data Structures

struct  xmpp_mem_t
struct  xmpp_log_t
struct  xmpp_stream_error_t

Defines

#define XMPP_NS_CLIENT   "jabber:client"
 Namespace definition for 'jabber:client'.
#define XMPP_NS_COMPONENT   "jabber:component:accept"
 Namespace definition for 'jabber:component:accept'.
#define XMPP_NS_STREAMS   "http://etherx.jabber.org/streams"
 Namespace definition for 'http://etherx.jabber.org/streams'.
#define XMPP_NS_STREAMS_IETF   "urn:ietf:params:xml:ns:xmpp-streams"
 Namespace definition for 'urn:ietf:params:xml:ns:xmpp-streams'.
#define XMPP_NS_TLS   "urn:ietf:params:xml:ns:xmpp-tls"
 Namespace definition for 'url:ietf:params:xml:ns:xmpp-tls'.
#define XMPP_NS_SASL   "urn:ietf:params:xml:ns:xmpp-sasl"
 Namespace definition for 'urn:ietf:params:xml:ns:xmpp-sasl'.
#define XMPP_NS_BIND   "urn:ietf:params:xml:ns:xmpp-bind"
 Namespace definition for 'urn:ietf:params:xml:ns:xmpp-bind'.
#define XMPP_NS_SESSION   "urn:ietf:params:xml:ns:xmpp-session"
 Namespace definition for 'urn:ietf:params:xml:ns:xmpp-session'.
#define XMPP_NS_AUTH   "jabber:iq:auth"
 Namespace definition for 'jabber:iq:auth'.
#define XMPP_NS_DISCO_INFO   "http://jabber.org/protocol/disco#info"
 Namespace definition for 'http://jabber.org/protocol/disco#info'.
#define XMPP_NS_DISCO_ITEMS   "http://jabber.org/protocol/disco#items"
 Namespace definition for 'http://jabber.org/protocol/disco#items'.
#define XMPP_NS_ROSTER   "jabber:iq:roster"
 Namespace definition for 'jabber:iq:roster'.
#define XMPP_EOK   0
 Success error code.
#define XMPP_EMEM   -1
 Memory related failure error code.
#define XMPP_EINVOP   -2
 Invalid operation error code.
#define XMPP_EINT   -3
 Internal failure error code.

Typedefs

typedef void(* xmpp_log_handler )(void *const userdata, const xmpp_log_level_t level, const char *const area, const char *const msg)
typedef void(* xmpp_conn_handler )(xmpp_conn_t *const conn, const xmpp_conn_event_t event, const int error, xmpp_stream_error_t *const stream_error, void *const userdata)
typedef int(* xmpp_timed_handler )(xmpp_conn_t *const conn, void *const userdata)
typedef int(* xmpp_handler )(xmpp_conn_t *const conn, xmpp_stanza_t *const stanza, void *const userdata)

Enumerations

enum  xmpp_log_level_t { XMPP_LEVEL_DEBUG, XMPP_LEVEL_INFO, XMPP_LEVEL_WARN, XMPP_LEVEL_ERROR }
enum  xmpp_conn_type_t { XMPP_UNKNOWN, XMPP_CLIENT, XMPP_COMPONENT }
enum  xmpp_conn_event_t { XMPP_CONN_CONNECT, XMPP_CONN_DISCONNECT, XMPP_CONN_FAIL }
enum  xmpp_error_type_t {
  XMPP_SE_BAD_FORMAT, XMPP_SE_BAD_NS_PREFIX, XMPP_SE_CONFLICT, XMPP_SE_CONN_TIMEOUT,
  XMPP_SE_HOST_GONE, XMPP_SE_HOST_UNKNOWN, XMPP_SE_IMPROPER_ADDR, XMPP_SE_INTERNAL_SERVER_ERROR,
  XMPP_SE_INVALID_FROM, XMPP_SE_INVALID_ID, XMPP_SE_INVALID_NS, XMPP_SE_INVALID_XML,
  XMPP_SE_NOT_AUTHORIZED, XMPP_SE_POLICY_VIOLATION, XMPP_SE_REMOTE_CONN_FAILED, XMPP_SE_RESOURCE_CONSTRAINT,
  XMPP_SE_RESTRICTED_XML, XMPP_SE_SEE_OTHER_HOST, XMPP_SE_SYSTEM_SHUTDOWN, XMPP_SE_UNDEFINED_CONDITION,
  XMPP_SE_UNSUPPORTED_ENCODING, XMPP_SE_UNSUPPORTED_STANZA_TYPE, XMPP_SE_UNSUPPORTED_VERSION, XMPP_SE_XML_NOT_WELL_FORMED
}

Functions

void xmpp_initialize (void)
 Initialize the Strophe library.
void xmpp_shutdown (void)
 Shutdown the Strophe library.
int xmpp_version_check (int major, int minor)
 Check that Strophe supports a specific API version.
xmpp_ctx_t * xmpp_ctx_new (const xmpp_mem_t *const mem, const xmpp_log_t *const log)
 Create and initialize a Strophe context object.
void xmpp_ctx_free (xmpp_ctx_t *const ctx)
 Free a Strophe context object that is no longer in use.
xmpp_log_t * xmpp_get_default_logger (xmpp_log_level_t level)
 Get a default logger with filtering.
xmpp_conn_t * xmpp_conn_new (xmpp_ctx_t *const ctx)
 Create a new Strophe connection object.
xmpp_conn_t * xmpp_conn_clone (xmpp_conn_t *const conn)
 Clone a Strophe connection object.
int xmpp_conn_release (xmpp_conn_t *const conn)
 Release a Strophe connection object.
const char * xmpp_conn_get_jid (const xmpp_conn_t *const conn)
 Get the JID which is or will be bound to the connection.
const char * xmpp_conn_get_bound_jid (const xmpp_conn_t *const conn)
 Get the JID discovered during binding time.
void xmpp_conn_set_jid (xmpp_conn_t *const conn, const char *const jid)
 Set the JID of the user that will be bound to the connection.
const char * xmpp_conn_get_pass (const xmpp_conn_t *const conn)
 Get the password used for authentication of a connection.
void xmpp_conn_set_pass (xmpp_conn_t *const conn, const char *const pass)
 Set the password used to authenticate the connection.
xmpp_ctx_t * xmpp_conn_get_context (xmpp_conn_t *const conn)
 Get the strophe context that the connection is associated with.
void xmpp_conn_disable_tls (xmpp_conn_t *const conn)
 Disable TLS for this connection, called by users of the library.
int xmpp_connect_client (xmpp_conn_t *const conn, const char *const altdomain, unsigned short altport, xmpp_conn_handler callback, void *const userdata)
 Initiate a connection to the XMPP server.
void xmpp_disconnect (xmpp_conn_t *const conn)
 Initiate termination of the connection to the XMPP server.
void xmpp_send (xmpp_conn_t *const conn, xmpp_stanza_t *const stanza)
 Send an XML stanza to the XMPP server.
void xmpp_send_raw_string (xmpp_conn_t *const conn, const char *const fmt,...)
 Send a raw string to the XMPP server.
void xmpp_send_raw (xmpp_conn_t *const conn, const char *const data, const size_t len)
 Send raw bytes to the XMPP server.
void xmpp_timed_handler_add (xmpp_conn_t *const conn, xmpp_timed_handler handler, const unsigned long period, void *const userdata)
 Add a timed handler.
void xmpp_timed_handler_delete (xmpp_conn_t *const conn, xmpp_timed_handler handler)
 Delete a timed handler.
void xmpp_handler_add (xmpp_conn_t *const conn, xmpp_handler handler, const char *const ns, const char *const name, const char *const type, void *const userdata)
 Add a stanza handler.
void xmpp_handler_delete (xmpp_conn_t *const conn, xmpp_handler handler)
 Delete a stanza handler.
void xmpp_id_handler_add (xmpp_conn_t *const conn, xmpp_handler handler, const char *const id, void *const userdata)
 Add an id based stanza handler.
void xmpp_id_handler_delete (xmpp_conn_t *const conn, xmpp_handler handler, const char *const id)
 Delete an id based stanza handler.
xmpp_stanza_t * xmpp_stanza_new (xmpp_ctx_t *ctx)
 stanzas
xmpp_stanza_t * xmpp_stanza_clone (xmpp_stanza_t *const stanza)
 clone a stanza
xmpp_stanza_t * xmpp_stanza_copy (const xmpp_stanza_t *const stanza)
 copies a stanza and all children
int xmpp_stanza_release (xmpp_stanza_t *const stanza)
 free a stanza object and it's contents
void xmpp_free (const xmpp_ctx_t *const ctx, void *p)
 free some blocks returned by other APIs, for example the buffer you get from xmpp_stanza_to_text
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)
 marshall a stanza into text for transmission or display
xmpp_stanza_t * xmpp_stanza_get_children (xmpp_stanza_t *const stanza)
 Get the list of children.
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_next (xmpp_stanza_t *const stanza)
 Get the next sibling of a stanza.
char * xmpp_stanza_get_attribute (xmpp_stanza_t *const stanza, const char *const name)
 Get an attribute from a stanza.
char * xmpp_stanza_get_ns (xmpp_stanza_t *const stanza)
 Get the namespace attribute of the stanza object.
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.
char * xmpp_stanza_get_name (xmpp_stanza_t *const stanza)
 Get the stanza name.
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_ns (xmpp_stanza_t *const stanza, const char *const ns)
 Set the stanza namespace.
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_name (xmpp_stanza_t *stanza, const char *const name)
 Set the name of a stanza.
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_type (xmpp_stanza_t *const stanza)
 Get the 'type' attribute of the stanza object.
char * xmpp_stanza_get_id (xmpp_stanza_t *const stanza)
 Get the 'id' attribute of the stanza object.
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.
void xmpp_run_once (xmpp_ctx_t *ctx, const unsigned long timeout)
 event loop
void xmpp_run (xmpp_ctx_t *ctx)
 Start the event loop.
void xmpp_stop (xmpp_ctx_t *ctx)
 Stop the event loop.

Detailed Description

Strophe public C API definitions.


Define Documentation

#define XMPP_NS_CLIENT   "jabber:client"

Namespace definition for 'jabber:client'.

#define XMPP_NS_COMPONENT   "jabber:component:accept"

Namespace definition for 'jabber:component:accept'.

#define XMPP_NS_STREAMS   "http://etherx.jabber.org/streams"

Namespace definition for 'http://etherx.jabber.org/streams'.

#define XMPP_NS_STREAMS_IETF   "urn:ietf:params:xml:ns:xmpp-streams"

Namespace definition for 'urn:ietf:params:xml:ns:xmpp-streams'.

#define XMPP_NS_TLS   "urn:ietf:params:xml:ns:xmpp-tls"

Namespace definition for 'url:ietf:params:xml:ns:xmpp-tls'.

#define XMPP_NS_SASL   "urn:ietf:params:xml:ns:xmpp-sasl"

Namespace definition for 'urn:ietf:params:xml:ns:xmpp-sasl'.

#define XMPP_NS_BIND   "urn:ietf:params:xml:ns:xmpp-bind"

Namespace definition for 'urn:ietf:params:xml:ns:xmpp-bind'.

#define XMPP_NS_SESSION   "urn:ietf:params:xml:ns:xmpp-session"

Namespace definition for 'urn:ietf:params:xml:ns:xmpp-session'.

#define XMPP_NS_AUTH   "jabber:iq:auth"

Namespace definition for 'jabber:iq:auth'.

#define XMPP_NS_DISCO_INFO   "http://jabber.org/protocol/disco#info"

Namespace definition for 'http://jabber.org/protocol/disco#info'.

#define XMPP_NS_DISCO_ITEMS   "http://jabber.org/protocol/disco#items"

Namespace definition for 'http://jabber.org/protocol/disco#items'.

#define XMPP_NS_ROSTER   "jabber:iq:roster"

Namespace definition for 'jabber:iq:roster'.

#define XMPP_EOK   0

Success error code.

#define XMPP_EMEM   -1

Memory related failure error code.

This is returned on allocation errors and signals that the host may be out of memory.

#define XMPP_EINVOP   -2

Invalid operation error code.

This error code is returned when the operation was invalid and signals that the Strophe API is being used incorrectly.

#define XMPP_EINT   -3

Internal failure error code.


Typedef Documentation

typedef void(* xmpp_log_handler)(void *const userdata, const xmpp_log_level_t level, const char *const area, const char *const msg)
typedef void(* xmpp_conn_handler)(xmpp_conn_t *const conn, const xmpp_conn_event_t event, const int error, xmpp_stream_error_t *const stream_error, void *const userdata)
typedef int(* xmpp_timed_handler)(xmpp_conn_t *const conn, void *const userdata)
typedef int(* xmpp_handler)(xmpp_conn_t *const conn, xmpp_stanza_t *const stanza, void *const userdata)

Enumeration Type Documentation

Enumerator:
XMPP_LEVEL_DEBUG 
XMPP_LEVEL_INFO 
XMPP_LEVEL_WARN 
XMPP_LEVEL_ERROR 
Enumerator:
XMPP_UNKNOWN 
XMPP_CLIENT 
XMPP_COMPONENT 
Enumerator:
XMPP_CONN_CONNECT 
XMPP_CONN_DISCONNECT 
XMPP_CONN_FAIL 
Enumerator:
XMPP_SE_BAD_FORMAT 
XMPP_SE_BAD_NS_PREFIX 
XMPP_SE_CONFLICT 
XMPP_SE_CONN_TIMEOUT 
XMPP_SE_HOST_GONE 
XMPP_SE_HOST_UNKNOWN 
XMPP_SE_IMPROPER_ADDR 
XMPP_SE_INTERNAL_SERVER_ERROR 
XMPP_SE_INVALID_FROM 
XMPP_SE_INVALID_ID 
XMPP_SE_INVALID_NS 
XMPP_SE_INVALID_XML 
XMPP_SE_NOT_AUTHORIZED 
XMPP_SE_POLICY_VIOLATION 
XMPP_SE_REMOTE_CONN_FAILED 
XMPP_SE_RESOURCE_CONSTRAINT 
XMPP_SE_RESTRICTED_XML 
XMPP_SE_SEE_OTHER_HOST 
XMPP_SE_SYSTEM_SHUTDOWN 
XMPP_SE_UNDEFINED_CONDITION 
XMPP_SE_UNSUPPORTED_ENCODING 
XMPP_SE_UNSUPPORTED_STANZA_TYPE 
XMPP_SE_UNSUPPORTED_VERSION 
XMPP_SE_XML_NOT_WELL_FORMED 

Function Documentation

void xmpp_conn_disable_tls ( xmpp_conn_t *const  conn)

Disable TLS for this connection, called by users of the library.

Occasionally a server will be misconfigured to send the starttls feature, but wil not support the handshake.

Parameters:
conna Strophe connection object
void xmpp_send_raw_string ( xmpp_conn_t *const  conn,
const char *const  fmt,
  ... 
)

Send a raw string to the XMPP server.

This function is a convenience function to send raw string data to the XMPP server. It is used by Strophe to send short messages instead of building up an XML stanza with DOM methods. This should be used with care as it does not validate the data; invalid data may result in immediate stream termination by the XMPP server.

Parameters:
conna Strophe connection object
fmta printf-style format string followed by a variable list of arguments to format
void xmpp_send_raw ( xmpp_conn_t *const  conn,
const char *const  data,
const size_t  len 
)

Send raw bytes to the XMPP server.

This function is a convenience function to send raw bytes to the XMPP server. It is usedly primarly by xmpp_send_raw_string. This function should be used with care as it does not validate the bytes and invalid data may result in stream termination by the XMPP server.

Parameters:
conna Strophe connection object
dataa buffer of raw bytes
lenthe length of the data in the buffer
void xmpp_free ( const xmpp_ctx_t *const  ctx,
void *  p 
)

free some blocks returned by other APIs, for example the buffer you get from xmpp_stanza_to_text

free some blocks returned by other APIs, for example the buffer you get from xmpp_stanza_to_text

All Strophe functions will use this to free allocated memory.

Parameters:
ctxa Strophe context object
pa pointer referencing memory to be freed