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