libpurple/signals.h

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