src/event.h

   1 /**
   2  * @file event.h Event API
   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_EVENT_H_
  24 #define _GAIM_EVENT_H_
  25
  26 #include <glib.h>
  27
  28 /**
  29  * Event types
  30  */
  31 typedef enum gaim_event
  32 {
  33         event_signon = 0,
  34         event_signoff,
  35         event_away,
  36         event_back,
  37         event_im_recv,
  38         event_im_send,
  39         event_buddy_signon,
  40         event_buddy_signoff,
  41         event_buddy_away,
  42         event_buddy_back,
  43         event_buddy_idle,
  44         event_buddy_unidle,
  45         event_blist_update,
  46         event_chat_invited,
  47         event_chat_join,
  48         event_chat_leave,
  49         event_chat_buddy_join,
  50         event_chat_buddy_leave,
  51         event_chat_recv,
  52         event_chat_send,
  53         event_warned,
  54         event_error,
  55         event_quit,
  56         event_new_conversation,
  57         event_set_info,
  58         event_draw_menu,
  59         event_im_displayed_sent,
  60         event_im_displayed_rcvd,
  61         event_chat_send_invite,
  62         event_got_typing,
  63         event_del_conversation,
  64         event_connecting,
  65         /* any others? it's easy to add... */
  66
  67 } GaimEvent;
  68
  69 typedef int (*GaimSignalBroadcastFunc)(GaimEvent event, void *data,
  70                                                                            va_list args);
  71
  72 /**
  73  * Connects a signal handler to a gaim event.
  74  *
  75  * @param module The optional module handle.
  76  * @param event  The event to connect to.
  77  * @param func   The callback function.
  78  * @param data   The data to pass to the callback function.
  79  *
  80  * @see gaim_signal_disconnect()
  81  */
  82 void gaim_signal_connect(void *module, GaimEvent event,
  83                                                  void *func, void *data);
  84
  85 /**
  86  * Disconnects a signal handler from a gaim event.
  87  *
  88  * @param module The optional module handle.
  89  * @param event  The event to disconnect from.
  90  * @param func   The registered function to disconnect.
  91  *
  92  * @see gaim_signal_connect()
  93  */
  94 void gaim_signal_disconnect(void *module, GaimEvent event,
  95                                                         void *func);
  96
  97 /**
  98  * Removes all callbacks associated with a handle.
  99  *
 100  * @param handle The handle.
 101  */
 102 void gaim_signals_disconnect_by_handle(void *handle);
 103
 104 /**
 105  * Registers a function that re-broadcasts events.
 106  *
 107  * @param func The function.
 108  * @param data Data to be passed to the callback.
 109  */
 110 void gaim_signals_register_broadcast_func(GaimSignalBroadcastFunc func,
 111                                                                                   void *data);
 112
 113 /**
 114  * Unregisters a function that re-broadcasts events.
 115  *
 116  * @param func The function.
 117  */
 118 void gaim_signals_unregister_broadcast_func(GaimSignalBroadcastFunc func);
 119
 120 /**
 121  * Returns a list of all signal callbacks.
 122  *
 123  * @return A list of all signal callbacks.
 124  */
 125 GList *gaim_signals_get_callbacks(void);
 126
 127 /**
 128  * Broadcasts an event to all registered signal handlers.
 129  *
 130  * @param event The event to broadcast
 131  *
 132  * @see gaim_signal_connect()
 133  * @see gaim_signal_disconnect()
 134  */
 135 int gaim_event_broadcast(GaimEvent event, ...);
 136
 137 /**
 138  * Returns a human-readable representation of an event name.
 139  *
 140  * @param event The event.
 141  *
 142  * @return A human-readable string of the name.
 143  */
 144 const char *gaim_event_get_name(GaimEvent event);
 145
 146 #endif /* _GAIM_EVENT_H_ */