# HG changeset patch # User Will Thompson # Date 1204299948 0 # Node ID e3bf822c19c8afed778c64495fce3c6693bc191c # Parent 25a1d6fe9074d4027076222c9e3aec32283e75af Document PurpleEventLoopUiOps and associated misc. diff -r 25a1d6fe9074 -r e3bf822c19c8 doc/ui-ops.dox --- a/doc/ui-ops.dox Fri Feb 29 14:47:34 2008 +0000 +++ b/doc/ui-ops.dox Fri Feb 29 15:45:48 2008 +0000 @@ -10,7 +10,7 @@ - #PurpleCoreUiOps - #PurpleDebugUiOps - #PurpleDnsQueryUiOps - - #PurpleEventLoopUiOps + - #PurpleEventLoopUiOps (without this, nothing will work and you will cry) - #PurpleIdleUiOps - #PurpleNotifyUiOps - #PurplePrivacyUiOps diff -r 25a1d6fe9074 -r e3bf822c19c8 libpurple/eventloop.h --- a/libpurple/eventloop.h Fri Feb 29 14:47:34 2008 +0000 +++ b/libpurple/eventloop.h Fri Feb 29 15:45:48 2008 +0000 @@ -42,59 +42,108 @@ } PurpleInputCondition; +/** The type of callbacks to handle events on file descriptors, as passed to + * purple_input_add(). The callback will receive the @c user_data passed to + * purple_input_add(), the file descriptor on which the event occurred, and the + * condition that was satisfied to cause the callback to be invoked. + */ typedef void (*PurpleInputFunction)(gpointer, gint, PurpleInputCondition); +/** @copydoc _PurpleEventLoopUiOps */ typedef struct _PurpleEventLoopUiOps PurpleEventLoopUiOps; +/** An abstraction of an application's mainloop; libpurple will use this to + * watch file descriptors and schedule timed callbacks. If your application + * uses the glib mainloop, there is an implementation of this struct in + * libpurple/example/nullclient.c which you can use verbatim. + */ struct _PurpleEventLoopUiOps { /** - * Creates a callback timer with an interval measured in milliseconds. - * @see g_timeout_add, purple_timeout_add + * Should create a callback timer with an interval measured in + * milliseconds. The supplied @a function should be called every @a + * interval seconds until it returns @c FALSE, after which it should not + * be called again. + * + * Analogous to g_timeout_add in glib. + * + * @param interval the interval in milliseconds between calls + * to @a function. + * @param data arbitrary data to be passed to @a function at each + * call. + * @todo Who is responsible for freeing @a data? + * + * @return a handle for the timeout, which can be passed to + * #timeout_remove. + * + * @see purple_timeout_add **/ guint (*timeout_add)(guint interval, GSourceFunc function, gpointer data); /** - * Removes a callback timer. - * @see purple_timeout_remove, g_source_remove + * Should remove a callback timer. Analogous to g_source_remove in glib. + * @param handle an identifier for a timeout, as returned by + * #timeout_add. + * @return @c TRUE if the timeout identified by @a handle was + * found and removed. + * @see purple_timeout_remove */ gboolean (*timeout_remove)(guint handle); /** - * Adds an input handler. - * @see purple_input_add, g_io_add_watch_full + * Should add an input handler. Analogous to g_io_add_watch_full in + * glib. + * + * @param fd a file descriptor to watch for events + * @param cond a bitwise OR of events on @a fd for which @a func + * should be called. + * @param func a callback to fire whenever a relevant event on @a + * fd occurs. + * @param user_data arbitrary data to pass to @a fd. + * @return an identifier for this input handler, which can be + * passed to #input_remove. + * + * @see purple_input_add */ guint (*input_add)(int fd, PurpleInputCondition cond, - PurpleInputFunction func, gpointer user_data); + PurpleInputFunction func, gpointer user_data); /** - * Removes an input handler. - * @see purple_input_remove, g_source_remove + * Should remove an input handler. Analogous to g_source_remove in glib. + * @param handle an identifier, as returned by #input_add. + * @return @c TRUE if the input handler was found and removed. + * @see purple_input_remove */ gboolean (*input_remove)(guint handle); /** - * Get the current error status for an input. - * Implementation of this UI op is optional. Implement it if the UI's sockets - * or event loop needs to customize determination of socket error status. - * @see purple_input_get_error, getsockopt + * If implemented, should get the current error status for an input. + * + * Implementation of this UI op is optional. Implement it if the UI's + * sockets or event loop needs to customize determination of socket + * error status. If unimplemented, getsockopt(2) will be used + * instead. + * + * @see purple_input_get_error */ int (*input_get_error)(int fd, int *error); /** - * Creates a callback timer with an interval measured in seconds. + * If implemented, should create a callback timer with an interval + * measured in seconds. Analogous to g_timeout_add_seconds in glib. * * This allows UIs to group timers for better power efficiency. For * this reason, @a interval may be rounded by up to a second. * * Implementation of this UI op is optional. If it's not implemented, - * calls to purple_timeout_add_seconds() will be serviced by the - * timeout_add UI op. + * calls to purple_timeout_add_seconds() will be serviced by + * #timeout_add. * - * @see g_timeout_add_seconds, purple_timeout_add_seconds() + * @see purple_timeout_add_seconds() **/ - guint (*timeout_add_seconds)(guint interval, GSourceFunc function, gpointer data); + guint (*timeout_add_seconds)(guint interval, GSourceFunc function, + gpointer data); void (*_purple_reserved2)(void); void (*_purple_reserved3)(void); @@ -118,8 +167,8 @@ * milliseconds. * @param function The function to call. * @param data data to pass to @a function. - * @return A handle to the timer which can be passed to - * purple_timeout_remove to remove the timer. + * @return A handle to the timer which can be passed to + * purple_timeout_remove() to remove the timer. */ guint purple_timeout_add(guint interval, GSourceFunc function, gpointer data); @@ -137,7 +186,7 @@ * @param function The function to call. * @param data data to pass to @a function. * @return A handle to the timer which can be passed to - * purple_timeout_remove to remove the timer. + * purple_timeout_remove() to remove the timer. * * @since 2.1.0 */ @@ -146,9 +195,9 @@ /** * Removes a timeout handler. * - * @param handle The handle, as returned by purple_timeout_add. + * @param handle The handle, as returned by purple_timeout_add(). * - * @return Something. + * @return @c TRUE if the handler was successfully removed. */ gboolean purple_timeout_remove(guint handle); @@ -164,26 +213,29 @@ * @see g_io_add_watch_full */ guint purple_input_add(int fd, PurpleInputCondition cond, - PurpleInputFunction func, gpointer user_data); + PurpleInputFunction func, gpointer user_data); /** * Removes an input handler. * * @param handle The handle of the input handler. Note that this is the return - * value from purple_input_add, not the file descriptor. + * value from purple_input_add(), not the file descriptor. */ gboolean purple_input_remove(guint handle); /** * Get the current error status for an input. + * * The return value and error follow getsockopt() with a level of SOL_SOCKET and an * option name of SO_ERROR, and this is how the error is determined if the UI does not * implement the input_get_error UI op. * * @param fd The input file descriptor. - * @param error A pointer to an int which on return will have the error, or 0 if no error. + * @param error A pointer to an @c int which on return will have the error, or + * @c 0 if no error. * - * @return 0 if there is no error; -1 if there is an error, in which case errno will be set. + * @return @c 0 if there is no error; @c -1 if there is an error, in which case + * @a errno will be set. */ int purple_input_get_error(int fd, int *error);