Mercurial > pidgin
annotate src/signals.h @ 8849:50d0f76639e7
[gaim-migrate @ 9616]
Let there be SILC.
committer: Tailor Script <tailor@pidgin.im>
author | Ethan Blanton <elb@pidgin.im> |
---|---|
date | Sat, 01 May 2004 19:34:44 +0000 |
parents | fa6395637e2c |
children | 1fac0336890c |
rev | line source |
---|---|
6485 | 1 /** |
6488
e5e8d21bd4d8
[gaim-migrate @ 7002]
Christian Hammond <chipx86@chipx86.com>
parents:
6485
diff
changeset
|
2 * @file signals.h Signal API |
6485 | 3 * @ingroup core |
4 * | |
5 * gaim | |
6 * | |
8046 | 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. | |
6485 | 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_SIGNAL_H_ | |
26 #define _GAIM_SIGNAL_H_ | |
27 | |
28 #include <glib.h> | |
6564
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
29 #include "value.h" |
6485 | 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 * Registers a signal in an instance. | |
48 * | |
6720
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6564
diff
changeset
|
49 * @param instance The instance to register the signal for. |
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6564
diff
changeset
|
50 * @param signal The signal name. |
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6564
diff
changeset
|
51 * @param marshal The marshal function. |
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6564
diff
changeset
|
52 * @param ret_value The return value type, or NULL for no return value. |
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6564
diff
changeset
|
53 * @param num_values The number of values to be passed to the callbacks. |
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6564
diff
changeset
|
54 * @param ... The values to pass to the callbacks. |
6485 | 55 * |
56 * @return The signal ID local to that instance, or 0 if the signal | |
57 * couldn't be registered. | |
6564
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
58 * |
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
59 * @see GaimValue |
6485 | 60 */ |
61 gulong gaim_signal_register(void *instance, const char *signal, | |
6564
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
62 GaimSignalMarshalFunc marshal, |
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
63 GaimValue *ret_value, int num_values, ...); |
6485 | 64 |
65 /** | |
66 * Unregisters a signal in an instance. | |
67 * | |
68 * @param instance The instance to unregister the signal for. | |
69 * @param signal The signal name. | |
70 */ | |
71 void gaim_signal_unregister(void *instance, const char *signal); | |
72 | |
73 /** | |
74 * Unregisters all signals in an instance. | |
75 * | |
76 * @param instance The instance to unregister the signal for. | |
77 */ | |
78 void gaim_signals_unregister_by_instance(void *instance); | |
79 | |
80 /** | |
6564
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
81 * Returns a list of value types used for a signal. |
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
82 * |
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
83 * @param instance The instance the signal is registered to. |
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
84 * @param signal The signal. |
6720
41120df7ed94
[gaim-migrate @ 7247]
Christian Hammond <chipx86@chipx86.com>
parents:
6564
diff
changeset
|
85 * @param ret_value The return value from the last signal handler. |
6564
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
86 * @param num_values The returned number of values. |
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
87 * @param values The returned list of values. |
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
88 */ |
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
89 void gaim_signal_get_values(void *instance, const char *signal, |
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
90 GaimValue **ret_value, |
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
91 int *num_values, GaimValue ***values); |
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
92 |
800ef4a51096
[gaim-migrate @ 7086]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
93 /** |
6485 | 94 * Connects a signal handler to a signal for a particular object. |
95 * | |
96 * Take care not to register a handler function twice. Gaim will | |
97 * not correct any mistakes for you in this area. | |
98 * | |
99 * @param instance The instance to connect to. | |
100 * @param signal The name of the signal to connect. | |
101 * @param handle The handle of the receiver. | |
102 * @param func The callback function. | |
103 * @param data The data to pass to the callback function. | |
104 * | |
105 * @return The signal handler ID. | |
106 * | |
107 * @see gaim_signal_disconnect() | |
108 */ | |
109 gulong gaim_signal_connect(void *instance, const char *signal, | |
110 void *handle, GaimCallback func, void *data); | |
111 | |
112 /** | |
6548
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
113 * Connects a signal handler to a signal for a particular object. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
114 * |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
115 * The signal handler will take a va_args of arguments, instead of |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
116 * individual arguments. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
117 * |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
118 * Take care not to register a handler function twice. Gaim will |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
119 * not correct any mistakes for you in this area. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
120 * |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
121 * @param instance The instance to connect to. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
122 * @param signal The name of the signal to connect. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
123 * @param handle The handle of the receiver. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
124 * @param func The callback function. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
125 * @param data The data to pass to the callback function. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
126 * |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
127 * @return The signal handler ID. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
128 * |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
129 * @see gaim_signal_disconnect() |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
130 */ |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
131 gulong gaim_signal_connect_vargs(void *instance, const char *signal, |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
132 void *handle, GaimCallback func, void *data); |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
133 |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
134 /** |
6485 | 135 * Disconnects a signal handler from a signal on an object. |
136 * | |
137 * @param instance The instance to disconnect from. | |
138 * @param signal The name of the signal to disconnect. | |
139 * @param handle The handle of the receiver. | |
140 * @param func The registered function to disconnect. | |
141 * | |
142 * @see gaim_signal_connect() | |
143 */ | |
144 void gaim_signal_disconnect(void *instance, const char *signal, | |
145 void *handle, GaimCallback func); | |
146 | |
147 /** | |
148 * Removes all callbacks associated with a receiver handle. | |
149 * | |
150 * @param handle The receiver handle. | |
151 */ | |
152 void gaim_signals_disconnect_by_handle(void *handle); | |
153 | |
154 /** | |
155 * Emits a signal. | |
156 * | |
157 * @param instance The instance emitting the signal. | |
158 * @param signal The signal being emitted. | |
159 * | |
160 * @see gaim_signal_connect() | |
161 * @see gaim_signal_disconnect() | |
162 */ | |
163 void gaim_signal_emit(void *instance, const char *signal, ...); | |
164 | |
165 /** | |
166 * Emits a signal, using a va_list of arguments. | |
167 * | |
168 * @param instance The instance emitting the signal. | |
169 * @param signal The signal being emitted. | |
170 * @param args The arguments list. | |
171 * | |
172 * @see gaim_signal_connect() | |
173 * @see gaim_signal_disconnect() | |
174 */ | |
175 void gaim_signal_emit_vargs(void *instance, const char *signal, va_list args); | |
176 | |
177 /** | |
178 * Emits a signal and returns the return value from the last handler. | |
179 * | |
180 * @param instance The instance emitting the signal. | |
181 * @param signal The signal being emitted. | |
182 * | |
183 * @return The return value from the last handler. | |
184 */ | |
185 void *gaim_signal_emit_return_1(void *instance, const char *signal, ...); | |
186 | |
187 /** | |
188 * Emits a signal and returns the return value from the last handler. | |
189 * | |
190 * @param instance The instance emitting the signal. | |
191 * @param signal The signal being emitted. | |
192 * @param args The arguments list. | |
193 * | |
194 * @return The return value from the last handler. | |
195 */ | |
196 void *gaim_signal_emit_vargs_return_1(void *instance, const char *signal, | |
197 va_list args); | |
198 | |
199 /** | |
200 * Initializes the signals subsystem. | |
201 */ | |
202 void gaim_signals_init(); | |
203 | |
204 /** | |
205 * Uninitializes the signals subsystem. | |
206 */ | |
207 void gaim_signals_uninit(); | |
208 | |
209 /*@}*/ | |
210 | |
211 /**************************************************************************/ | |
212 /** @name Marshal Functions */ | |
213 /**************************************************************************/ | |
214 /*@{*/ | |
215 | |
216 void gaim_marshal_VOID( | |
217 GaimCallback cb, va_list args, void *data, void **return_val); | |
6822
7dba3e17cb21
[gaim-migrate @ 7366]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
218 void gaim_marshal_VOID__INT( |
7dba3e17cb21
[gaim-migrate @ 7366]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
219 GaimCallback cb, va_list args, void *data, void **return_val); |
7dba3e17cb21
[gaim-migrate @ 7366]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
220 void gaim_marshal_VOID__INT_INT( |
7dba3e17cb21
[gaim-migrate @ 7366]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
221 GaimCallback cb, va_list args, void *data, void **return_val); |
6485 | 222 void gaim_marshal_VOID__POINTER( |
223 GaimCallback cb, va_list args, void *data, void **return_val); | |
224 void gaim_marshal_VOID__POINTER_POINTER( | |
225 GaimCallback cb, va_list args, void *data, void **return_val); | |
226 void gaim_marshal_VOID__POINTER_POINTER_UINT( | |
227 GaimCallback cb, va_list args, void *data, void **return_val); | |
228 void gaim_marshal_VOID__POINTER_POINTER_POINTER( | |
229 GaimCallback cb, va_list args, void *data, void **return_val); | |
230 void gaim_marshal_VOID__POINTER_POINTER_POINTER_POINTER( | |
231 GaimCallback cb, va_list args, void *data, void **return_val); | |
6509 | 232 void gaim_marshal_VOID__POINTER_POINTER_POINTER_UINT( |
233 GaimCallback cb, va_list args, void *data, void **return_val); | |
6485 | 234 void gaim_marshal_VOID__POINTER_POINTER_POINTER_UINT_UINT( |
235 GaimCallback cb, va_list args, void *data, void **return_val); | |
236 | |
6822
7dba3e17cb21
[gaim-migrate @ 7366]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
237 void gaim_marshal_INT__INT( |
7dba3e17cb21
[gaim-migrate @ 7366]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
238 GaimCallback cb, va_list args, void *data, void **return_val); |
7dba3e17cb21
[gaim-migrate @ 7366]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
239 void gaim_marshal_INT__INT_INT( |
7dba3e17cb21
[gaim-migrate @ 7366]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
240 GaimCallback cb, va_list args, void *data, void **return_val); |
7dba3e17cb21
[gaim-migrate @ 7366]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
241 |
6485 | 242 void gaim_marshal_BOOLEAN__POINTER( |
243 GaimCallback cb, va_list args, void *data, void **return_val); | |
244 void gaim_marshal_BOOLEAN__POINTER_POINTER( | |
245 GaimCallback cb, va_list args, void *data, void **return_val); | |
6509 | 246 void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER( |
247 GaimCallback cb, va_list args, void *data, void **return_val); | |
248 void gaim_marshal_BOOLEAN__POINTER_POINTER_UINT( | |
249 GaimCallback cb, va_list args, void *data, void **return_val); | |
6485 | 250 void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER_UINT( |
251 GaimCallback cb, va_list args, void *data, void **return_val); | |
252 void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER( | |
253 GaimCallback cb, va_list args, void *data, void **return_val); | |
254 void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER_POINTER( | |
255 GaimCallback cb, va_list args, void *data, void **return_val); | |
256 | |
257 /*@}*/ | |
258 | |
259 #ifdef __cplusplus | |
260 } | |
261 #endif | |
262 | |
263 #endif /* _GAIM_SIGNAL_H_ */ |