Doxyfile docs/footer.html @@ -12,6 +12,10 @@ ** distribution. */ +/** @file + * Authentication function and handlers. + */ + #include <stdio.h> #include <stdlib.h> #include <string.h> @@ -24,11 +28,32 @@ #define strcasecmp stricmp #endif -/* FIXME: these should be configurable */ +/* TODO: these should configurable at runtime on a per connection basis */ + +#ifndef FEATURES_TIMEOUT +/** @def FEATURES_TIMEOUT + * Time to wait for &lt;stream:features/&gt; stanza. + */ #define FEATURES_TIMEOUT 15000 /* 15 seconds */ +#endif +#ifndef BIND_TIMEOUT +/** @def BIND_TIMEOUT + * Time to wait for &lt;bind/&gt; stanza reply. + */ #define BIND_TIMEOUT 15000 /* 15 seconds */ +#endif +#ifndef SESSION_TIMEOUT +/** @def SESSION_TIMEOUT + * Time to wait for &lt;session/&gt; stanza reply. + */ #define SESSION_TIMEOUT 15000 /* 15 seconds */ +#endif +#ifndef LEGACY_TIMEOUT +/** @def LEGACY_TIMEOUT + * Time to wait for legacy authentication to complete. + */ #define LEGACY_TIMEOUT 15000 /* 15 seconds */ +#endif static void _auth(xmpp_conn_t * const conn); static void _handle_open_tls(xmpp_conn_t * const conn); @@ -65,7 +90,6 @@ static int _handle_missing_session(xmpp_conn_t * const conn, void * const userdata); /* stream:error handler */ - static int _handle_error(xmpp_conn_t * const conn, xmpp_stanza_t * const stanza, void * const userdata) @@ -160,7 +184,6 @@ static int _handle_error(xmpp_conn_t * const conn, } /* stream:features handlers */ - static int _handle_missing_features(xmpp_conn_t * const conn, void * const userdata) { @@ -466,7 +489,8 @@ static xmpp_stanza_t *_make_sasl_auth(xmpp_conn_t * const conn, /* authenticate the connection * this may get called multiple times. if any auth method fails, * this will get called again until one auth method succeeds or every - * method fails */ + * method fails + */ static void _auth(xmpp_conn_t * const conn) { xmpp_stanza_t *auth, *authdata, *query, *child, *iq; @@ -503,8 +527,7 @@ static void _auth(xmpp_conn_t * const conn) /* TLS was tried, unset flag */ conn->tls_support = 0; - } - else if (conn->sasl_support & SASL_MASK_DIGESTMD5) { + } else if (conn->sasl_support & SASL_MASK_DIGESTMD5) { auth = _make_sasl_auth(conn, "DIGEST-MD5"); if (!auth) { disconnect_mem_error(conn); @@ -661,7 +684,15 @@ static void _auth(xmpp_conn_t * const conn) } -/* this is called on initial stream open */ +/** Set up handlers at stream start. + * This function is called internally to Strophe for handling the opening + * of an XMPP stream. It's called by the parser when a stream is opened + * or reset, and adds the initial handlers for <stream:error/> and + * <stream:features/>. This function is not intended for use outside + * of Strophe. + * + * @param conn a Strophe connection object + */ void auth_handle_open(xmpp_conn_t * const conn) { /* reset all timed handlers */ src/auth.c @@ -12,6 +12,13 @@ ** distribution. */ +/** @file + * Connection management. + */ + +/** @defgroup Connections Connection management + */ + #include <stdio.h> #include <stdlib.h> #include <string.h> @@ -20,14 +27,38 @@ #include "common.h" #include "util.h" +#ifndef DEFAULT_SEND_QUEUE_MAX +/** @def DEFAULT_SEND_QUEUE_MAX + * The default maximum send queue size. This is currently unused. + */ #define DEFAULT_SEND_QUEUE_MAX 64 +#endif +#ifndef DISCONNECT_TIMEOUT +/** @def DISCONNECT_TIMEOUT + * The time to wait (in milliseconds) for graceful disconnection to + * complete before the connection is reset. The default is 2 seconds. + */ #define DISCONNECT_TIMEOUT 2000 /* 2 seconds */ +#endif +#ifndef CONNECT_TIMEOUT +/** @def CONNECT_TIMEOUT + * The time to wait (in milliseconds) for a connection attempt to succeed + * or error. The default is 5 seconds. + */ #define CONNECT_TIMEOUT 5000 /* 5 seconds */ +#endif static int _disconnect_cleanup(xmpp_conn_t * const conn, void * const userdata); - +/** Create a new Strophe connection object. + * + * @param ctx a Strophe context object + * + * @return a Strophe connection object or NULL on an error + * + * @ingroup Connections + */ xmpp_conn_t *xmpp_conn_new(xmpp_ctx_t * const ctx) { xmpp_conn_t *conn = NULL; @@ -111,12 +142,31 @@ xmpp_conn_t *xmpp_conn_new(xmpp_ctx_t * const ctx) return conn; } +/** Clone a Strophe connection object. + * + * @param conn a Strophe connection object + * + * @return the same conn object passed in with its reference count + * incremented by 1 + * + * @ingroup Connections + */ xmpp_conn_t *xmpp_conn_clone(xmpp_conn_t * const conn) { conn->ref++; return conn; } +/** Release a Strophe connection object. + * Decrement the reference count by one for a connection, freeing the + * connection object if the count reaches 0. + * + * @param conn a Strophe connection object + * + * @return TRUE if the connection object was freed and FALSE otherwise + * + * @ingroup Connections + */ int xmpp_conn_release(xmpp_conn_t * const conn) { xmpp_ctx_t *ctx; @@ -212,14 +262,28 @@ int xmpp_conn_release(xmpp_conn_t * const conn) return released; } +/** Get the JID which is or will be bound to the connection. + * + * @param conn a Strophe connection object + * + * @return a string containing the full JID or NULL if it has not been set + * + * @ingroup Connections + */ const char *xmpp_conn_get_jid(const xmpp_conn_t * const conn) { return conn->jid; } -/* set the jid of the user or the component name. in the first case, - * this can be a full jid, or a bare jid. in the second case, this will - * probably be a domain only. +/** Set the JID of the user that will be bound to the connection. + * If any JID was previously set, it will be discarded. This should not be + * be used after a connection is bound. The function will make a copy of + * the JID string. + * + * @param conn a Strophe connection object + * @param jid a full or bare JID + * + * @ingroup Connections */ void xmpp_conn_set_jid(xmpp_conn_t * const conn, const char * const jid) { @@ -227,17 +291,55 @@ void xmpp_conn_set_jid(xmpp_conn_t * const conn, const char * const jid) conn->jid = xmpp_strdup(conn->ctx, jid); } +/** Get the password used for authentication of a connection. + * + * @param conn a Strophe connection object + * + * @return a string containing the password or NULL if it has not been set + * + * @ingroup Connections + */ const char *xmpp_conn_get_pass(const xmpp_conn_t * const conn) { return conn->pass; } +/** Set the password used to authenticate the connection. + * If any password was previously set, it will be discarded. The function + * will make a copy of the password string. + * + * @param conn a Strophe connection object + * @param pass the password + * + * @ingroup Connections + */ void xmpp_conn_set_pass(xmpp_conn_t * const conn, const char * const pass) { if (conn->pass) xmpp_free(conn->ctx, conn->pass); conn->pass = xmpp_strdup(conn->ctx, pass); } +/** Initiate a connection to the XMPP server. + * This function returns immediately after starting the connection + * process to the XMPP server, and notifiations of connection state changes + * will be sent to the callback function. The domain and port to connect to + * are usually determined by an SRV lookup for the xmpp-client service at + * the domain specified in the JID. If SRV lookup fails, altdomain and + * altport will be used instead if specified. + * + * @param conn a Strophe connection object + * @param domain a string with the domain name to connect to. If this is + * NULL then the domain is taken from the JID. + * @param altdomain a string with domain to use if SRV lookup fails + * @param altport an integer port number to use if SRV lookup fails + * @param callback a xmpp_conn_handler callback function that will receive + * notifications of connection status + * @param userdata an opaque data pointer that will be passed to the callback + * + * @return 0 on success and -1 on an error + * + * @ingroup Connections + */ int xmpp_connect_client(xmpp_conn_t * const conn, const char * const domain, const char * const altdomain, @@ -284,9 +386,12 @@ int xmpp_connect_client(xmpp_conn_t * const conn, return 0; } -/* this function is only called by the end tag handler. it is - * the only place where a conn_disconnect would be called during a clean - * disconnect sequence */ +/** Cleanly disconnect the connection. + * This function is only called by the stream parser when </stream:stream> + * is received, and it not intended to be called by code outside of Strophe. + * + * @param conn a Strophe connection object + */ void conn_disconnect_clean(xmpp_conn_t * const conn) { /* remove the timed handler */ @@ -295,6 +400,12 @@ void conn_disconnect_clean(xmpp_conn_t * const conn) conn_disconnect(conn); } +/** Disconnect from the XMPP server. + * This function immediately disconnects from the XMPP server, and should + * not be used outside of the Strophe library. + * + * @param conn a Strophe connection object + */ void conn_disconnect(xmpp_conn_t * const conn) { xmpp_debug(conn->ctx, "xmpp", "Closing socket."); @@ -323,9 +434,15 @@ static int _disconnect_cleanup(xmpp_conn_t * const conn, return 0; } -/* terminates the XMPP stream, closing the underlying socket, - * and calls the conn_handler. this function returns immediately - * without calling the handler if the connection is not active */ +/** Initiate termination of the connection to the XMPP server. + * This function starts the disconnection sequence by sending + * </stream:stream> to the XMPP server. This function will do nothing + * if the connection state is CONNECTING or CONNECTED. + * + * @param conn a Strophe connection object + * + * @ingroup Connections + */ void xmpp_disconnect(xmpp_conn_t * const conn) { if (conn->state != XMPP_STATE_CONNECTING && @@ -340,7 +457,17 @@ void xmpp_disconnect(xmpp_conn_t * const conn) DISCONNECT_TIMEOUT, NULL); } -/* convinience function for sending data to a connection */ +/** 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. + * + * @param conn a Strophe connection object + * @param fmt a printf-style format string followed by a variable list of + * arguments to format + */ void xmpp_send_raw_string(xmpp_conn_t * const conn, const char * const fmt, ...) { @@ -379,7 +506,16 @@ void xmpp_send_raw_string(xmpp_conn_t * const conn, } } -/* adds data to the send queue for a connection */ +/** 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. + * + * @param conn a Strophe connection object + * @param data a buffer of raw bytes + * @param len the length of the data in the buffer + */ void xmpp_send_raw(xmpp_conn_t * const conn, const char * const data, const size_t len) { @@ -414,6 +550,15 @@ void xmpp_send_raw(xmpp_conn_t * const conn, conn->send_queue_len++; } +/** Send an XML stanza to the XMPP server. + * This is the main way to send data to the XMPP server. The function will + * terminate without action if the connection state is not CONNECTED. + * + * @param conn a Strophe connection object + * @param stanza a Strophe stanza object + * + * @ingroup Connections + */ void xmpp_send(xmpp_conn_t * const conn, xmpp_stanza_t * const stanza) { @@ -430,6 +575,12 @@ void xmpp_send(xmpp_conn_t * const conn, } } +/** Send the opening &lt;stream:stream&gt; tag to the server. + * This function is used by Strophe to begin an XMPP stream. It should + * not be used outside of the library. + * + * @param conn a Strophe connection object + */ void conn_open_stream(xmpp_conn_t * const conn) { xmpp_send_raw_string(conn, src/conn.c @@ -12,6 +12,37 @@ ** distribution. */ +/** @file + * Runtime contexts, library initialization and shutdown, and versioning. + */ + +/** @defgroup Context Context objects + * These functions create and manipulate Strophe context objects. + * + * In order to support usage in a variety of environments, the + * Strophe library uses a runtime context object. This object + * contains the information on how to do memory allocation and + * logging. This allows the user to control how memory is allocated + * and what do to with log messages. + * + * These issues do not affect programs in the common case, but many + * environments require special treatment. Abstracting these into a runtime + * context object makes it easy to use Strophe on embedded platforms. + * + * Objects in Strophe are reference counted to ease memory management issues, + * but the context objects are not. + */ + +/** @defgroup Init Initialization, shutdown, and versioning + * These functions initialize and shutdown the library, and also allow + * for API version checking. Failure to properly call these functions may + * result in strange (and platform dependent) behavior. + * + * Specifically, the socket library on Win32 platforms must be initialized + * before use (although this is not the case on POSIX systems). The TLS + * subsystem must also seed the random number generator. + */ + #include <stdlib.h> #include <stdio.h> #include <stdarg.h> @@ -21,41 +52,63 @@ #include "common.h" #include "util.h" -/* initialization and shutdown */ - -void xmpp_initialize(void) +/** Initialize the Strophe library. + * This function initializes subcomponents of the Strophe library and must + * be called for Strophe to operate correctly. + * + * @ingroup Init + */ + void xmpp_initialize(void) { sock_initialize(); tls_initialize(); } +/** Shutdown the Strophe library. + * + * @ingroup Init + */ void xmpp_shutdown(void) { - sock_shutdown(); tls_shutdown(); + sock_shutdown(); } -/** version **/ +/* version information */ -/* TODO: update from the build system? */ #ifndef LIBXMPP_VERSION_MAJOR +/** @def LIBXMPP_VERSION_MAJOR + * The major version number of Strophe. + */ #define LIBXMPP_VERSION_MAJOR (0) #endif #ifndef LIBXMPP_VERSION_MINOR +/** @def LIBXMPP_VERSION_MINOR + * The minor version number of Strophe. + */ #define LIBXMPP_VERSION_MINOR (0) #endif +/** Check that Strophe supports a specific API version. + * + * @param major the major version number + * @param minor the minor version number + * + * @return TRUE if the version is supported and FALSE if unsupported + * + * @ingroup Init + */ int xmpp_version_check(int major, int minor) { return (major == LIBXMPP_VERSION_MAJOR) && (minor >= LIBXMPP_VERSION_MINOR); } -/** run-time contexts **/ +/* We define the global default allocator, logger, and context here. */ -/* define the global default allocator, logger and context here */ - -/* wrap stdlib routines to deal with userdata pointer */ +/* Wrap stdlib routines malloc, free, and realloc for default memory + * management. + */ static void *_malloc(const size_t size, void * const userdata) { return malloc(size); @@ -71,6 +124,7 @@ static void *_realloc(void *p, const size_t size, void * const userdata) return realloc(p, size); } +/* default memory function map */ static xmpp_mem_t xmpp_default_mem = { _malloc, /* use the thinly wrapped stdlib routines by default */ _free, @@ -78,12 +132,22 @@ static xmpp_mem_t xmpp_default_mem = { NULL }; +/* log levels and names */ static const char * const _xmpp_log_level_name[4] = {"DEBUG", "INFO", "WARN", "ERROR"}; static const xmpp_log_level_t _xmpp_default_logger_levels[] = {XMPP_LEVEL_DEBUG, XMPP_LEVEL_INFO, XMPP_LEVEL_WARN, XMPP_LEVEL_ERROR}; +/** Log a message. + * The default logger writes to stderr. + * + * @param userdata the opaque data used by the default logger. This contains + * the filter level in the default logger. + * @param level the level to log at + * @param area the area the log message is for + * @param msg the log message + */ void xmpp_default_logger(void * const userdata, const xmpp_log_level_t level, const char * const area, @@ -101,6 +165,17 @@ static const xmpp_log_t _xmpp_default_loggers[] = { {&xmpp_default_logger, (void*)&_xmpp_default_logger_levels[XMPP_LEVEL_ERROR]} }; +/** Get a default logger with filtering. + * The default logger provides a basic logging setup which writes log + * messages to stderr. Only messages where level is greater than or + * equal to the filter level will be logged. + * + * @param level the highest level the logger will log at + * + * @return the log structure for the given level + * + * @ingroup Context + */ xmpp_log_t *xmpp_get_default_logger(xmpp_log_level_t level) { /* clamp to the known range */ @@ -112,28 +187,60 @@ xmpp_log_t *xmpp_get_default_logger(xmpp_log_level_t level) static xmpp_log_t xmpp_default_log = { NULL, NULL }; -/** convenience functions for accessing the context **/ - -/* allocator */ +/* convenience functions for accessing the context */ +/** Allocate memory in a Strophe context. + * All Strophe functions will use this to allocate memory. + * + * @param ctx a Strophe context object + * @param size the number of bytes to allocate + * + * @return a pointer to the allocated memory or NULL on an error + */ void *xmpp_alloc(const xmpp_ctx_t * const ctx, const size_t size) { return ctx->mem->alloc(size, ctx->mem->userdata); } +/** Free memory in a Strophe context. + * All Strophe functions will use this to free allocated memory. + * + * @param ctx a Strophe context object + * @param p a pointer referencing memory to be freed + */ void xmpp_free(const xmpp_ctx_t * const ctx, void *p) { ctx->mem->free(p, ctx->mem->userdata); } +/** Reallocate memory in a Strophe context. + * All Strophe functions will use this to reallocate memory. + * + * @param ctx a Strophe context object + * @param p a pointer to previously allocated memory + * @param size the new size in bytes to allocate + * + * @return a pointer to the reallocated memory or NULL on an error + */ void *xmpp_realloc(const xmpp_ctx_t * const ctx, void *p, const size_t size) { return ctx->mem->realloc(p, size, ctx->mem->userdata); } -/* logger */ - +/** Write a log message to the logger. + * Write a log message to the logger for the context for the specified + * level and area. This function takes a printf-style format string and a + * variable argument list (in va_list) format. This function is not meant + * to be called directly, but is used via xmpp_error, xmpp_warn, xmpp_info, + * and xmpp_debug. + * + * @param ctx a Strophe context object + * @param level the level at which to log + * @param area the area to log for + * @param fmt a printf-style format string for the message + * @param ap variable argument list supplied for the format string + */ void xmpp_log(const xmpp_ctx_t * const ctx, const xmpp_log_level_t level, const char * const area, @@ -165,6 +272,16 @@ void xmpp_log(const xmpp_ctx_t * const ctx, ctx->log->handler(ctx->log->userdata, level, area, buf); } +/** Write to the log at the ERROR level. + * This is a convenience function for writing to the log at the + * ERROR level. It takes a printf-style format string followed by a + * variable list of arguments for formatting. + * + * @param ctx a Strophe context object + * @param area the area to log for + * @param fmt a printf-style format string followed by a variable list of + * arguments to format + */ void xmpp_error(const xmpp_ctx_t * const ctx, const char * const area, const char * const fmt, @@ -177,6 +294,16 @@ void xmpp_error(const xmpp_ctx_t * const ctx, va_end(ap); } +/** Write to the log at the WARN level. + * This is a convenience function for writing to the log at the WARN level. + * It takes a printf-style format string followed by a variable list of + * arguments for formatting. + * + * @param ctx a Strophe context object + * @param area the area to log for + * @param fmt a printf-style format string followed by a variable list of + * arguments to format + */ void xmpp_warn(const xmpp_ctx_t * const ctx, const char * const area, const char * const fmt, @@ -189,6 +316,16 @@ void xmpp_warn(const xmpp_ctx_t * const ctx, va_end(ap); } +/** Write to the log at the INFO level. + * This is a convenience function for writing to the log at the INFO level. + * It takes a printf-style format string followed by a variable list of + * arguments for formatting. + * + * @param ctx a Strophe context object + * @param area the area to log for + * @param fmt a printf-style format string followed by a variable list of + * arguments to format + */ void xmpp_info(const xmpp_ctx_t * const ctx, const char * const area, const char * const fmt, @@ -201,6 +338,16 @@ void xmpp_info(const xmpp_ctx_t * const ctx, va_end(ap); } +/** Write to the log at the DEBUG level. + * This is a convenience function for writing to the log at the DEBUG level. + * It takes a printf-style format string followed by a variable list of + * arguments for formatting. + * + * @param ctx a Strophe context object + * @param area the area to log for + * @param fmt a printf-style format string followed by a variable list of + * arguments to format + */ void xmpp_debug(const xmpp_ctx_t * const ctx, const char * const area, const char * const fmt, @@ -213,7 +360,20 @@ void xmpp_debug(const xmpp_ctx_t * const ctx, va_end(ap); } -/** allocate and initialize a new ctx object */ +/** Create and initialize a Strophe context object. + * If mem is NULL, a default allocation setup will be used which + * wraps malloc(), free(), and realloc() from the standard library. + * If log is NULL, a default logger will be used which does no + * logging. Basic filtered logging to stderr can be done with the + * xmpp_get_default_logger() convenience function. + * + * @param mem a pointer to an xmpp_mem_t structure or NULL + * @param log a pointer to an xmpp_log_t structure or NULL + * + * @return the allocated Strophe context object or NULL on an error + * + * @ingroup Context + */ xmpp_ctx_t *xmpp_ctx_new(const xmpp_mem_t * const mem, const xmpp_log_t * const log) { @@ -242,7 +402,12 @@ xmpp_ctx_t *xmpp_ctx_new(const xmpp_mem_t * const mem, return ctx; } -/** free a ctx object no longer in use */ +/** Free a Strophe context object that is no longer in use. + * + * @param ctx a Strophe context object + * + * @ingroup Context + */ void xmpp_ctx_free(xmpp_ctx_t * const ctx) { /* mem and log are owned by their suppliers */ src/ctx.c @@ -12,6 +12,27 @@ ** distribution. */ +/** @file + * Event loop and management. + */ + +/** @defgroup EventLoop Event loop + * These functions manage the Strophe event loop. + * + * Simple tools can use xmpp_run() and xmpp_stop() to manage the life + * cycle of the program. A common idiom is to set up a few initial + * event handers, call xmpp_run(), and then respond and react to + * events as they come in. At some point, one of the handlers will + * call xmpp_stop() to quit the event loop which leads to the program + * terminating. + * + * More complex programs will have their own event loops, and should + * ensure that xmpp_run_once() is called regularly from there. For + * example, a GUI program will already include an event loop to + * process UI events from users, and xmpp_run_once() would be called + * from an idle function. + */ + #include <stdio.h> #include <stdlib.h> #include <string.h> @@ -29,10 +50,27 @@ #include "strophe.h" #include "common.h" +#ifndef DEFAULT_TIMEOUT +/** @def DEFAULT_TIMEOUT + * The default timeout in milliseconds for the event loop. + * This is set to 1 millisecond. + */ #define DEFAULT_TIMEOUT 1 +#endif -/* send data and check all connections for their events - * and call event handlers. timeout is in milliseconds */ +/** Run the event loop once. + * This function will run send any data that has been queued by + * xmpp_send and related functions and run through the Strophe even + * loop a single time, and will not wait more than timeout + * milliseconds for events. This is provided to support integration + * with event loops outside the library, and if used, should be + * called regularly to achieve low latency event handling. + * + * @param ctx a Strophe context object + * @param timeout time to wait for events in milliseconds + * + * @ingroup EventLoop + */ void xmpp_run_once(xmpp_ctx_t *ctx, const unsigned long timeout) { xmpp_connlist_t *connitem; @@ -71,6 +109,7 @@ void xmpp_run_once(xmpp_ctx_t *ctx, const unsigned long timeout) } } + /* write all data from the send queue to the socket */ sq = conn->send_queue_head; while (sq) { towrite = sq->len - sq->written; @@ -265,6 +304,14 @@ void xmpp_run_once(xmpp_ctx_t *ctx, const unsigned long timeout) handler_fire_timed(ctx); } +/** Start the event loop. + * This function continuously calls xmpp_run_once and does not return + * until xmpp_stop has been called. + * + * @param ctx a Strophe context object + * + * @ingroup EventLoop + */ void xmpp_run(xmpp_ctx_t *ctx) { if (ctx->loop_status != XMPP_LOOP_NOTSTARTED) return; @@ -277,6 +324,14 @@ void xmpp_run(xmpp_ctx_t *ctx) xmpp_debug(ctx, "event", "Event loop completed."); } +/** Stop the event loop. + * This will stop the event loop after the current iteration and cause + * xmpp_run to exit. + * + * @param ctx a Strophe context object + * + * @ingroup EventLoop + */ void xmpp_stop(xmpp_ctx_t *ctx) { xmpp_debug(ctx, "event", "Stopping event loop."); src/event.c @@ -12,6 +12,13 @@ ** distribution. */ +/** @file + * Event handler management. + */ + +/** @defgroup Handlers Stanza and timed event handlers + */ + #include <stdio.h> #include <stdlib.h> #include <string.h> @@ -25,6 +32,13 @@ #include "strophe.h" #include "common.h" +/** Fire off all stanza handlers that match. + * This function is called internally by the event loop whenever stanzas + * are received from the XMPP server. + * + * @param conn a Strophe connection object + * @param stanza a Strophe stanza object + */ void handler_fire_stanza(xmpp_conn_t * const conn, xmpp_stanza_t * const stanza) { @@ -108,8 +122,13 @@ void handler_fire_stanza(xmpp_conn_t * const conn, } } -/* helper function to fire timed handlers. returns the - * time until the next handler would be fired */ +/** Fire off all timed handlers that are ready. + * This function is called internally by the event loop. + * + * @param ctx a Strophe context object + * + * @return the time in milliseconds until the next handler will be ready + */ uint64_t handler_fire_timed(xmpp_ctx_t * const ctx) { xmpp_connlist_t *connitem; @@ -169,8 +188,12 @@ uint64_t handler_fire_timed(xmpp_ctx_t * const ctx) return min; } -/* reset timed handlers for a connection. this is called - * whenever connection is successful */ +/** Reset all timed handlers. + * This function is called internally when a connection is successful. + * + * @param conn a Strophe connection object + * @param user_only whether to reset all handlers or only user ones + */ void handler_reset_timed(xmpp_conn_t *conn, int user_only) { xmpp_handlist_t *handitem; @@ -223,6 +246,13 @@ static void _timed_handler_add(xmpp_conn_t * const conn, } } +/** Delete a timed handler. + * + * @param conn a Strophe connection object + * @param handler function pointer to the handler + * + * @ingroup Handlers + */ void xmpp_timed_handler_delete(xmpp_conn_t * const conn, xmpp_timed_handler handler) { @@ -292,6 +322,14 @@ static void _id_handler_add(xmpp_conn_t * const conn, } } +/** Delete an id based stanza handler. + * + * @param conn a Strophe connection object + * @param handler a function pointer to a stanza handler + * @param id a string containing the id the handler is for + * + * @ingroup Handlers + */ void xmpp_id_handler_delete(xmpp_conn_t * const conn, xmpp_handler handler, const char * const id) @@ -322,6 +360,7 @@ void xmpp_id_handler_delete(xmpp_conn_t * const conn, } } +/* add a stanza handler */ static void _handler_add(xmpp_conn_t * const conn, xmpp_handler handler, const char * const ns, @@ -386,6 +425,13 @@ static void _handler_add(xmpp_conn_t * const conn, } } +/** Delete a stanza handler. + * + * @param conn a Strophe connection object + * @param handler a function pointer to a stanza handler + * + * @ingroup Handlers + */ void xmpp_handler_delete(xmpp_conn_t * const conn, xmpp_handler handler) { @@ -416,6 +462,19 @@ void xmpp_handler_delete(xmpp_conn_t * const conn, } } +/** 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. + * + * @param conn a Strophe connection object + * @param handler a function pointer to a timed handler + * @param period the time in milliseconds between firings + * @param userdata an opaque data pointer that will be passed to the handler + * + * @ingroup Handlers + */ void xmpp_timed_handler_add(xmpp_conn_t * const conn, xmpp_timed_handler handler, const unsigned long period, @@ -424,6 +483,15 @@ void xmpp_timed_handler_add(xmpp_conn_t * const conn, _timed_handler_add(conn, handler, period, userdata, 1); } +/** Add a timed system handler. + * This function is used to add internal timed handlers and should not be + * used outside of the library. + * + * @param conn a Strophe connection object + * @param handler a function pointer to a timed handler + * @param period the time in milliseconds between firings + * @param userdata an opaque data pointer that will be passed to the handler + */ void handler_add_timed(xmpp_conn_t * const conn, xmpp_timed_handler handler, const unsigned long period, @@ -432,6 +500,19 @@ void handler_add_timed(xmpp_conn_t * const conn, _timed_handler_add(conn, handler, period, userdata, 0); } +/** Add an id based stanza handler. + + * This function adds a stanza handler for an &lt;iq/&gt; stanza of + * type 'result' or 'error' with a specific id attribute. This can + * be used to handle responses to specific &lt;iq/&gt;s. + * + * @param conn a Strophe connection object + * @param handler a function pointer to a stanza handler + * @param id a string with the id + * @param userdata an opaque data pointer that will be passed to the handler + * + * @ingroup Handlers + */ void xmpp_id_handler_add(xmpp_conn_t * const conn, xmpp_handler handler, const char * const id, @@ -440,6 +521,15 @@ void xmpp_id_handler_add(xmpp_conn_t * const conn, _id_handler_add(conn, handler, id, userdata, 1); } +/** Add an id based system stanza handler. + * This function is used to add internal id based stanza handlers and should + * not be used outside of the library. + * + * @param conn a Strophe connection object + * @param handler a function pointer to a stanza handler + * @param id a string with the id + * @param userdata an opaque data pointer that will be passed to the handler + */ void handler_add_id(xmpp_conn_t * const conn, xmpp_handler handler, const char * const id, @@ -448,6 +538,25 @@ void handler_add_id(xmpp_conn_t * const conn, _id_handler_add(conn, handler, id, userdata, 0); } +/** 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 &lt;iq/&gt; stanzas based on the &lt;query/&gt; + * child namespace. + * + * @param conn a Strophe connection object + * @param handler a function pointer to a stanza handler + * @param ns a string with the namespace to match + * @param name a string with the stanza name to match + * @param type a string with the 'type' attribute to match + * @param userdata an opaque data pointer that will be passed to the handler + * + * @ingroup Handlers + */ void xmpp_handler_add(xmpp_conn_t * const conn, xmpp_handler handler, const char * const ns, @@ -458,6 +567,17 @@ void xmpp_handler_add(xmpp_conn_t * const conn, _handler_add(conn, handler, ns, name, type, userdata, 1); } +/** Add a system stanza handler. + * This function is used to add internal stanza handlers and should + * not be used outside of the library. + * + * @param conn a Strophe connection object + * @param handler a function pointer to a stanza handler + * @param ns a string with the namespace to match + * @param name a string with the stanza name to match + * @param type a string with the 'type' attribute value to match + * @param userdata an opaque data pointer that will be passed to the handler + */ void handler_add(xmpp_conn_t * const conn, xmpp_handler handler, const char * const ns, src/handler.c @@ -12,6 +12,10 @@ ** distribution. */ +/** @file + * Hash tables. + */ + #include <stdlib.h> #include <string.h> src/hash.c @@ -12,12 +12,25 @@ ** distribution. */ +/** @file + * JID creation and parsing. + */ + #include <string.h> #include "strophe.h" #include "common.h" -/** join jid component parts to form a new jid string */ +/** Create a JID string from component parts node, domain, and resource. + * + * @param ctx the Strophe context object + * @param node a string representing the node + * @param domain a string representing the domain. Required. + * @param resource a string representing the resource + * + * @return an allocated string with the full JID or NULL if no domain + * is specified + */ char *xmpp_jid_new(xmpp_ctx_t *ctx, const char *node, const char *domain, const char *resource) @@ -52,7 +65,13 @@ char *xmpp_jid_new(xmpp_ctx_t *ctx, const char *node, return result; } -/** return a bare jid */ +/** Create a bare JID from a JID. + * + * @param ctx the Strophe context object + * @param jid the JID + * + * @return an allocated string with the bare JID or NULL on an error + */ char *xmpp_jid_bare(xmpp_ctx_t *ctx, const char *jid) { char *result; @@ -70,7 +89,14 @@ char *xmpp_jid_bare(xmpp_ctx_t *ctx, const char *jid) return result; } -/** return the node portion of a jid */ +/** Create a node string from a JID. + * + * @param ctx a Strophe context object + * @param jid the JID + * + * @return an allocated string with the node or NULL if no node is found + * or an error occurs + */ char *xmpp_jid_node(xmpp_ctx_t *ctx, const char *jid) { char *result = NULL; @@ -88,7 +114,13 @@ char *xmpp_jid_node(xmpp_ctx_t *ctx, const char *jid) return result; } -/** return the domain portion of a jid */ +/** Create a domain string from a JID. + * + * @param ctx the Strophe context object + * @param jid the JID + * + * @return an allocated string with the domain or NULL on an error + */ char *xmpp_jid_domain(xmpp_ctx_t *ctx, const char *jid) { char *result = NULL; @@ -116,7 +148,14 @@ char *xmpp_jid_domain(xmpp_ctx_t *ctx, const char *jid) return result; } -/** return the node portion of a jid */ +/** Create a resource string from a JID. + * + * @param ctx a Strophe context object + * @param jid the JID + * + * @return an allocated string with the resource or NULL if no resource + * is found or an error occurs + */ char *xmpp_jid_resource(xmpp_ctx_t *ctx, const char *jid) { char *result = NULL; src/jid.c @@ -21,6 +21,10 @@ * will fill a supplied 16-byte array with the digest. */ +/** @file + * MD5 hash. + */ + #include <string.h> /* memcpy(), memset() */ #include "md5.h" src/md5.c @@ -12,6 +12,10 @@ ** distribution. */ +/** @file + * XML parser handlers. + */ + #include <stdio.h> #include <stdlib.h> #include <string.h> src/parser.c @@ -12,6 +12,10 @@ ** distribution. */ +/** @file + * SASL authentication. + */ + #include <string.h> #include "strophe.h" src/sasl.c @@ -1,3 +1,7 @@ +/** @file + * SHA-1 hash. + */ + /* SHA-1 in C By Steve Reid <sreid@sea-to-sky.net> src/sha1.c @@ -55,6 +55,10 @@ * **************************************************************/ +/** @file + * A snprintf implementation. + */ + /* JAM: we don't need this - #include "config.h" */ /* JAM: changed declarations to xmpp_snprintf and xmpp_vsnprintf to src/snprintf.c @@ -12,6 +12,10 @@ ** distribution. */ +/** @file + * Socket abstraction. + */ + #include <stdio.h> #include <string.h> #include <sys/types.h> src/sock.c @@ -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) { src/stanza.c @@ -12,6 +12,10 @@ ** distribution. */ +/** @file + * Thread absraction. + */ + #include <stdio.h> #include <stdlib.h> src/thread.c @@ -12,6 +12,10 @@ ** distribution. */ +/** @file + * TLS dummy implementation. + */ + #include "common.h" #include "tls.h" #include "sock.h" src/tls_dummy.c @@ -12,6 +12,10 @@ ** distribution. */ +/** @file + * TLS implementation with GNUTLS + */ + #include <gnutls/gnutls.h> #include "common.h" src/tls_gnutls.c @@ -12,6 +12,10 @@ ** distribution. */ +/** @file + * TLS implementation with OpenSSL. + */ + #include <openssl/ssl.h> #include <openssl/applink.c> src/tls_openssl.c @@ -12,6 +12,10 @@ ** distribution. */ +/** @file + * TLS implementation with Win32 SChannel. + */ + #include "common.h" #include "tls.h" #include "sock.h" src/tls_schannel.c @@ -12,6 +12,10 @@ ** distribution. */ +/** @file + * Utility functions. + */ + #include <stdio.h> #include <string.h> @@ -28,6 +32,15 @@ #include "util.h" /** implement our own strdup that uses the ctx allocator */ +/** Duplicate a string. + * This function replaces the standard strdup library call with a version + * that uses the Strophe context object's allocator. + * + * @param ctx a Strophe context object + * @param s a string + * + * @return a new allocates string with the same data as s or NULL on error + */ char *xmpp_strdup(const xmpp_ctx_t * const ctx, const char * const s) { size_t len; @@ -45,6 +58,13 @@ char *xmpp_strdup(const xmpp_ctx_t * const ctx, const char * const s) return copy; } +/** Return an integer based time stamp. + * This function uses gettimeofday or timeGetTime (on Win32 platforms) to + * compute an integer based time stamp. This is used internally by the + * event loop and timed handlers. + * + * @return an integer time stamp + */ uint64_t time_stamp(void) { #ifdef _WIN32 @@ -58,11 +78,28 @@ uint64_t time_stamp(void) #endif } +/** Get the time elapsed between two time stamps. + * This function returns the time elapsed between t1 and t2 by subtracting + * t1 from t2. If t2 happened before t1, the result will be negative. This + * function is used internally by the event loop and timed handlers. + * + * @param t1 first time stamp + * @param t2 second time stamp + * + * @return number of milliseconds between the stamps + */ uint64_t time_elapsed(uint64_t t1, uint64_t t2) { return (uint64_t)(t2 - t1); } +/** Disconnect the stream with a memory error. + * This is a convenience function used internally by various parts of + * the Strophe library for terminating the connection because of a + * memory error. + * + * @param conn a Strophe connection object + */ void disconnect_mem_error(xmpp_conn_t * const conn) { xmpp_error(conn->ctx, "xmpp", "Memory allocation error"); src/util.c b6027cfd7f19b44c8d32869740fdf1c2e249b37d Jack Moffitt jack@metajack.im http://github.com/dustin/libstrophe/commit/65a174ee7ef95ef402981f86cc4d6b7d304bb0a6 65a174ee7ef95ef402981f86cc4d6b7d304bb0a6 2008-06-24T07:43:54-07:00 2008-06-24T07:43:54-07:00 Most public API points are now documented. 34d230d422e13800a3bfaad8504e53e1a2af6b50 Jack Moffitt jack@metajack.im