libpurple/signals.h

   1 /**
   2  * @file signals.h Signal API
   3  * @ingroup core
   4  */
   5
   6 /* purple
   7  *
   8  * Purple is the legal property of its developers, whose names are too numerous
   9  * to list here.  Please refer to the COPYRIGHT file distributed with this
  10  * source distribution.
  11  *
  12  * This program is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  25  */
  26 #ifndef _PURPLE_SIGNALS_H_
  27 #define _PURPLE_SIGNALS_H_
  28
  29 #include <glib.h>
  30 #include "value.h"
  31
  32 #define PURPLE_CALLBACK(func) ((PurpleCallback)func)
  33
  34 typedef void (*PurpleCallback)(void);
  35 typedef void (*PurpleSignalMarshalFunc)(PurpleCallback cb, va_list args,
  36                                                                           void *data, void **return_val);
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42 /**************************************************************************/
  43 /** @name Signal API                                                      */
  44 /**************************************************************************/
  45 /*@{*/
  46
  47 /** The priority of a signal connected using purple_signal_connect().
  48  *
  49  *  @see purple_signal_connect_priority()
  50  */
  51 #define PURPLE_SIGNAL_PRIORITY_DEFAULT     0
  52 /** The largest signal priority; signals with this priority will be called
  53  *  <em>last</em>.  (This is highest as in numerical value, not as in order of
  54  *  importance.)
  55  *
  56  *  @see purple_signal_connect_priority().
  57  */
  58 #define PURPLE_SIGNAL_PRIORITY_HIGHEST  9999
  59 /** The smallest signal priority; signals with this priority will be called
  60  *  <em>first</em>.  (This is lowest as in numerical value, not as in order of
  61  *  importance.)
  62  *
  63  *  @see purple_signal_connect_priority().
  64  */
  65 #define PURPLE_SIGNAL_PRIORITY_LOWEST  -9999
  66
  67 /**
  68  * Registers a signal in an instance.
  69  *
  70  * @param instance   The instance to register the signal for.
  71  * @param signal     The signal name.
  72  * @param marshal    The marshal function.
  73  * @param ret_value  The return value type, or NULL for no return value.
  74  * @param num_values The number of values to be passed to the callbacks.
  75  * @param ...        The values to pass to the callbacks.
  76  *
  77  * @return The signal ID local to that instance, or 0 if the signal
  78  *         couldn't be registered.
  79  *
  80  * @see PurpleValue
  81  */
  82 gulong purple_signal_register(void *instance, const char *signal,
  83                                                         PurpleSignalMarshalFunc marshal,
  84                                                         PurpleValue *ret_value, int num_values, ...);
  85
  86 /**
  87  * Unregisters a signal in an instance.
  88  *
  89  * @param instance The instance to unregister the signal for.
  90  * @param signal   The signal name.
  91  */
  92 void purple_signal_unregister(void *instance, const char *signal);
  93
  94 /**
  95  * Unregisters all signals in an instance.
  96  *
  97  * @param instance The instance to unregister the signal for.
  98  */
  99 void purple_signals_unregister_by_instance(void *instance);
 100
 101 /**
 102  * Returns a list of value types used for a signal.
 103  *
 104  * @param instance   The instance the signal is registered to.
 105  * @param signal     The signal.
 106  * @param ret_value  The return value from the last signal handler.
 107  * @param num_values The returned number of values.
 108  * @param values     The returned list of values.
 109  */
 110 void purple_signal_get_values(void *instance, const char *signal,
 111                                                         PurpleValue **ret_value,
 112                                                         int *num_values, PurpleValue ***values);
 113
 114 /**
 115  * Connects a signal handler to a signal for a particular object.
 116  *
 117  * Take care not to register a handler function twice. Purple will
 118  * not correct any mistakes for you in this area.
 119  *
 120  * @param instance The instance to connect to.
 121  * @param signal   The name of the signal to connect.
 122  * @param handle   The handle of the receiver.
 123  * @param func     The callback function.
 124  * @param data     The data to pass to the callback function.
 125  * @param priority The priority with which the handler should be called. Signal
 126  *                 handlers are called in ascending numerical order of @a
 127  *                 priority from #PURPLE_SIGNAL_PRIORITY_LOWEST to
 128  *                 #PURPLE_SIGNAL_PRIORITY_HIGHEST.
 129  *
 130  * @return The signal handler ID.
 131  *
 132  * @see purple_signal_disconnect()
 133  */
 134 gulong purple_signal_connect_priority(void *instance, const char *signal,
 135         void *handle, PurpleCallback func, void *data, int priority);
 136
 137 /**
 138  * Connects a signal handler to a signal for a particular object.
 139  * (Its priority defaults to 0, aka #PURPLE_SIGNAL_PRIORITY_DEFAULT.)
 140  *
 141  * Take care not to register a handler function twice. Purple will
 142  * not correct any mistakes for you in this area.
 143  *
 144  * @param instance The instance to connect to.
 145  * @param signal   The name of the signal to connect.
 146  * @param handle   The handle of the receiver.
 147  * @param func     The callback function.
 148  * @param data     The data to pass to the callback function.
 149  *
 150  * @return The signal handler ID.
 151  *
 152  * @see purple_signal_disconnect()
 153  */
 154 gulong purple_signal_connect(void *instance, const char *signal,
 155         void *handle, PurpleCallback func, void *data);
 156
 157 /**
 158  * Connects a signal handler to a signal for a particular object.
 159  *
 160  * The signal handler will take a va_args of arguments, instead of
 161  * individual arguments.
 162  *
 163  * Take care not to register a handler function twice. Purple will
 164  * not correct any mistakes for you in this area.
 165  *
 166  * @param instance The instance to connect to.
 167  * @param signal   The name of the signal to connect.
 168  * @param handle   The handle of the receiver.
 169  * @param func     The callback function.
 170  * @param data     The data to pass to the callback function.
 171  * @param priority The priority with which the handler should be called. Signal
 172  *                 handlers are called in ascending numerical order of @a
 173  *                 priority from #PURPLE_SIGNAL_PRIORITY_LOWEST to
 174  *                 #PURPLE_SIGNAL_PRIORITY_HIGHEST.
 175  *
 176  * @return The signal handler ID.
 177  *
 178  * @see purple_signal_disconnect()
 179  */
 180 gulong purple_signal_connect_priority_vargs(void *instance, const char *signal,
 181         void *handle, PurpleCallback func, void *data, int priority);
 182
 183 /**
 184  * Connects a signal handler to a signal for a particular object.
 185  * (Its priority defaults to 0, aka #PURPLE_SIGNAL_PRIORITY_DEFAULT.)
 186  *
 187  * The signal handler will take a va_args of arguments, instead of
 188  * individual arguments.
 189  *
 190  * Take care not to register a handler function twice. Purple will
 191  * not correct any mistakes for you in this area.
 192  *
 193  * @param instance The instance to connect to.
 194  * @param signal   The name of the signal to connect.
 195  * @param handle   The handle of the receiver.
 196  * @param func     The callback function.
 197  * @param data     The data to pass to the callback function.
 198  *
 199  * @return The signal handler ID.
 200  *
 201  * @see purple_signal_disconnect()
 202  */
 203 gulong purple_signal_connect_vargs(void *instance, const char *signal,
 204         void *handle, PurpleCallback func, void *data);
 205
 206 /**
 207  * Disconnects a signal handler from a signal on an object.
 208  *
 209  * @param instance The instance to disconnect from.
 210  * @param signal   The name of the signal to disconnect.
 211  * @param handle   The handle of the receiver.
 212  * @param func     The registered function to disconnect.
 213  *
 214  * @see purple_signal_connect()
 215  */
 216 void purple_signal_disconnect(void *instance, const char *signal,
 217                                                         void *handle, PurpleCallback func);
 218
 219 /**
 220  * Removes all callbacks associated with a receiver handle.
 221  *
 222  * @param handle The receiver handle.
 223  */
 224 void purple_signals_disconnect_by_handle(void *handle);
 225
 226 /**
 227  * Emits a signal.
 228  *
 229  * @param instance The instance emitting the signal.
 230  * @param signal   The signal being emitted.
 231  *
 232  * @see purple_signal_connect()
 233  * @see purple_signal_disconnect()
 234  */
 235 void purple_signal_emit(void *instance, const char *signal, ...);
 236
 237 /**
 238  * Emits a signal, using a va_list of arguments.
 239  *
 240  * @param instance The instance emitting the signal.
 241  * @param signal   The signal being emitted.
 242  * @param args     The arguments list.
 243  *
 244  * @see purple_signal_connect()
 245  * @see purple_signal_disconnect()
 246  */
 247 void purple_signal_emit_vargs(void *instance, const char *signal, va_list args);
 248
 249 /**
 250  * Emits a signal and returns the first non-NULL return value.
 251  *
 252  * Further signal handlers are NOT called after a handler returns
 253  * something other than NULL.
 254  *
 255  * @param instance The instance emitting the signal.
 256  * @param signal   The signal being emitted.
 257  *
 258  * @return The first non-NULL return value
 259  */
 260 void *purple_signal_emit_return_1(void *instance, const char *signal, ...);
 261
 262 /**
 263  * Emits a signal and returns the first non-NULL return value.
 264  *
 265  * Further signal handlers are NOT called after a handler returns
 266  * something other than NULL.
 267  *
 268  * @param instance The instance emitting the signal.
 269  * @param signal   The signal being emitted.
 270  * @param args     The arguments list.
 271  *
 272  * @return The first non-NULL return value
 273  */
 274 void *purple_signal_emit_vargs_return_1(void *instance, const char *signal,
 275                                                                           va_list args);
 276
 277 /**
 278  * Initializes the signals subsystem.
 279  */
 280 void purple_signals_init(void);
 281
 282 /**
 283  * Uninitializes the signals subsystem.
 284  */
 285 void purple_signals_uninit(void);
 286
 287 /*@}*/
 288
 289 /**************************************************************************/
 290 /** @name Marshal Functions                                               */
 291 /**************************************************************************/
 292 /*@{*/
 293
 294 void purple_marshal_VOID(
 295                 PurpleCallback cb, va_list args, void *data, void **return_val);
 296 void purple_marshal_VOID__INT(
 297                 PurpleCallback cb, va_list args, void *data, void **return_val);
 298 void purple_marshal_VOID__INT_INT(
 299                 PurpleCallback cb, va_list args, void *data, void **return_val);
 300 void purple_marshal_VOID__POINTER(
 301                 PurpleCallback cb, va_list args, void *data, void **return_val);
 302 void purple_marshal_VOID__POINTER_UINT(
 303                 PurpleCallback cb, va_list args, void *data, void **return_val);
 304 void purple_marshal_VOID__POINTER_INT_INT(
 305                 PurpleCallback cb, va_list args, void *data, void **return_val);
 306 void purple_marshal_VOID__POINTER_INT_POINTER(
 307                 PurpleCallback cb, va_list args, void *data, void **return_val);
 308 void purple_marshal_VOID__POINTER_POINTER(
 309                 PurpleCallback cb, va_list args, void *data, void **return_val);
 310 void purple_marshal_VOID__POINTER_POINTER_UINT(
 311                 PurpleCallback cb, va_list args, void *data, void **return_val);
 312 void purple_marshal_VOID__POINTER_POINTER_UINT_UINT(
 313                 PurpleCallback cb, va_list args, void *data, void **return_val);
 314 void purple_marshal_VOID__POINTER_POINTER_POINTER(
 315                 PurpleCallback cb, va_list args, void *data, void **return_val);
 316 void purple_marshal_VOID__POINTER_POINTER_POINTER_POINTER(
 317                 PurpleCallback cb, va_list args, void *data, void **return_val);
 318 void purple_marshal_VOID__POINTER_POINTER_POINTER_POINTER_POINTER(
 319                 PurpleCallback cb, va_list args, void *data, void **return_val);
 320 void purple_marshal_VOID__POINTER_POINTER_POINTER_UINT(
 321                 PurpleCallback cb, va_list args, void *data, void **return_val);
 322 void purple_marshal_VOID__POINTER_POINTER_POINTER_POINTER_UINT(
 323                 PurpleCallback cb, va_list args, void *data, void **return_val);
 324 void purple_marshal_VOID__POINTER_POINTER_POINTER_UINT_UINT(
 325                 PurpleCallback cb, va_list args, void *data, void **return_val);
 326
 327 void purple_marshal_INT__INT(
 328                 PurpleCallback cb, va_list args, void *data, void **return_val);
 329 void purple_marshal_INT__INT_INT(
 330                 PurpleCallback cb, va_list args, void *data, void **return_val);
 331 void purple_marshal_INT__POINTER_POINTER(
 332                 PurpleCallback cb, va_list args, void *data, void **return_val);
 333 void purple_marshal_INT__POINTER_POINTER_POINTER_POINTER_POINTER(
 334                 PurpleCallback cb, va_list args, void *data, void **return_val);
 335
 336 void purple_marshal_BOOLEAN__POINTER(
 337                 PurpleCallback cb, va_list args, void *data, void **return_val);
 338 void purple_marshal_BOOLEAN__POINTER_POINTER(
 339                 PurpleCallback cb, va_list args, void *data, void **return_val);
 340 void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER(
 341                 PurpleCallback cb, va_list args, void *data, void **return_val);
 342 void purple_marshal_BOOLEAN__POINTER_POINTER_UINT(
 343                 PurpleCallback cb, va_list args, void *data, void **return_val);
 344 void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_UINT(
 345                 PurpleCallback cb, va_list args, void *data, void **return_val);
 346 void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER(
 347                 PurpleCallback cb, va_list args, void *data, void **return_val);
 348 void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER_POINTER(
 349                 PurpleCallback cb, va_list args, void *data, void **return_val);
 350 void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER_UINT(
 351                 PurpleCallback cb, va_list args, void *data, void **return_val);
 352 void purple_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER_POINTER_POINTER(
 353                 PurpleCallback cb, va_list args, void *data, void **return_val);
 354
 355 void purple_marshal_BOOLEAN__INT_POINTER(
 356                 PurpleCallback cb, va_list args, void *data, void **return_val);
 357
 358 void purple_marshal_POINTER__POINTER_INT(
 359                 PurpleCallback cb, va_list args, void *data, void **return_val);
 360 void purple_marshal_POINTER__POINTER_INT64(
 361                 PurpleCallback cb, va_list args, void *data, void **return_val);
 362 void purple_marshal_POINTER__POINTER_INT_BOOLEAN(
 363                 PurpleCallback cb, va_list args, void *data, void **return_val);
 364 void purple_marshal_POINTER__POINTER_INT64_BOOLEAN(
 365                 PurpleCallback cb, va_list args, void *data, void **return_val);
 366 void purple_marshal_POINTER__POINTER_POINTER(
 367                 PurpleCallback cb, va_list args, void *data, void **return_val);
 368 /*@}*/
 369
 370 #ifdef __cplusplus
 371 }
 372 #endif
 373
 374 #endif /* _PURPLE_SIGNALS_H_ */