libpurple/pounce.h

   1 /**
   2  * @file pounce.h Buddy Pounce 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_POUNCE_H_
  27 #define _PURPLE_POUNCE_H_
  28
  29 typedef struct _PurplePounce PurplePounce;
  30
  31 #include <glib.h>
  32 #include "account.h"
  33
  34 /**
  35  * Events that trigger buddy pounces.
  36  */
  37 typedef enum
  38 {
  39         PURPLE_POUNCE_NONE             = 0x000, /**< No events.                    */
  40         PURPLE_POUNCE_SIGNON           = 0x001, /**< The buddy signed on.          */
  41         PURPLE_POUNCE_SIGNOFF          = 0x002, /**< The buddy signed off.         */
  42         PURPLE_POUNCE_AWAY             = 0x004, /**< The buddy went away.          */
  43         PURPLE_POUNCE_AWAY_RETURN      = 0x008, /**< The buddy returned from away. */
  44         PURPLE_POUNCE_IDLE             = 0x010, /**< The buddy became idle.        */
  45         PURPLE_POUNCE_IDLE_RETURN      = 0x020, /**< The buddy is no longer idle.  */
  46         PURPLE_POUNCE_TYPING           = 0x040, /**< The buddy started typing.     */
  47         PURPLE_POUNCE_TYPED            = 0x080, /**< The buddy has entered text.   */
  48         PURPLE_POUNCE_TYPING_STOPPED   = 0x100, /**< The buddy stopped typing.     */
  49         PURPLE_POUNCE_MESSAGE_RECEIVED = 0x200  /**< The buddy sent a message      */
  50
  51 } PurplePounceEvent;
  52
  53 typedef enum
  54 {
  55         PURPLE_POUNCE_OPTION_NONE               = 0x00, /**< No Option                */
  56         PURPLE_POUNCE_OPTION_AWAY               = 0x01  /**< Pounce only when away    */
  57 } PurplePounceOption;
  58
  59 /** A pounce callback. */
  60 typedef void (*PurplePounceCb)(PurplePounce *, PurplePounceEvent, void *);
  61
  62 /**
  63  * A buddy pounce structure.
  64  *
  65  * Buddy pounces are actions triggered by a buddy-related event. For
  66  * example, a sound can be played or an IM window opened when a buddy
  67  * signs on or returns from away. Such responses are handled in the
  68  * UI. The events themselves are done in the core.
  69  */
  70 struct _PurplePounce
  71 {
  72         char *ui_type;                /**< The type of UI.            */
  73
  74         PurplePounceEvent events;       /**< The event(s) to pounce on. */
  75         PurplePounceOption options;     /**< The pounce options         */
  76         PurpleAccount *pouncer;         /**< The user who is pouncing.  */
  77
  78         char *pouncee;                /**< The buddy to pounce on.    */
  79
  80         GHashTable *actions;          /**< The registered actions.    */
  81
  82         gboolean save;                /**< Whether or not the pounce should
  83                                            be saved after activation. */
  84         void *data;                   /**< Pounce-specific data.      */
  85 };
  86
  87 #ifdef __cplusplus
  88 extern "C" {
  89 #endif
  90
  91 /**************************************************************************/
  92 /** @name Buddy Pounce API                                                */
  93 /**************************************************************************/
  94 /*@{*/
  95
  96 /**
  97  * Creates a new buddy pounce.
  98  *
  99  * @param ui_type The type of UI the pounce is for.
 100  * @param pouncer The account that will pounce.
 101  * @param pouncee The buddy to pounce on.
 102  * @param event   The event(s) to pounce on.
 103  * @param option  Pounce options.
 104  *
 105  * @return The new buddy pounce structure.
 106  */
 107 PurplePounce *purple_pounce_new(const char *ui_type, PurpleAccount *pouncer,
 108                                                         const char *pouncee, PurplePounceEvent event,
 109                                                         PurplePounceOption option);
 110
 111 /**
 112  * Destroys a buddy pounce.
 113  *
 114  * @param pounce The buddy pounce.
 115  */
 116 void purple_pounce_destroy(PurplePounce *pounce);
 117
 118 /**
 119  * Destroys all buddy pounces for the account
 120  *
 121  * @param account The account to remove all pounces from.
 122  */
 123 void purple_pounce_destroy_all_by_account(PurpleAccount *account);
 124
 125 /**
 126  * Destroys all buddy pounces for a buddy
 127  *
 128  * @param buddy The buddy whose pounces are to be removed
 129  *
 130  * @since 2.8.0
 131  */
 132 void purple_pounce_destroy_all_by_buddy(PurpleBuddy *buddy);
 133
 134 /**
 135  * Sets the events a pounce should watch for.
 136  *
 137  * @param pounce The buddy pounce.
 138  * @param events The events to watch for.
 139  */
 140 void purple_pounce_set_events(PurplePounce *pounce, PurplePounceEvent events);
 141
 142 /**
 143  * Sets the options for a pounce.
 144  *
 145  * @param pounce  The buddy pounce.
 146  * @param options The options for the pounce.
 147  */
 148 void purple_pounce_set_options(PurplePounce *pounce, PurplePounceOption options);
 149
 150 /**
 151  * Sets the account that will do the pouncing.
 152  *
 153  * @param pounce  The buddy pounce.
 154  * @param pouncer The account that will pounce.
 155  */
 156 void purple_pounce_set_pouncer(PurplePounce *pounce, PurpleAccount *pouncer);
 157
 158 /**
 159  * Sets the buddy a pounce should pounce on.
 160  *
 161  * @param pounce  The buddy pounce.
 162  * @param pouncee The buddy to pounce on.
 163  */
 164 void purple_pounce_set_pouncee(PurplePounce *pounce, const char *pouncee);
 165
 166 /**
 167  * Sets whether or not the pounce should be saved after execution.
 168  *
 169  * @param pounce The buddy pounce.
 170  * @param save   @c TRUE if the pounce should be saved, or @c FALSE otherwise.
 171  */
 172 void purple_pounce_set_save(PurplePounce *pounce, gboolean save);
 173
 174 /**
 175  * Registers an action type for the pounce.
 176  *
 177  * @param pounce The buddy pounce.
 178  * @param name   The action name.
 179  */
 180 void purple_pounce_action_register(PurplePounce *pounce, const char *name);
 181
 182 /**
 183  * Enables or disables an action for a pounce.
 184  *
 185  * @param pounce  The buddy pounce.
 186  * @param action  The name of the action.
 187  * @param enabled The enabled state.
 188  */
 189 void purple_pounce_action_set_enabled(PurplePounce *pounce, const char *action,
 190                                                                         gboolean enabled);
 191
 192 /**
 193  * Sets a value for an attribute in an action.
 194  *
 195  * If @a value is @c NULL, the value will be unset.
 196  *
 197  * @param pounce The buddy pounce.
 198  * @param action The action name.
 199  * @param attr   The attribute name.
 200  * @param value  The value.
 201  */
 202 void purple_pounce_action_set_attribute(PurplePounce *pounce, const char *action,
 203                                                                           const char *attr, const char *value);
 204
 205 /**
 206  * Sets the pounce-specific data.
 207  *
 208  * @param pounce The buddy pounce.
 209  * @param data   Data specific to the pounce.
 210  */
 211 void purple_pounce_set_data(PurplePounce *pounce, void *data);
 212
 213 /**
 214  * Returns the events a pounce should watch for.
 215  *
 216  * @param pounce The buddy pounce.
 217  *
 218  * @return The events the pounce is watching for.
 219  */
 220 PurplePounceEvent purple_pounce_get_events(const PurplePounce *pounce);
 221
 222 /**
 223  * Returns the options for a pounce.
 224  *
 225  * @param pounce The buddy pounce.
 226  *
 227  * @return The options for the pounce.
 228  */
 229 PurplePounceOption purple_pounce_get_options(const PurplePounce *pounce);
 230
 231 /**
 232  * Returns the account that will do the pouncing.
 233  *
 234  * @param pounce The buddy pounce.
 235  *
 236  * @return The account that will pounce.
 237  */
 238 PurpleAccount *purple_pounce_get_pouncer(const PurplePounce *pounce);
 239
 240 /**
 241  * Returns the buddy a pounce should pounce on.
 242  *
 243  * @param pounce The buddy pounce.
 244  *
 245  * @return The buddy to pounce on.
 246  */
 247 const char *purple_pounce_get_pouncee(const PurplePounce *pounce);
 248
 249 /**
 250  * Returns whether or not the pounce should save after execution.
 251  *
 252  * @param pounce The buddy pounce.
 253  *
 254  * @return @c TRUE if the pounce should be saved after execution, or
 255  *         @c FALSE otherwise.
 256  */
 257 gboolean purple_pounce_get_save(const PurplePounce *pounce);
 258
 259 /**
 260  * Returns whether or not an action is enabled.
 261  *
 262  * @param pounce The buddy pounce.
 263  * @param action The action name.
 264  *
 265  * @return @c TRUE if the action is enabled, or @c FALSE otherwise.
 266  */
 267 gboolean purple_pounce_action_is_enabled(const PurplePounce *pounce,
 268                                                                            const char *action);
 269
 270 /**
 271  * Returns the value for an attribute in an action.
 272  *
 273  * @param pounce The buddy pounce.
 274  * @param action The action name.
 275  * @param attr   The attribute name.
 276  *
 277  * @return The attribute value, if it exists, or @c NULL.
 278  */
 279 const char *purple_pounce_action_get_attribute(const PurplePounce *pounce,
 280                                                                                          const char *action,
 281                                                                                          const char *attr);
 282
 283 /**
 284  * Returns the pounce-specific data.
 285  *
 286  * @param pounce The buddy pounce.
 287  *
 288  * @return The data specific to a buddy pounce.
 289  */
 290 void *purple_pounce_get_data(const PurplePounce *pounce);
 291
 292 /**
 293  * Executes a pounce with the specified pouncer, pouncee, and event type.
 294  *
 295  * @param pouncer The account that will do the pouncing.
 296  * @param pouncee The buddy that is being pounced.
 297  * @param events  The events that triggered the pounce.
 298  */
 299 void purple_pounce_execute(const PurpleAccount *pouncer, const char *pouncee,
 300                                                  PurplePounceEvent events);
 301
 302 /*@}*/
 303
 304 /**************************************************************************/
 305 /** @name Buddy Pounce Subsystem API                                      */
 306 /**************************************************************************/
 307 /*@{*/
 308
 309 /**
 310  * Finds a pounce with the specified event(s) and buddy.
 311  *
 312  * @param pouncer The account to match against.
 313  * @param pouncee The buddy to match against.
 314  * @param events  The event(s) to match against.
 315  *
 316  * @return The pounce if found, or @c NULL otherwise.
 317  */
 318 PurplePounce *purple_find_pounce(const PurpleAccount *pouncer,
 319                                                          const char *pouncee, PurplePounceEvent events);
 320
 321
 322 /**
 323  * Loads the pounces.
 324  *
 325  * @return @c TRUE if the pounces could be loaded.
 326  */
 327 gboolean purple_pounces_load(void);
 328
 329 /**
 330  * Registers a pounce handler for a UI.
 331  *
 332  * @param ui          The UI name.
 333  * @param cb          The callback function.
 334  * @param new_pounce  The function called when a pounce is created.
 335  * @param free_pounce The function called when a pounce is freed.
 336  */
 337 void purple_pounces_register_handler(const char *ui, PurplePounceCb cb,
 338                                                                    void (*new_pounce)(PurplePounce *pounce),
 339                                                                    void (*free_pounce)(PurplePounce *pounce));
 340
 341 /**
 342  * Unregisters a pounce handle for a UI.
 343  *
 344  * @param ui The UI name.
 345  */
 346 void purple_pounces_unregister_handler(const char *ui);
 347
 348 /**
 349  * Returns a list of all registered buddy pounces.
 350  *
 351  * @constreturn The list of buddy pounces.
 352  */
 353 GList *purple_pounces_get_all(void);
 354
 355 /**
 356  * Returns a list of registered buddy pounces for the ui-type.
 357  *
 358  * @param ui  The ID of the UI using the core.
 359  *
 360  * @return The list of buddy pounces. The list should be freed by
 361  *         the caller when it's no longer used.
 362  * @since  2.1.0
 363  */
 364 GList *purple_pounces_get_all_for_ui(const char *ui);
 365
 366 /**
 367  * Returns the buddy pounce subsystem handle.
 368  *
 369  * @return The subsystem handle.
 370  */
 371 void *purple_pounces_get_handle(void);
 372
 373 /**
 374  * Initializes the pounces subsystem.
 375  */
 376 void purple_pounces_init(void);
 377
 378 /**
 379  * Uninitializes the pounces subsystem.
 380  */
 381 void purple_pounces_uninit(void);
 382
 383 /*@}*/
 384
 385 #ifdef __cplusplus
 386 }
 387 #endif
 388
 389 #endif /* _PURPLE_POUNCE_H_ */