comparison: src/pounce.h
src/pounce.h
- branch
- gaim
- changeset 20470
- 77693555855f
- parent 13071
- b98e72d4089a
- parent 20469
- b2836a24d81e
- child 20471
- 1966704b3e42
equal
deleted
inserted
replaced
| 13071:b98e72d4089a | 20470:77693555855f |
|---|---|
| 1 /** | |
| 2 * @file pounce.h Buddy Pounce 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_POUNCE_H_ | |
| 26 #define _GAIM_POUNCE_H_ | |
| 27 | |
| 28 typedef struct _GaimPounce GaimPounce; | |
| 29 | |
| 30 #include <glib.h> | |
| 31 #include "account.h" | |
| 32 | |
| 33 /** | |
| 34 * Events that trigger buddy pounces. | |
| 35 */ | |
| 36 typedef enum | |
| 37 { | |
| 38 GAIM_POUNCE_NONE = 0x00, /**< No events. */ | |
| 39 GAIM_POUNCE_SIGNON = 0x01, /**< The buddy signed on. */ | |
| 40 GAIM_POUNCE_SIGNOFF = 0x02, /**< The buddy signed off. */ | |
| 41 GAIM_POUNCE_AWAY = 0x04, /**< The buddy went away. */ | |
| 42 GAIM_POUNCE_AWAY_RETURN = 0x08, /**< The buddy returned from away. */ | |
| 43 GAIM_POUNCE_IDLE = 0x10, /**< The buddy became idle. */ | |
| 44 GAIM_POUNCE_IDLE_RETURN = 0x20, /**< The buddy is no longer idle. */ | |
| 45 GAIM_POUNCE_TYPING = 0x40, /**< The buddy started typing. */ | |
| 46 GAIM_POUNCE_TYPING_STOPPED = 0x80, /**< The buddy stopped typing. */ | |
| 47 GAIM_POUNCE_MESSAGE_RECEIVED = 0x100 /**< The buddy sent a message */ | |
| 48 | |
| 49 } GaimPounceEvent; | |
| 50 | |
| 51 typedef enum | |
| 52 { | |
| 53 GAIM_POUNCE_OPTION_NONE = 0x00, /**< No Option */ | |
| 54 GAIM_POUNCE_OPTION_AWAY = 0x01 /**< Pounce only when away */ | |
| 55 } GaimPounceOption; | |
| 56 | |
| 57 /** A pounce callback. */ | |
| 58 typedef void (*GaimPounceCb)(GaimPounce *, GaimPounceEvent, void *); | |
| 59 | |
| 60 /** | |
| 61 * A buddy pounce structure. | |
| 62 * | |
| 63 * Buddy pounces are actions triggered by a buddy-related event. For | |
| 64 * example, a sound can be played or an IM window opened when a buddy | |
| 65 * signs on or returns from away. Such responses are handled in the | |
| 66 * UI. The events themselves are done in the core. | |
| 67 */ | |
| 68 struct _GaimPounce | |
| 69 { | |
| 70 char *ui_type; /**< The type of UI. */ | |
| 71 | |
| 72 GaimPounceEvent events; /**< The event(s) to pounce on. */ | |
| 73 GaimPounceOption options; /**< The pounce options */ | |
| 74 GaimAccount *pouncer; /**< The user who is pouncing. */ | |
| 75 | |
| 76 char *pouncee; /**< The buddy to pounce on. */ | |
| 77 | |
| 78 GHashTable *actions; /**< The registered actions. */ | |
| 79 | |
| 80 gboolean save; /**< Whether or not the pounce should | |
| 81 be saved after activation. */ | |
| 82 void *data; /**< Pounce-specific data. */ | |
| 83 }; | |
| 84 | |
| 85 #ifdef __cplusplus | |
| 86 extern "C" { | |
| 87 #endif | |
| 88 | |
| 89 /**************************************************************************/ | |
| 90 /** @name Buddy Pounce API */ | |
| 91 /**************************************************************************/ | |
| 92 /*@{*/ | |
| 93 | |
| 94 /** | |
| 95 * Creates a new buddy pounce. | |
| 96 * | |
| 97 * @param ui_type The type of UI the pounce is for. | |
| 98 * @param pouncer The account that will pounce. | |
| 99 * @param pouncee The buddy to pounce on. | |
| 100 * @param event The event(s) to pounce on. | |
| 101 * | |
| 102 * @return The new buddy pounce structure. | |
| 103 */ | |
| 104 GaimPounce *gaim_pounce_new(const char *ui_type, GaimAccount *pouncer, | |
| 105 const char *pouncee, GaimPounceEvent event, | |
| 106 GaimPounceOption option); | |
| 107 | |
| 108 /** | |
| 109 * Destroys a buddy pounce. | |
| 110 * | |
| 111 * @param pounce The buddy pounce. | |
| 112 */ | |
| 113 void gaim_pounce_destroy(GaimPounce *pounce); | |
| 114 | |
| 115 /** | |
| 116 * Destroys all buddy pounces for the account | |
| 117 * | |
| 118 * @param account The account to remove all pounces from. | |
| 119 */ | |
| 120 void gaim_pounce_destroy_all_by_account(GaimAccount *account); | |
| 121 | |
| 122 /** | |
| 123 * Sets the events a pounce should watch for. | |
| 124 * | |
| 125 * @param pounce The buddy pounce. | |
| 126 * @param events The events to watch for. | |
| 127 */ | |
| 128 void gaim_pounce_set_events(GaimPounce *pounce, GaimPounceEvent events); | |
| 129 | |
| 130 /** | |
| 131 * Sets the options for a pounce. | |
| 132 * | |
| 133 * @param pounce The buddy pounce. | |
| 134 * @param options The options for the pounce. | |
| 135 */ | |
| 136 void gaim_pounce_set_options(GaimPounce *pounce, GaimPounceOption options); | |
| 137 | |
| 138 /** | |
| 139 * Sets the account that will do the pouncing. | |
| 140 * | |
| 141 * @param pounce The buddy pounce. | |
| 142 * @param pouncer The account that will pounce. | |
| 143 */ | |
| 144 void gaim_pounce_set_pouncer(GaimPounce *pounce, GaimAccount *pouncer); | |
| 145 | |
| 146 /** | |
| 147 * Sets the buddy a pounce should pounce on. | |
| 148 * | |
| 149 * @param pounce The buddy pounce. | |
| 150 * @param pouncee The buddy to pounce on. | |
| 151 */ | |
| 152 void gaim_pounce_set_pouncee(GaimPounce *pounce, const char *pouncee); | |
| 153 | |
| 154 /** | |
| 155 * Sets whether or not the pounce should be saved after execution. | |
| 156 * | |
| 157 * @param pounce The buddy pounce. | |
| 158 * @param save @c TRUE if the pounce should be saved, or @c FALSE otherwise. | |
| 159 */ | |
| 160 void gaim_pounce_set_save(GaimPounce *pounce, gboolean save); | |
| 161 | |
| 162 /** | |
| 163 * Registers an action type for the pounce. | |
| 164 * | |
| 165 * @param pounce The buddy pounce. | |
| 166 * @param name The action name. | |
| 167 */ | |
| 168 void gaim_pounce_action_register(GaimPounce *pounce, const char *name); | |
| 169 | |
| 170 /** | |
| 171 * Enables or disables an action for a pounce. | |
| 172 * | |
| 173 * @param pounce The buddy pounce. | |
| 174 * @param action The name of the action. | |
| 175 * @param enabled The enabled state. | |
| 176 */ | |
| 177 void gaim_pounce_action_set_enabled(GaimPounce *pounce, const char *action, | |
| 178 gboolean enabled); | |
| 179 | |
| 180 /** | |
| 181 * Sets a value for an attribute in an action. | |
| 182 * | |
| 183 * If @a value is @c NULL, the value will be unset. | |
| 184 * | |
| 185 * @param pounce The buddy pounce. | |
| 186 * @param action The action name. | |
| 187 * @param attr The attribute name. | |
| 188 * @param value The value. | |
| 189 */ | |
| 190 void gaim_pounce_action_set_attribute(GaimPounce *pounce, const char *action, | |
| 191 const char *attr, const char *value); | |
| 192 | |
| 193 /** | |
| 194 * Sets the pounce-specific data. | |
| 195 * | |
| 196 * @param pounce The buddy pounce. | |
| 197 * @param data Data specific to the pounce. | |
| 198 */ | |
| 199 void gaim_pounce_set_data(GaimPounce *pounce, void *data); | |
| 200 | |
| 201 /** | |
| 202 * Returns the events a pounce should watch for. | |
| 203 * | |
| 204 * @param pounce The buddy pounce. | |
| 205 * | |
| 206 * @return The events the pounce is watching for. | |
| 207 */ | |
| 208 GaimPounceEvent gaim_pounce_get_events(const GaimPounce *pounce); | |
| 209 | |
| 210 /** | |
| 211 * Returns the options for a pounce. | |
| 212 * | |
| 213 * @param pounce The buddy pounce. | |
| 214 * | |
| 215 * @return The options for the pounce. | |
| 216 */ | |
| 217 GaimPounceOption gaim_pounce_get_options(const GaimPounce *pounce); | |
| 218 | |
| 219 /** | |
| 220 * Returns the account that will do the pouncing. | |
| 221 * | |
| 222 * @param pounce The buddy pounce. | |
| 223 * | |
| 224 * @return The account that will pounce. | |
| 225 */ | |
| 226 GaimAccount *gaim_pounce_get_pouncer(const GaimPounce *pounce); | |
| 227 | |
| 228 /** | |
| 229 * Returns the buddy a pounce should pounce on. | |
| 230 * | |
| 231 * @param pounce The buddy pounce. | |
| 232 * | |
| 233 * @return The buddy to pounce on. | |
| 234 */ | |
| 235 const char *gaim_pounce_get_pouncee(const GaimPounce *pounce); | |
| 236 | |
| 237 /** | |
| 238 * Returns whether or not the pounce should save after execution. | |
| 239 * | |
| 240 * @param pounce The buddy pounce. | |
| 241 * | |
| 242 * @return @c TRUE if the pounce should be saved after execution, or | |
| 243 * @c FALSE otherwise. | |
| 244 */ | |
| 245 gboolean gaim_pounce_get_save(const GaimPounce *pounce); | |
| 246 | |
| 247 /** | |
| 248 * Returns whether or not an action is enabled. | |
| 249 * | |
| 250 * @param pounce The buddy pounce. | |
| 251 * @param action The action name. | |
| 252 * | |
| 253 * @return @c TRUE if the action is enabled, or @c FALSE otherwise. | |
| 254 */ | |
| 255 gboolean gaim_pounce_action_is_enabled(const GaimPounce *pounce, | |
| 256 const char *action); | |
| 257 | |
| 258 /** | |
| 259 * Returns the value for an attribute in an action. | |
| 260 * | |
| 261 * @param pounce The buddy pounce. | |
| 262 * @param action The action name. | |
| 263 * @param attr The attribute name. | |
| 264 * | |
| 265 * @return The attribute value, if it exists, or @c NULL. | |
| 266 */ | |
| 267 const char *gaim_pounce_action_get_attribute(const GaimPounce *pounce, | |
| 268 const char *action, | |
| 269 const char *attr); | |
| 270 | |
| 271 /** | |
| 272 * Returns the pounce-specific data. | |
| 273 * | |
| 274 * @param pounce The buddy pounce. | |
| 275 * | |
| 276 * @return The data specific to a buddy pounce. | |
| 277 */ | |
| 278 void *gaim_pounce_get_data(const GaimPounce *pounce); | |
| 279 | |
| 280 /** | |
| 281 * Executes a pounce with the specified pouncer, pouncee, and event type. | |
| 282 * | |
| 283 * @param pouncer The account that will do the pouncing. | |
| 284 * @param pouncee The buddy that is being pounced. | |
| 285 * @param events The events that triggered the pounce. | |
| 286 */ | |
| 287 void gaim_pounce_execute(const GaimAccount *pouncer, const char *pouncee, | |
| 288 GaimPounceEvent events); | |
| 289 | |
| 290 /*@}*/ | |
| 291 | |
| 292 /**************************************************************************/ | |
| 293 /** @name Buddy Pounce Subsystem API */ | |
| 294 /**************************************************************************/ | |
| 295 /*@{*/ | |
| 296 | |
| 297 /** | |
| 298 * Finds a pounce with the specified event(s) and buddy. | |
| 299 * | |
| 300 * @param pouncer The account to match against. | |
| 301 * @param pouncee The buddy to match against. | |
| 302 * @param events The event(s) to match against. | |
| 303 * | |
| 304 * @return The pounce if found, or @c NULL otherwise. | |
| 305 */ | |
| 306 GaimPounce *gaim_find_pounce(const GaimAccount *pouncer, | |
| 307 const char *pouncee, GaimPounceEvent events); | |
| 308 | |
| 309 | |
| 310 /** | |
| 311 * Loads the pounces. | |
| 312 * | |
| 313 * @return @c TRUE if the pounces could be loaded. | |
| 314 */ | |
| 315 gboolean gaim_pounces_load(void); | |
| 316 | |
| 317 /** | |
| 318 * Registers a pounce handler for a UI. | |
| 319 * | |
| 320 * @param ui The UI name. | |
| 321 * @param cb The callback function. | |
| 322 * @param new_pounce The function called when a pounce is created. | |
| 323 * @param free_pounce The function called when a pounce is freed. | |
| 324 */ | |
| 325 void gaim_pounces_register_handler(const char *ui, GaimPounceCb cb, | |
| 326 void (*new_pounce)(GaimPounce *pounce), | |
| 327 void (*free_pounce)(GaimPounce *pounce)); | |
| 328 | |
| 329 /** | |
| 330 * Unregisters a pounce handle for a UI. | |
| 331 * | |
| 332 * @param ui The UI name. | |
| 333 */ | |
| 334 void gaim_pounces_unregister_handler(const char *ui); | |
| 335 | |
| 336 /** | |
| 337 * Returns a list of all registered buddy pounces. | |
| 338 * | |
| 339 * @return The list of buddy pounces. | |
| 340 */ | |
| 341 GList *gaim_pounces_get_all(void); | |
| 342 | |
| 343 /** | |
| 344 * Returns the buddy pounce subsystem handle. | |
| 345 * | |
| 346 * @return The subsystem handle. | |
| 347 */ | |
| 348 void *gaim_pounces_get_handle(void); | |
| 349 | |
| 350 /** | |
| 351 * Initializes the pounces subsystem. | |
| 352 */ | |
| 353 void gaim_pounces_init(void); | |
| 354 | |
| 355 /** | |
| 356 * Uninitializes the pounces subsystem. | |
| 357 */ | |
| 358 void gaim_pounces_uninit(void); | |
| 359 | |
| 360 /*@}*/ | |
| 361 | |
| 362 #ifdef __cplusplus | |
| 363 } | |
| 364 #endif | |
| 365 | |
| 366 #endif /* _GAIM_POUNCE_H_ */ |
