14192
+ �� 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_ */