Mercurial > pidgin.yaz
annotate src/signals.h @ 6562:c53a3f0649eb
[gaim-migrate @ 7084]
New GaimValue structure. We'll be using this for signals and stuff shortly.
committer: Tailor Script <tailor@pidgin.im>
author | Christian Hammond <chipx86@chipx86.com> |
---|---|
date | Thu, 21 Aug 2003 20:29:33 +0000 |
parents | d01ba50e3f3e |
children | 800ef4a51096 |
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 * | |
7 * Copyright (C) 2003 Christian Hammond <chipx86@gnupdate.org> | |
8 * | |
9 * This program is free software; you can redistribute it and/or modify | |
10 * it under the terms of the GNU General Public License as published by | |
11 * the Free Software Foundation; either version 2 of the License, or | |
12 * (at your option) any later version. | |
13 * | |
14 * This program is distributed in the hope that it will be useful, | |
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 * GNU General Public License for more details. | |
18 * | |
19 * You should have received a copy of the GNU General Public License | |
20 * along with this program; if not, write to the Free Software | |
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
22 */ | |
23 #ifndef _GAIM_SIGNAL_H_ | |
24 #define _GAIM_SIGNAL_H_ | |
25 | |
26 #include <glib.h> | |
27 | |
28 #define GAIM_CALLBACK(func) ((GaimCallback)func) | |
29 | |
30 typedef void (*GaimCallback)(void); | |
31 typedef void (*GaimSignalMarshalFunc)(GaimCallback cb, va_list args, | |
32 void *data, void **return_val); | |
33 | |
34 #ifdef __cplusplus | |
35 extern "C" { | |
36 #endif | |
37 | |
38 /**************************************************************************/ | |
39 /** @name Signal API */ | |
40 /**************************************************************************/ | |
41 /*@{*/ | |
42 | |
43 /** | |
44 * Registers a signal in an instance. | |
45 * | |
46 * @param instance The instance to register the signal for. | |
47 * @param signal The signal name. | |
48 * @param marshal The marshal function. | |
49 * | |
50 * @return The signal ID local to that instance, or 0 if the signal | |
51 * couldn't be registered. | |
52 */ | |
53 gulong gaim_signal_register(void *instance, const char *signal, | |
54 GaimSignalMarshalFunc marshal); | |
55 | |
56 /** | |
57 * Unregisters a signal in an instance. | |
58 * | |
59 * @param instance The instance to unregister the signal for. | |
60 * @param signal The signal name. | |
61 */ | |
62 void gaim_signal_unregister(void *instance, const char *signal); | |
63 | |
64 /** | |
65 * Unregisters all signals in an instance. | |
66 * | |
67 * @param instance The instance to unregister the signal for. | |
68 */ | |
69 void gaim_signals_unregister_by_instance(void *instance); | |
70 | |
71 /** | |
72 * Connects a signal handler to a signal for a particular object. | |
73 * | |
74 * Take care not to register a handler function twice. Gaim will | |
75 * not correct any mistakes for you in this area. | |
76 * | |
77 * @param instance The instance to connect to. | |
78 * @param signal The name of the signal to connect. | |
79 * @param handle The handle of the receiver. | |
80 * @param func The callback function. | |
81 * @param data The data to pass to the callback function. | |
82 * | |
83 * @return The signal handler ID. | |
84 * | |
85 * @see gaim_signal_disconnect() | |
86 */ | |
87 gulong gaim_signal_connect(void *instance, const char *signal, | |
88 void *handle, GaimCallback func, void *data); | |
89 | |
90 /** | |
6548
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
91 * Connects a signal handler to a signal for a particular object. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
92 * |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
93 * 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
|
94 * individual arguments. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
95 * |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
96 * Take care not to register a handler function twice. Gaim will |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
97 * not correct any mistakes for you in this area. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
98 * |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
99 * @param instance The instance to connect to. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
100 * @param signal The name of the signal to connect. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
101 * @param handle The handle of the receiver. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
102 * @param func The callback function. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
103 * @param data The data to pass to the callback function. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
104 * |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
105 * @return The signal handler ID. |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
106 * |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
107 * @see gaim_signal_disconnect() |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
108 */ |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
109 gulong gaim_signal_connect_vargs(void *instance, const char *signal, |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
110 void *handle, GaimCallback func, void *data); |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
111 |
d01ba50e3f3e
[gaim-migrate @ 7070]
Christian Hammond <chipx86@chipx86.com>
parents:
6509
diff
changeset
|
112 /** |
6485 | 113 * Disconnects a signal handler from a signal on an object. |
114 * | |
115 * @param instance The instance to disconnect from. | |
116 * @param signal The name of the signal to disconnect. | |
117 * @param handle The handle of the receiver. | |
118 * @param func The registered function to disconnect. | |
119 * | |
120 * @see gaim_signal_connect() | |
121 */ | |
122 void gaim_signal_disconnect(void *instance, const char *signal, | |
123 void *handle, GaimCallback func); | |
124 | |
125 /** | |
126 * Removes all callbacks associated with a receiver handle. | |
127 * | |
128 * @param handle The receiver handle. | |
129 */ | |
130 void gaim_signals_disconnect_by_handle(void *handle); | |
131 | |
132 /** | |
133 * Emits a signal. | |
134 * | |
135 * @param instance The instance emitting the signal. | |
136 * @param signal The signal being emitted. | |
137 * | |
138 * @see gaim_signal_connect() | |
139 * @see gaim_signal_disconnect() | |
140 */ | |
141 void gaim_signal_emit(void *instance, const char *signal, ...); | |
142 | |
143 /** | |
144 * Emits a signal, using a va_list of arguments. | |
145 * | |
146 * @param instance The instance emitting the signal. | |
147 * @param signal The signal being emitted. | |
148 * @param args The arguments list. | |
149 * | |
150 * @see gaim_signal_connect() | |
151 * @see gaim_signal_disconnect() | |
152 */ | |
153 void gaim_signal_emit_vargs(void *instance, const char *signal, va_list args); | |
154 | |
155 /** | |
156 * Emits a signal and returns the return value from the last handler. | |
157 * | |
158 * @param instance The instance emitting the signal. | |
159 * @param signal The signal being emitted. | |
160 * | |
161 * @return The return value from the last handler. | |
162 */ | |
163 void *gaim_signal_emit_return_1(void *instance, const char *signal, ...); | |
164 | |
165 /** | |
166 * Emits a signal and returns the return value from the last handler. | |
167 * | |
168 * @param instance The instance emitting the signal. | |
169 * @param signal The signal being emitted. | |
170 * @param args The arguments list. | |
171 * | |
172 * @return The return value from the last handler. | |
173 */ | |
174 void *gaim_signal_emit_vargs_return_1(void *instance, const char *signal, | |
175 va_list args); | |
176 | |
177 /** | |
178 * Initializes the signals subsystem. | |
179 */ | |
180 void gaim_signals_init(); | |
181 | |
182 /** | |
183 * Uninitializes the signals subsystem. | |
184 */ | |
185 void gaim_signals_uninit(); | |
186 | |
187 /*@}*/ | |
188 | |
189 /**************************************************************************/ | |
190 /** @name Marshal Functions */ | |
191 /**************************************************************************/ | |
192 /*@{*/ | |
193 | |
194 void gaim_marshal_VOID( | |
195 GaimCallback cb, va_list args, void *data, void **return_val); | |
196 void gaim_marshal_VOID__POINTER( | |
197 GaimCallback cb, va_list args, void *data, void **return_val); | |
198 void gaim_marshal_VOID__POINTER_POINTER( | |
199 GaimCallback cb, va_list args, void *data, void **return_val); | |
200 void gaim_marshal_VOID__POINTER_POINTER_UINT( | |
201 GaimCallback cb, va_list args, void *data, void **return_val); | |
202 void gaim_marshal_VOID__POINTER_POINTER_POINTER( | |
203 GaimCallback cb, va_list args, void *data, void **return_val); | |
204 void gaim_marshal_VOID__POINTER_POINTER_POINTER_POINTER( | |
205 GaimCallback cb, va_list args, void *data, void **return_val); | |
6509 | 206 void gaim_marshal_VOID__POINTER_POINTER_POINTER_UINT( |
207 GaimCallback cb, va_list args, void *data, void **return_val); | |
6485 | 208 void gaim_marshal_VOID__POINTER_POINTER_POINTER_UINT_UINT( |
209 GaimCallback cb, va_list args, void *data, void **return_val); | |
210 | |
211 void gaim_marshal_BOOLEAN__POINTER( | |
212 GaimCallback cb, va_list args, void *data, void **return_val); | |
213 void gaim_marshal_BOOLEAN__POINTER_POINTER( | |
214 GaimCallback cb, va_list args, void *data, void **return_val); | |
6509 | 215 void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER( |
216 GaimCallback cb, va_list args, void *data, void **return_val); | |
217 void gaim_marshal_BOOLEAN__POINTER_POINTER_UINT( | |
218 GaimCallback cb, va_list args, void *data, void **return_val); | |
6485 | 219 void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER_UINT( |
220 GaimCallback cb, va_list args, void *data, void **return_val); | |
221 void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER( | |
222 GaimCallback cb, va_list args, void *data, void **return_val); | |
223 void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER_POINTER( | |
224 GaimCallback cb, va_list args, void *data, void **return_val); | |
225 | |
226 /*@}*/ | |
227 | |
228 #ifdef __cplusplus | |
229 } | |
230 #endif | |
231 | |
232 #endif /* _GAIM_SIGNAL_H_ */ |