libpurple/eventloop.h

   1 /**
   2  * @file eventloop.h Purple Event Loop API
   3  * @ingroup core
   4  */
   5
   6 /* purple
   7  *
   8  * Purple is the legal property of its developers, whose names are too numerous
   9  * to list here.  Please refer to the COPYRIGHT file distributed with this
  10  * source distribution.
  11  *
  12  * This program is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  25  */
  26 #ifndef _PURPLE_EVENTLOOP_H_
  27 #define _PURPLE_EVENTLOOP_H_
  28
  29 #include <glib.h>
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /**
  36  * An input condition.
  37  */
  38 typedef enum
  39 {
  40         PURPLE_INPUT_READ  = 1 << 0,  /**< A read condition.  */
  41         PURPLE_INPUT_WRITE = 1 << 1   /**< A write condition. */
  42
  43 } PurpleInputCondition;
  44
  45 /** The type of callbacks to handle events on file descriptors, as passed to
  46  *  purple_input_add().  The callback will receive the @c user_data passed to
  47  *  purple_input_add(), the file descriptor on which the event occurred, and the
  48  *  condition that was satisfied to cause the callback to be invoked.
  49  */
  50 typedef void (*PurpleInputFunction)(gpointer, gint, PurpleInputCondition);
  51
  52 /** @copydoc _PurpleEventLoopUiOps */
  53 typedef struct _PurpleEventLoopUiOps PurpleEventLoopUiOps;
  54
  55 /** An abstraction of an application's mainloop; libpurple will use this to
  56  *  watch file descriptors and schedule timed callbacks.  If your application
  57  *  uses the glib mainloop, there is an implementation of this struct in
  58  *  <tt>libpurple/example/nullclient.c</tt> which you can use verbatim.
  59  */
  60 struct _PurpleEventLoopUiOps
  61 {
  62         /**
  63          * Should create a callback timer with an interval measured in
  64          * milliseconds.  The supplied @a function should be called every @a
  65          * interval seconds until it returns @c FALSE, after which it should not
  66          * be called again.
  67          *
  68          * Analogous to g_timeout_add in glib.
  69          *
  70          * Note: On Win32, this function may be called from a thread other than
  71          * the libpurple thread.  You should make sure to detect this situation
  72          * and to only call "function" from the libpurple thread.
  73          *
  74          * @param interval the interval in <em>milliseconds</em> between calls
  75          *                 to @a function.
  76          * @param data     arbitrary data to be passed to @a function at each
  77          *                 call.
  78          * @todo Who is responsible for freeing @a data?
  79          *
  80          * @return a handle for the timeout, which can be passed to
  81          *         #timeout_remove.
  82          *
  83          * @see purple_timeout_add
  84          **/
  85         guint (*timeout_add)(guint interval, GSourceFunc function, gpointer data);
  86
  87         /**
  88          * Should remove a callback timer.  Analogous to g_source_remove in glib.
  89          * @param handle an identifier for a timeout, as returned by
  90          *               #timeout_add.
  91          * @return       @c TRUE if the timeout identified by @a handle was
  92          *               found and removed.
  93          * @see purple_timeout_remove
  94          */
  95         gboolean (*timeout_remove)(guint handle);
  96
  97         /**
  98          * Should add an input handler.  Analogous to g_io_add_watch_full in
  99          * glib.
 100          *
 101          * @param fd        a file descriptor to watch for events
 102          * @param cond      a bitwise OR of events on @a fd for which @a func
 103          *                  should be called.
 104          * @param func      a callback to fire whenever a relevant event on @a
 105          *                  fd occurs.
 106          * @param user_data arbitrary data to pass to @a fd.
 107          * @return          an identifier for this input handler, which can be
 108          *                  passed to #input_remove.
 109          *
 110          * @see purple_input_add
 111          */
 112         guint (*input_add)(int fd, PurpleInputCondition cond,
 113                            PurpleInputFunction func, gpointer user_data);
 114
 115         /**
 116          * Should remove an input handler.  Analogous to g_source_remove in glib.
 117          * @param handle an identifier, as returned by #input_add.
 118          * @return       @c TRUE if the input handler was found and removed.
 119          * @see purple_input_remove
 120          */
 121         gboolean (*input_remove)(guint handle);
 122
 123
 124         /**
 125          * If implemented, should get the current error status for an input.
 126          *
 127          * Implementation of this UI op is optional. Implement it if the UI's
 128          * sockets or event loop needs to customize determination of socket
 129          * error status.  If unimplemented, <tt>getsockopt(2)</tt> will be used
 130          * instead.
 131          *
 132          * @see purple_input_get_error
 133          */
 134         int (*input_get_error)(int fd, int *error);
 135
 136         /**
 137          * If implemented, should create a callback timer with an interval
 138          * measured in seconds.  Analogous to g_timeout_add_seconds in glib.
 139          *
 140          * This allows UIs to group timers for better power efficiency.  For
 141          * this reason, @a interval may be rounded by up to a second.
 142          *
 143          * Implementation of this UI op is optional.  If it's not implemented,
 144          * calls to purple_timeout_add_seconds() will be serviced by
 145          * #timeout_add.
 146          *
 147          * @see purple_timeout_add_seconds()
 148          * @since 2.1.0
 149          **/
 150         guint (*timeout_add_seconds)(guint interval, GSourceFunc function,
 151                                      gpointer data);
 152
 153         void (*_purple_reserved2)(void);
 154         void (*_purple_reserved3)(void);
 155         void (*_purple_reserved4)(void);
 156 };
 157
 158 /**************************************************************************/
 159 /** @name Event Loop API                                                  */
 160 /**************************************************************************/
 161 /*@{*/
 162 /**
 163  * Creates a callback timer.
 164  *
 165  * The timer will repeat until the function returns @c FALSE. The
 166  * first call will be at the end of the first interval.
 167  *
 168  * If the timer is in a multiple of seconds, use purple_timeout_add_seconds()
 169  * instead as it allows UIs to group timers for power efficiency.
 170  *
 171  * @param interval      The time between calls of the function, in
 172  *                      milliseconds.
 173  * @param function      The function to call.
 174  * @param data          data to pass to @a function.
 175  * @return A handle to the timer which can be passed to
 176  *         purple_timeout_remove() to remove the timer.
 177  */
 178 guint purple_timeout_add(guint interval, GSourceFunc function, gpointer data);
 179
 180 /**
 181  * Creates a callback timer.
 182  *
 183  * The timer will repeat until the function returns @c FALSE. The
 184  * first call will be at the end of the first interval.
 185  *
 186  * This function allows UIs to group timers for better power efficiency.  For
 187  * this reason, @a interval may be rounded by up to a second.
 188  *
 189  * @param interval      The time between calls of the function, in
 190  *                      seconds.
 191  * @param function      The function to call.
 192  * @param data          data to pass to @a function.
 193  * @return A handle to the timer which can be passed to
 194  *         purple_timeout_remove() to remove the timer.
 195  *
 196  * @since 2.1.0
 197  */
 198 guint purple_timeout_add_seconds(guint interval, GSourceFunc function, gpointer data);
 199
 200 /**
 201  * Removes a timeout handler.
 202  *
 203  * @param handle The handle, as returned by purple_timeout_add().
 204  *
 205  * @return @c TRUE if the handler was successfully removed.
 206  */
 207 gboolean purple_timeout_remove(guint handle);
 208
 209 /**
 210  * Adds an input handler.
 211  *
 212  * @param fd        The input file descriptor.
 213  * @param cond      The condition type.
 214  * @param func      The callback function for data.
 215  * @param user_data User-specified data.
 216  *
 217  * @return The resulting handle (will be greater than 0).
 218  * @see g_io_add_watch_full
 219  */
 220 guint purple_input_add(int fd, PurpleInputCondition cond,
 221                        PurpleInputFunction func, gpointer user_data);
 222
 223 /**
 224  * Removes an input handler.
 225  *
 226  * @param handle The handle of the input handler. Note that this is the return
 227  *               value from purple_input_add(), <i>not</i> the file descriptor.
 228  */
 229 gboolean purple_input_remove(guint handle);
 230
 231 /**
 232  * Get the current error status for an input.
 233  *
 234  * The return value and error follow getsockopt() with a level of SOL_SOCKET and an
 235  * option name of SO_ERROR, and this is how the error is determined if the UI does not
 236  * implement the input_get_error UI op.
 237  *
 238  * @param fd        The input file descriptor.
 239  * @param error     A pointer to an @c int which on return will have the error, or
 240  *                  @c 0 if no error.
 241  *
 242  * @return @c 0 if there is no error; @c -1 if there is an error, in which case
 243  *         @a errno will be set.
 244  */
 245 int
 246 purple_input_get_error(int fd, int *error);
 247
 248
 249 /*@}*/
 250
 251
 252 /**************************************************************************/
 253 /** @name UI Registration Functions                                       */
 254 /**************************************************************************/
 255 /*@{*/
 256 /**
 257  * Sets the UI operations structure to be used for accounts.
 258  *
 259  * @param ops The UI operations structure.
 260  */
 261 void purple_eventloop_set_ui_ops(PurpleEventLoopUiOps *ops);
 262
 263 /**
 264  * Returns the UI operations structure used for accounts.
 265  *
 266  * @return The UI operations structure in use.
 267  */
 268 PurpleEventLoopUiOps *purple_eventloop_get_ui_ops(void);
 269
 270 /*@}*/
 271
 272 #ifdef __cplusplus
 273 }
 274 #endif
 275
 276 #endif /* _PURPLE_EVENTLOOP_H_ */