Mercurial > pidgin.yaz
comparison libgaim/signals.h @ 14192:60b1bc8dbf37
[gaim-migrate @ 16863]
Renamed 'core' to 'libgaim'
committer: Tailor Script <tailor@pidgin.im>
author | Evan Schoenberg <evan.s@dreskin.net> |
---|---|
date | Sat, 19 Aug 2006 01:50:10 +0000 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
14191:009db0b357b5 | 14192:60b1bc8dbf37 |
---|---|
1 /** | |
2 * @file signals.h Signal API | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
7 * Gaim 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 _GAIM_SIGNALS_H_ | |
26 #define _GAIM_SIGNALS_H_ | |
27 | |
28 #include <glib.h> | |
29 #include "value.h" | |
30 | |
31 #define GAIM_CALLBACK(func) ((GaimCallback)func) | |
32 | |
33 typedef void (*GaimCallback)(void); | |
34 typedef void (*GaimSignalMarshalFunc)(GaimCallback cb, va_list args, | |
35 void *data, void **return_val); | |
36 | |
37 #ifdef __cplusplus | |
38 extern "C" { | |
39 #endif | |
40 | |
41 /**************************************************************************/ | |
42 /** @name Signal API */ | |
43 /**************************************************************************/ | |
44 /*@{*/ | |
45 | |
46 /** | |
47 * Signal Connect Priorities | |
48 */ | |
49 #define GAIM_SIGNAL_PRIORITY_DEFAULT 0 | |
50 #define GAIM_SIGNAL_PRIORITY_HIGHEST 9999 | |
51 #define GAIM_SIGNAL_PRIORITY_LOWEST -9999 | |
52 | |
53 /** | |
54 * Registers a signal in an instance. | |
55 * | |
56 * @param instance The instance to register the signal for. | |
57 * @param signal The signal name. | |
58 * @param marshal The marshal function. | |
59 * @param ret_value The return value type, or NULL for no return value. | |
60 * @param num_values The number of values to be passed to the callbacks. | |
61 * @param ... The values to pass to the callbacks. | |
62 * | |
63 * @return The signal ID local to that instance, or 0 if the signal | |
64 * couldn't be registered. | |
65 * | |
66 * @see GaimValue | |
67 */ | |
68 gulong gaim_signal_register(void *instance, const char *signal, | |
69 GaimSignalMarshalFunc marshal, | |
70 GaimValue *ret_value, int num_values, ...); | |
71 | |
72 /** | |
73 * Unregisters a signal in an instance. | |
74 * | |
75 * @param instance The instance to unregister the signal for. | |
76 * @param signal The signal name. | |
77 */ | |
78 void gaim_signal_unregister(void *instance, const char *signal); | |
79 | |
80 /** | |
81 * Unregisters all signals in an instance. | |
82 * | |
83 * @param instance The instance to unregister the signal for. | |
84 */ | |
85 void gaim_signals_unregister_by_instance(void *instance); | |
86 | |
87 /** | |
88 * Returns a list of value types used for a signal. | |
89 * | |
90 * @param instance The instance the signal is registered to. | |
91 * @param signal The signal. | |
92 * @param ret_value The return value from the last signal handler. | |
93 * @param num_values The returned number of values. | |
94 * @param values The returned list of values. | |
95 */ | |
96 void gaim_signal_get_values(void *instance, const char *signal, | |
97 GaimValue **ret_value, | |
98 int *num_values, GaimValue ***values); | |
99 | |
100 /** | |
101 * Connects a signal handler to a signal for a particular object. | |
102 * | |
103 * Take care not to register a handler function twice. Gaim will | |
104 * not correct any mistakes for you in this area. | |
105 * | |
106 * @param instance The instance to connect to. | |
107 * @param signal The name of the signal to connect. | |
108 * @param handle The handle of the receiver. | |
109 * @param func The callback function. | |
110 * @param data The data to pass to the callback function. | |
111 * @param priority The priority with which the handler should be called. Signal handlers are called | |
112 * in order from GAIM_SIGNAL_PRIORITY_LOWEST to GAIM_SIGNAL_PRIORITY_HIGHEST. | |
113 * | |
114 * @return The signal handler ID. | |
115 * | |
116 * @see gaim_signal_disconnect() | |
117 */ | |
118 gulong gaim_signal_connect_priority(void *instance, const char *signal, | |
119 void *handle, GaimCallback func, void *data, int priority); | |
120 | |
121 /** | |
122 * Connects a signal handler to a signal for a particular object. | |
123 * (priority defaults to 0) | |
124 * | |
125 * Take care not to register a handler function twice. Gaim will | |
126 * not correct any mistakes for you in this area. | |
127 * | |
128 * @param instance The instance to connect to. | |
129 * @param signal The name of the signal to connect. | |
130 * @param handle The handle of the receiver. | |
131 * @param func The callback function. | |
132 * @param data The data to pass to the callback function. | |
133 * | |
134 * @return The signal handler ID. | |
135 * | |
136 * @see gaim_signal_disconnect() | |
137 */ | |
138 gulong gaim_signal_connect(void *instance, const char *signal, | |
139 void *handle, GaimCallback func, void *data); | |
140 | |
141 /** | |
142 * Connects a signal handler to a signal for a particular object. | |
143 * | |
144 * The signal handler will take a va_args of arguments, instead of | |
145 * individual arguments. | |
146 * | |
147 * Take care not to register a handler function twice. Gaim will | |
148 * not correct any mistakes for you in this area. | |
149 * | |
150 * @param instance The instance to connect to. | |
151 * @param signal The name of the signal to connect. | |
152 * @param handle The handle of the receiver. | |
153 * @param func The callback function. | |
154 * @param data The data to pass to the callback function. | |
155 * @param priority The order in which the signal should be added to the list | |
156 * | |
157 * @return The signal handler ID. | |
158 * | |
159 * @see gaim_signal_disconnect() | |
160 */ | |
161 gulong gaim_signal_connect_priority_vargs(void *instance, const char *signal, | |
162 void *handle, GaimCallback func, void *data, int priority); | |
163 | |
164 /** | |
165 * Connects a signal handler to a signal for a particular object. | |
166 * (priority defaults to 0) | |
167 * The signal handler will take a va_args of arguments, instead of | |
168 * individual arguments. | |
169 * | |
170 * Take care not to register a handler function twice. Gaim will | |
171 * not correct any mistakes for you in this area. | |
172 * | |
173 * @param instance The instance to connect to. | |
174 * @param signal The name of the signal to connect. | |
175 * @param handle The handle of the receiver. | |
176 * @param func The callback function. | |
177 * @param data The data to pass to the callback function. | |
178 * | |
179 * @return The signal handler ID. | |
180 * | |
181 * @see gaim_signal_disconnect() | |
182 */ | |
183 gulong gaim_signal_connect_vargs(void *instance, const char *signal, | |
184 void *handle, GaimCallback func, void *data); | |
185 | |
186 /** | |
187 * Disconnects a signal handler from a signal on an object. | |
188 * | |
189 * @param instance The instance to disconnect from. | |
190 * @param signal The name of the signal to disconnect. | |
191 * @param handle The handle of the receiver. | |
192 * @param func The registered function to disconnect. | |
193 * | |
194 * @see gaim_signal_connect() | |
195 */ | |
196 void gaim_signal_disconnect(void *instance, const char *signal, | |
197 void *handle, GaimCallback func); | |
198 | |
199 /** | |
200 * Removes all callbacks associated with a receiver handle. | |
201 * | |
202 * @param handle The receiver handle. | |
203 */ | |
204 void gaim_signals_disconnect_by_handle(void *handle); | |
205 | |
206 /** | |
207 * Emits a signal. | |
208 * | |
209 * @param instance The instance emitting the signal. | |
210 * @param signal The signal being emitted. | |
211 * | |
212 * @see gaim_signal_connect() | |
213 * @see gaim_signal_disconnect() | |
214 */ | |
215 void gaim_signal_emit(void *instance, const char *signal, ...); | |
216 | |
217 /** | |
218 * Emits a signal, using a va_list of arguments. | |
219 * | |
220 * @param instance The instance emitting the signal. | |
221 * @param signal The signal being emitted. | |
222 * @param args The arguments list. | |
223 * | |
224 * @see gaim_signal_connect() | |
225 * @see gaim_signal_disconnect() | |
226 */ | |
227 void gaim_signal_emit_vargs(void *instance, const char *signal, va_list args); | |
228 | |
229 /** | |
230 * Emits a signal and returns the first non-NULL return value. | |
231 * | |
232 * Further signal handlers are NOT called after a handler returns | |
233 * something other than NULL. | |
234 * | |
235 * @param instance The instance emitting the signal. | |
236 * @param signal The signal being emitted. | |
237 * | |
238 * @return The first non-NULL return value | |
239 */ | |
240 void *gaim_signal_emit_return_1(void *instance, const char *signal, ...); | |
241 | |
242 /** | |
243 * Emits a signal and returns the first non-NULL return value. | |
244 * | |
245 * Further signal handlers are NOT called after a handler returns | |
246 * something other than NULL. | |
247 * | |
248 * @param instance The instance emitting the signal. | |
249 * @param signal The signal being emitted. | |
250 * @param args The arguments list. | |
251 * | |
252 * @return The first non-NULL return value | |
253 */ | |
254 void *gaim_signal_emit_vargs_return_1(void *instance, const char *signal, | |
255 va_list args); | |
256 | |
257 /** | |
258 * Initializes the signals subsystem. | |
259 */ | |
260 void gaim_signals_init(void); | |
261 | |
262 /** | |
263 * Uninitializes the signals subsystem. | |
264 */ | |
265 void gaim_signals_uninit(void); | |
266 | |
267 /*@}*/ | |
268 | |
269 /**************************************************************************/ | |
270 /** @name Marshal Functions */ | |
271 /**************************************************************************/ | |
272 /*@{*/ | |
273 | |
274 void gaim_marshal_VOID( | |
275 GaimCallback cb, va_list args, void *data, void **return_val); | |
276 void gaim_marshal_VOID__INT( | |
277 GaimCallback cb, va_list args, void *data, void **return_val); | |
278 void gaim_marshal_VOID__INT_INT( | |
279 GaimCallback cb, va_list args, void *data, void **return_val); | |
280 void gaim_marshal_VOID__POINTER( | |
281 GaimCallback cb, va_list args, void *data, void **return_val); | |
282 void gaim_marshal_VOID__POINTER_UINT( | |
283 GaimCallback cb, va_list args, void *data, void **return_val); | |
284 void gaim_marshal_VOID__POINTER_INT_INT( | |
285 GaimCallback cb, va_list args, void *data, void **return_val); | |
286 void gaim_marshal_VOID__POINTER_POINTER( | |
287 GaimCallback cb, va_list args, void *data, void **return_val); | |
288 void gaim_marshal_VOID__POINTER_POINTER_UINT( | |
289 GaimCallback cb, va_list args, void *data, void **return_val); | |
290 void gaim_marshal_VOID__POINTER_POINTER_UINT_UINT( | |
291 GaimCallback cb, va_list args, void *data, void **return_val); | |
292 void gaim_marshal_VOID__POINTER_POINTER_POINTER( | |
293 GaimCallback cb, va_list args, void *data, void **return_val); | |
294 void gaim_marshal_VOID__POINTER_POINTER_POINTER_POINTER( | |
295 GaimCallback cb, va_list args, void *data, void **return_val); | |
296 void gaim_marshal_VOID__POINTER_POINTER_POINTER_POINTER_POINTER( | |
297 GaimCallback cb, va_list args, void *data, void **return_val); | |
298 void gaim_marshal_VOID__POINTER_POINTER_POINTER_UINT( | |
299 GaimCallback cb, va_list args, void *data, void **return_val); | |
300 void gaim_marshal_VOID__POINTER_POINTER_POINTER_POINTER_UINT( | |
301 GaimCallback cb, va_list args, void *data, void **return_val); | |
302 void gaim_marshal_VOID__POINTER_POINTER_POINTER_UINT_UINT( | |
303 GaimCallback cb, va_list args, void *data, void **return_val); | |
304 | |
305 void gaim_marshal_INT__INT( | |
306 GaimCallback cb, va_list args, void *data, void **return_val); | |
307 void gaim_marshal_INT__INT_INT( | |
308 GaimCallback cb, va_list args, void *data, void **return_val); | |
309 void gaim_marshal_INT__POINTER_POINTER_POINTER_POINTER_POINTER( | |
310 GaimCallback cb, va_list args, void *data, void **return_val); | |
311 | |
312 void gaim_marshal_BOOLEAN__POINTER( | |
313 GaimCallback cb, va_list args, void *data, void **return_val); | |
314 void gaim_marshal_BOOLEAN__POINTER_POINTER( | |
315 GaimCallback cb, va_list args, void *data, void **return_val); | |
316 void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER( | |
317 GaimCallback cb, va_list args, void *data, void **return_val); | |
318 void gaim_marshal_BOOLEAN__POINTER_POINTER_UINT( | |
319 GaimCallback cb, va_list args, void *data, void **return_val); | |
320 void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER_UINT( | |
321 GaimCallback cb, va_list args, void *data, void **return_val); | |
322 void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER( | |
323 GaimCallback cb, va_list args, void *data, void **return_val); | |
324 void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER_POINTER( | |
325 GaimCallback cb, va_list args, void *data, void **return_val); | |
326 | |
327 void gaim_marshal_BOOLEAN__INT_POINTER( | |
328 GaimCallback cb, va_list args, void *data, void **return_val); | |
329 | |
330 void gaim_marshal_POINTER__POINTER_INT( | |
331 GaimCallback cb, va_list args, void *data, void **return_val); | |
332 void gaim_marshal_POINTER__POINTER_INT64( | |
333 GaimCallback cb, va_list args, void *data, void **return_val); | |
334 void gaim_marshal_POINTER__POINTER_POINTER( | |
335 GaimCallback cb, va_list args, void *data, void **return_val); | |
336 /*@}*/ | |
337 | |
338 #ifdef __cplusplus | |
339 } | |
340 #endif | |
341 | |
342 #endif /* _GAIM_SIGNALS_H_ */ |