Mercurial > pidgin.yaz
comparison libpurple/eventloop.h @ 25635:efaecb71baad
propagate from branch 'im.pidgin.pidgin' (head 8ca6a80e2cd7fbbc59983f8ba370f7276e062db9)
to branch 'im.pidgin.pidgin.vv' (head 3ed39e8792f4a2e92ef5a3c7f4fb14251c9dae11)
author | Sadrul Habib Chowdhury <imadil@gmail.com> |
---|---|
date | Sat, 15 Mar 2008 07:39:15 +0000 |
parents | e3bf822c19c8 |
children | 3d7e9eff04d0 |
comparison
equal
deleted
inserted
replaced
25634:741a702033e0 | 25635:efaecb71baad |
---|---|
40 PURPLE_INPUT_READ = 1 << 0, /**< A read condition. */ | 40 PURPLE_INPUT_READ = 1 << 0, /**< A read condition. */ |
41 PURPLE_INPUT_WRITE = 1 << 1 /**< A write condition. */ | 41 PURPLE_INPUT_WRITE = 1 << 1 /**< A write condition. */ |
42 | 42 |
43 } PurpleInputCondition; | 43 } PurpleInputCondition; |
44 | 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 */ | |
45 typedef void (*PurpleInputFunction)(gpointer, gint, PurpleInputCondition); | 50 typedef void (*PurpleInputFunction)(gpointer, gint, PurpleInputCondition); |
46 | 51 |
52 /** @copydoc _PurpleEventLoopUiOps */ | |
47 typedef struct _PurpleEventLoopUiOps PurpleEventLoopUiOps; | 53 typedef struct _PurpleEventLoopUiOps PurpleEventLoopUiOps; |
48 | 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 */ | |
49 struct _PurpleEventLoopUiOps | 60 struct _PurpleEventLoopUiOps |
50 { | 61 { |
51 /** | 62 /** |
52 * Creates a callback timer with an interval measured in milliseconds. | 63 * Should create a callback timer with an interval measured in |
53 * @see g_timeout_add, purple_timeout_add | 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 * @param interval the interval in <em>milliseconds</em> between calls | |
71 * to @a function. | |
72 * @param data arbitrary data to be passed to @a function at each | |
73 * call. | |
74 * @todo Who is responsible for freeing @a data? | |
75 * | |
76 * @return a handle for the timeout, which can be passed to | |
77 * #timeout_remove. | |
78 * | |
79 * @see purple_timeout_add | |
54 **/ | 80 **/ |
55 guint (*timeout_add)(guint interval, GSourceFunc function, gpointer data); | 81 guint (*timeout_add)(guint interval, GSourceFunc function, gpointer data); |
56 | 82 |
57 /** | 83 /** |
58 * Removes a callback timer. | 84 * Should remove a callback timer. Analogous to g_source_remove in glib. |
59 * @see purple_timeout_remove, g_source_remove | 85 * @param handle an identifier for a timeout, as returned by |
86 * #timeout_add. | |
87 * @return @c TRUE if the timeout identified by @a handle was | |
88 * found and removed. | |
89 * @see purple_timeout_remove | |
60 */ | 90 */ |
61 gboolean (*timeout_remove)(guint handle); | 91 gboolean (*timeout_remove)(guint handle); |
62 | 92 |
63 /** | 93 /** |
64 * Adds an input handler. | 94 * Should add an input handler. Analogous to g_io_add_watch_full in |
65 * @see purple_input_add, g_io_add_watch_full | 95 * glib. |
96 * | |
97 * @param fd a file descriptor to watch for events | |
98 * @param cond a bitwise OR of events on @a fd for which @a func | |
99 * should be called. | |
100 * @param func a callback to fire whenever a relevant event on @a | |
101 * fd occurs. | |
102 * @param user_data arbitrary data to pass to @a fd. | |
103 * @return an identifier for this input handler, which can be | |
104 * passed to #input_remove. | |
105 * | |
106 * @see purple_input_add | |
66 */ | 107 */ |
67 guint (*input_add)(int fd, PurpleInputCondition cond, | 108 guint (*input_add)(int fd, PurpleInputCondition cond, |
68 PurpleInputFunction func, gpointer user_data); | 109 PurpleInputFunction func, gpointer user_data); |
69 | 110 |
70 /** | 111 /** |
71 * Removes an input handler. | 112 * Should remove an input handler. Analogous to g_source_remove in glib. |
72 * @see purple_input_remove, g_source_remove | 113 * @param handle an identifier, as returned by #input_add. |
114 * @return @c TRUE if the input handler was found and removed. | |
115 * @see purple_input_remove | |
73 */ | 116 */ |
74 gboolean (*input_remove)(guint handle); | 117 gboolean (*input_remove)(guint handle); |
75 | 118 |
76 | 119 |
77 /** | 120 /** |
78 * Get the current error status for an input. | 121 * If implemented, should get the current error status for an input. |
79 * Implementation of this UI op is optional. Implement it if the UI's sockets | 122 * |
80 * or event loop needs to customize determination of socket error status. | 123 * Implementation of this UI op is optional. Implement it if the UI's |
81 * @see purple_input_get_error, getsockopt | 124 * sockets or event loop needs to customize determination of socket |
125 * error status. If unimplemented, <tt>getsockopt(2)</tt> will be used | |
126 * instead. | |
127 * | |
128 * @see purple_input_get_error | |
82 */ | 129 */ |
83 int (*input_get_error)(int fd, int *error); | 130 int (*input_get_error)(int fd, int *error); |
84 | 131 |
85 /** | 132 /** |
86 * Creates a callback timer with an interval measured in seconds. | 133 * If implemented, should create a callback timer with an interval |
134 * measured in seconds. Analogous to g_timeout_add_seconds in glib. | |
87 * | 135 * |
88 * This allows UIs to group timers for better power efficiency. For | 136 * This allows UIs to group timers for better power efficiency. For |
89 * this reason, @a interval may be rounded by up to a second. | 137 * this reason, @a interval may be rounded by up to a second. |
90 * | 138 * |
91 * Implementation of this UI op is optional. If it's not implemented, | 139 * Implementation of this UI op is optional. If it's not implemented, |
92 * calls to purple_timeout_add_seconds() will be serviced by the | 140 * calls to purple_timeout_add_seconds() will be serviced by |
93 * timeout_add UI op. | 141 * #timeout_add. |
94 * | 142 * |
95 * @see g_timeout_add_seconds, purple_timeout_add_seconds() | 143 * @see purple_timeout_add_seconds() |
96 **/ | 144 **/ |
97 guint (*timeout_add_seconds)(guint interval, GSourceFunc function, gpointer data); | 145 guint (*timeout_add_seconds)(guint interval, GSourceFunc function, |
146 gpointer data); | |
98 | 147 |
99 void (*_purple_reserved2)(void); | 148 void (*_purple_reserved2)(void); |
100 void (*_purple_reserved3)(void); | 149 void (*_purple_reserved3)(void); |
101 void (*_purple_reserved4)(void); | 150 void (*_purple_reserved4)(void); |
102 }; | 151 }; |
116 * | 165 * |
117 * @param interval The time between calls of the function, in | 166 * @param interval The time between calls of the function, in |
118 * milliseconds. | 167 * milliseconds. |
119 * @param function The function to call. | 168 * @param function The function to call. |
120 * @param data data to pass to @a function. | 169 * @param data data to pass to @a function. |
121 * @return A handle to the timer which can be passed to | 170 * @return A handle to the timer which can be passed to |
122 * purple_timeout_remove to remove the timer. | 171 * purple_timeout_remove() to remove the timer. |
123 */ | 172 */ |
124 guint purple_timeout_add(guint interval, GSourceFunc function, gpointer data); | 173 guint purple_timeout_add(guint interval, GSourceFunc function, gpointer data); |
125 | 174 |
126 /** | 175 /** |
127 * Creates a callback timer. | 176 * Creates a callback timer. |
135 * @param interval The time between calls of the function, in | 184 * @param interval The time between calls of the function, in |
136 * seconds. | 185 * seconds. |
137 * @param function The function to call. | 186 * @param function The function to call. |
138 * @param data data to pass to @a function. | 187 * @param data data to pass to @a function. |
139 * @return A handle to the timer which can be passed to | 188 * @return A handle to the timer which can be passed to |
140 * purple_timeout_remove to remove the timer. | 189 * purple_timeout_remove() to remove the timer. |
141 * | 190 * |
142 * @since 2.1.0 | 191 * @since 2.1.0 |
143 */ | 192 */ |
144 guint purple_timeout_add_seconds(guint interval, GSourceFunc function, gpointer data); | 193 guint purple_timeout_add_seconds(guint interval, GSourceFunc function, gpointer data); |
145 | 194 |
146 /** | 195 /** |
147 * Removes a timeout handler. | 196 * Removes a timeout handler. |
148 * | 197 * |
149 * @param handle The handle, as returned by purple_timeout_add. | 198 * @param handle The handle, as returned by purple_timeout_add(). |
150 * | 199 * |
151 * @return Something. | 200 * @return @c TRUE if the handler was successfully removed. |
152 */ | 201 */ |
153 gboolean purple_timeout_remove(guint handle); | 202 gboolean purple_timeout_remove(guint handle); |
154 | 203 |
155 /** | 204 /** |
156 * Adds an input handler. | 205 * Adds an input handler. |
162 * | 211 * |
163 * @return The resulting handle (will be greater than 0). | 212 * @return The resulting handle (will be greater than 0). |
164 * @see g_io_add_watch_full | 213 * @see g_io_add_watch_full |
165 */ | 214 */ |
166 guint purple_input_add(int fd, PurpleInputCondition cond, | 215 guint purple_input_add(int fd, PurpleInputCondition cond, |
167 PurpleInputFunction func, gpointer user_data); | 216 PurpleInputFunction func, gpointer user_data); |
168 | 217 |
169 /** | 218 /** |
170 * Removes an input handler. | 219 * Removes an input handler. |
171 * | 220 * |
172 * @param handle The handle of the input handler. Note that this is the return | 221 * @param handle The handle of the input handler. Note that this is the return |
173 * value from purple_input_add, <i>not</i> the file descriptor. | 222 * value from purple_input_add(), <i>not</i> the file descriptor. |
174 */ | 223 */ |
175 gboolean purple_input_remove(guint handle); | 224 gboolean purple_input_remove(guint handle); |
176 | 225 |
177 /** | 226 /** |
178 * Get the current error status for an input. | 227 * Get the current error status for an input. |
228 * | |
179 * The return value and error follow getsockopt() with a level of SOL_SOCKET and an | 229 * The return value and error follow getsockopt() with a level of SOL_SOCKET and an |
180 * option name of SO_ERROR, and this is how the error is determined if the UI does not | 230 * option name of SO_ERROR, and this is how the error is determined if the UI does not |
181 * implement the input_get_error UI op. | 231 * implement the input_get_error UI op. |
182 * | 232 * |
183 * @param fd The input file descriptor. | 233 * @param fd The input file descriptor. |
184 * @param error A pointer to an int which on return will have the error, or 0 if no error. | 234 * @param error A pointer to an @c int which on return will have the error, or |
185 * | 235 * @c 0 if no error. |
186 * @return 0 if there is no error; -1 if there is an error, in which case errno will be set. | 236 * |
237 * @return @c 0 if there is no error; @c -1 if there is an error, in which case | |
238 * @a errno will be set. | |
187 */ | 239 */ |
188 int | 240 int |
189 purple_input_get_error(int fd, int *error); | 241 purple_input_get_error(int fd, int *error); |
190 | 242 |
191 | 243 |