Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/eventloop.h
branchadium-1.5.11
changeset 6014 fcb71cb71a3d
parent 5941 307f53385811
parent 6013 f8d0dc659e3f
child 6016 325e2ab3406f
equal deleted inserted replaced
5941:307f53385811 6014:fcb71cb71a3d
     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_ */