comparison libpurple/eventloop.h @ 16177:d88f0f320c9b

merge of '07fc4db9a3c2c12596e0354b8e7959aa847f966b' and '2e6d324c725b3e6a2c803589bca3f0ac9b9790bf'
author Richard Laager <rlaager@wiktel.com>
date Mon, 16 Apr 2007 00:44:33 +0000
parents b449dc6b8a20
children 516f14bef90e
comparison
equal deleted inserted replaced
15938:2e3eba412412 16177:d88f0f320c9b
1 /**
2 * @file eventloop.h Purple Event Loop API
3 * @ingroup core
4 *
5 * purple
6 *
7 * Purple is the legal property of its developers, whose names are too numerous
8 * to list here. Please refer to the COPYRIGHT file distributed with this
9 * source distribution.
10 *
11 * This program is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; either version 2 of the License, or
14 * (at your option) any later version.
15 *
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, write to the Free Software
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 */
25 #ifndef _PURPLE_EVENTLOOP_H_
26 #define _PURPLE_EVENTLOOP_H_
27
28 #include <glib.h>
29
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33
34 /**
35 * An input condition.
36 */
37 typedef enum
38 {
39 PURPLE_INPUT_READ = 1 << 0, /**< A read condition. */
40 PURPLE_INPUT_WRITE = 1 << 1 /**< A write condition. */
41
42 } PurpleInputCondition;
43
44 typedef void (*PurpleInputFunction)(gpointer, gint, PurpleInputCondition);
45
46 typedef struct _PurpleEventLoopUiOps PurpleEventLoopUiOps;
47
48 struct _PurpleEventLoopUiOps
49 {
50 /**
51 * Creates a callback timer.
52 * @see g_timeout_add, purple_timeout_add
53 **/
54 guint (*timeout_add)(guint interval, GSourceFunc function, gpointer data);
55
56 /**
57 * Removes a callback timer.
58 * @see purple_timeout_remove, g_source_remove
59 */
60 gboolean (*timeout_remove)(guint handle);
61
62 /**
63 * Adds an input handler.
64 * @see purple_input_add, g_io_add_watch_full
65 */
66 guint (*input_add)(int fd, PurpleInputCondition cond,
67 PurpleInputFunction func, gpointer user_data);
68
69 /**
70 * Removes an input handler.
71 * @see purple_input_remove, g_source_remove
72 */
73 gboolean (*input_remove)(guint handle);
74
75
76 /**
77 * Get the current error status for an input.
78 * Implementation of this UI op is optional. Implement it if the UI's sockets
79 * or event loop needs to customize determination of socket error status.
80 * @see purple_input_get_error, getsockopt
81 */
82 int (*input_get_error)(int fd, int *error);
83
84 };
85
86 /**************************************************************************/
87 /** @name Event Loop API */
88 /**************************************************************************/
89 /*@{*/
90 /**
91 * Creates a callback timer.
92 * The timer will repeat until the function returns @c FALSE. The
93 * first call will be at the end of the first interval.
94 * @param interval The time between calls of the function, in
95 * milliseconds.
96 * @param function The function to call.
97 * @param data data to pass to @a function.
98 * @return A handle to the timer which can be passed to
99 * purple_timeout_remove to remove the timer.
100 */
101 guint purple_timeout_add(guint interval, GSourceFunc function, gpointer data);
102
103 /**
104 * Removes a timeout handler.
105 *
106 * @param handle The handle, as returned by purple_timeout_add.
107 *
108 * @return Something.
109 */
110 gboolean purple_timeout_remove(guint handle);
111
112 /**
113 * Adds an input handler.
114 *
115 * @param fd The input file descriptor.
116 * @param cond The condition type.
117 * @param func The callback function for data.
118 * @param user_data User-specified data.
119 *
120 * @return The resulting handle (will be greater than 0).
121 * @see g_io_add_watch_full
122 */
123 guint purple_input_add(int fd, PurpleInputCondition cond,
124 PurpleInputFunction func, gpointer user_data);
125
126 /**
127 * Removes an input handler.
128 *
129 * @param handle The handle of the input handler. Note that this is the return
130 * value from purple_input_add, <i>not</i> the file descriptor.
131 */
132 gboolean purple_input_remove(guint handle);
133
134 /**
135 * Get the current error status for an input.
136 * The return value and error follow getsockopt() with a level of SOL_SOCKET and an
137 * option name of SO_ERROR, and this is how the error is determined if the UI does not
138 * implement the input_get_error UI op.
139 *
140 * @param fd The input file descriptor.
141 * @param error A pointer to an int which on return will have the error, or 0 if no error.
142 *
143 * @return 0 if there is no error; -1 if there is an error, in which case errno will be set.
144 */
145 int
146 purple_input_get_error(int fd, int *error);
147
148
149 /*@}*/
150
151
152 /**************************************************************************/
153 /** @name UI Registration Functions */
154 /**************************************************************************/
155 /*@{*/
156 /**
157 * Sets the UI operations structure to be used for accounts.
158 *
159 * @param ops The UI operations structure.
160 */
161 void purple_eventloop_set_ui_ops(PurpleEventLoopUiOps *ops);
162
163 /**
164 * Returns the UI operations structure used for accounts.
165 *
166 * @return The UI operations structure in use.
167 */
168 PurpleEventLoopUiOps *purple_eventloop_get_ui_ops(void);
169
170 /*@}*/
171
172 #ifdef __cplusplus
173 }
174 #endif
175
176 #endif /* _PURPLE_EVENTLOOP_H_ */