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  * @pounce: The #PurplePounce.
  82  * @event: The #PurplePounceEvent.
  83  * @data: user-data.
  84  *
  85  * A pounce callback.
  86  */
  87 typedef void (*PurplePounceCb)(PurplePounce *pounce, PurplePounceEvent event, void *data);
  88
  89 G_BEGIN_DECLS
  90
  91 /**************************************************************************/
  92 /* Buddy Pounce API                                                       */
  93 /**************************************************************************/
  94
  95 /**
  96  * purple_pounce_new:
  97  * @ui_type: The type of UI the pounce is for.
  98  * @pouncer: The account that will pounce.
  99  * @pouncee: The buddy to pounce on.
 100  * @event:   The event(s) to pounce on.
 101  * @option:  Pounce options.
 102  *
 103  * Creates a new buddy pounce.
 104  *
 105  * Returns: 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  * purple_pounce_destroy:
 113  * @pounce: The buddy pounce.
 114  *
 115  * Destroys a buddy pounce.
 116  */
 117 void purple_pounce_destroy(PurplePounce *pounce);
 118
 119 /**
 120  * purple_pounce_destroy_all_by_account:
 121  * @account: The account to remove all pounces from.
 122  *
 123  * Destroys all buddy pounces for the account
 124  */
 125 void purple_pounce_destroy_all_by_account(PurpleAccount *account);
 126
 127 /**
 128  * purple_pounce_destroy_all_by_buddy:
 129  * @buddy: The buddy whose pounces are to be removed
 130  *
 131  * Destroys all buddy pounces for a buddy
 132  */
 133 void purple_pounce_destroy_all_by_buddy(PurpleBuddy *buddy);
 134
 135 /**
 136  * purple_pounce_set_events:
 137  * @pounce: The buddy pounce.
 138  * @events: The events to watch for.
 139  *
 140  * Sets the events a pounce should watch for.
 141  */
 142 void purple_pounce_set_events(PurplePounce *pounce, PurplePounceEvent events);
 143
 144 /**
 145  * purple_pounce_set_options:
 146  * @pounce:  The buddy pounce.
 147  * @options: The options for the pounce.
 148  *
 149  * Sets the options for a pounce.
 150  */
 151 void purple_pounce_set_options(PurplePounce *pounce, PurplePounceOption options);
 152
 153 /**
 154  * purple_pounce_set_pouncer:
 155  * @pounce:  The buddy pounce.
 156  * @pouncer: The account that will pounce.
 157  *
 158  * Sets the account that will do the pouncing.
 159  */
 160 void purple_pounce_set_pouncer(PurplePounce *pounce, PurpleAccount *pouncer);
 161
 162 /**
 163  * purple_pounce_set_pouncee:
 164  * @pounce:  The buddy pounce.
 165  * @pouncee: The buddy to pounce on.
 166  *
 167  * Sets the buddy a pounce should pounce on.
 168  */
 169 void purple_pounce_set_pouncee(PurplePounce *pounce, const char *pouncee);
 170
 171 /**
 172  * purple_pounce_set_save:
 173  * @pounce: The buddy pounce.
 174  * @save:   %TRUE if the pounce should be saved, or %FALSE otherwise.
 175  *
 176  * Sets whether or not the pounce should be saved after execution.
 177  */
 178 void purple_pounce_set_save(PurplePounce *pounce, gboolean save);
 179
 180 /**
 181  * purple_pounce_action_register:
 182  * @pounce: The buddy pounce.
 183  * @name:   The action name.
 184  *
 185  * Registers an action type for the pounce.
 186  */
 187 void purple_pounce_action_register(PurplePounce *pounce, const char *name);
 188
 189 /**
 190  * purple_pounce_action_set_enabled:
 191  * @pounce:  The buddy pounce.
 192  * @action:  The name of the action.
 193  * @enabled: The enabled state.
 194  *
 195  * Enables or disables an action for a pounce.
 196  */
 197 void purple_pounce_action_set_enabled(PurplePounce *pounce, const char *action,
 198                                                                         gboolean enabled);
 199
 200 /**
 201  * purple_pounce_action_set_attribute:
 202  * @pounce: The buddy pounce.
 203  * @action: The action name.
 204  * @attr:   The attribute name.
 205  * @value:  The value.
 206  *
 207  * Sets a value for an attribute in an action.
 208  *
 209  * If @value is %NULL, the value will be unset.
 210  */
 211 void purple_pounce_action_set_attribute(PurplePounce *pounce, const char *action,
 212                                                                           const char *attr, const char *value);
 213
 214 /**
 215  * purple_pounce_set_data:
 216  * @pounce: The buddy pounce.
 217  * @data:   Data specific to the pounce.
 218  *
 219  * Sets the pounce-specific data.
 220  */
 221 void purple_pounce_set_data(PurplePounce *pounce, void *data);
 222
 223 /**
 224  * purple_pounce_get_events:
 225  * @pounce: The buddy pounce.
 226  *
 227  * Returns the events a pounce should watch for.
 228  *
 229  * Returns: The events the pounce is watching for.
 230  */
 231 PurplePounceEvent purple_pounce_get_events(const PurplePounce *pounce);
 232
 233 /**
 234  * purple_pounce_get_options:
 235  * @pounce: The buddy pounce.
 236  *
 237  * Returns the options for a pounce.
 238  *
 239  * Returns: The options for the pounce.
 240  */
 241 PurplePounceOption purple_pounce_get_options(const PurplePounce *pounce);
 242
 243 /**
 244  * purple_pounce_get_pouncer:
 245  * @pounce: The buddy pounce.
 246  *
 247  * Returns the account that will do the pouncing.
 248  *
 249  * Returns: (transfer none): The account that will pounce.
 250  */
 251 PurpleAccount *purple_pounce_get_pouncer(const PurplePounce *pounce);
 252
 253 /**
 254  * purple_pounce_get_pouncee:
 255  * @pounce: The buddy pounce.
 256  *
 257  * Returns the buddy a pounce should pounce on.
 258  *
 259  * Returns: The buddy to pounce on.
 260  */
 261 const char *purple_pounce_get_pouncee(const PurplePounce *pounce);
 262
 263 /**
 264  * purple_pounce_get_save:
 265  * @pounce: The buddy pounce.
 266  *
 267  * Returns whether or not the pounce should save after execution.
 268  *
 269  * Returns: %TRUE if the pounce should be saved after execution, or
 270  *         %FALSE otherwise.
 271  */
 272 gboolean purple_pounce_get_save(const PurplePounce *pounce);
 273
 274 /**
 275  * purple_pounce_action_is_enabled:
 276  * @pounce: The buddy pounce.
 277  * @action: The action name.
 278  *
 279  * Returns whether or not an action is enabled.
 280  *
 281  * Returns: %TRUE if the action is enabled, or %FALSE otherwise.
 282  */
 283 gboolean purple_pounce_action_is_enabled(const PurplePounce *pounce,
 284                                                                            const char *action);
 285
 286 /**
 287  * purple_pounce_action_get_attribute:
 288  * @pounce: The buddy pounce.
 289  * @action: The action name.
 290  * @attr:   The attribute name.
 291  *
 292  * Returns the value for an attribute in an action.
 293  *
 294  * Returns: The attribute value, if it exists, or %NULL.
 295  */
 296 const char *purple_pounce_action_get_attribute(const PurplePounce *pounce,
 297                                                                                          const char *action,
 298                                                                                          const char *attr);
 299
 300 /**
 301  * purple_pounce_get_data:
 302  * @pounce: The buddy pounce.
 303  *
 304  * Returns the pounce-specific data.
 305  *
 306  * Returns: The data specific to a buddy pounce.
 307  */
 308 void *purple_pounce_get_data(const PurplePounce *pounce);
 309
 310 /**
 311  * purple_pounce_execute:
 312  * @pouncer: The account that will do the pouncing.
 313  * @pouncee: The buddy that is being pounced.
 314  * @events:  The events that triggered the pounce.
 315  *
 316  * Executes a pounce with the specified pouncer, pouncee, and event type.
 317  */
 318 void purple_pounce_execute(PurpleAccount *pouncer, const char *pouncee,
 319                                                  PurplePounceEvent events);
 320
 321 /**************************************************************************/
 322 /* Buddy Pounce Subsystem API                                             */
 323 /**************************************************************************/
 324
 325 /**
 326  * purple_find_pounce:
 327  * @pouncer: The account to match against.
 328  * @pouncee: The buddy to match against.
 329  * @events:  The event(s) to match against.
 330  *
 331  * Finds a pounce with the specified event(s) and buddy.
 332  *
 333  * Returns: The pounce if found, or %NULL otherwise.
 334  */
 335 PurplePounce *purple_find_pounce(PurpleAccount *pouncer,
 336                                                          const char *pouncee, PurplePounceEvent events);
 337
 338 /**
 339  * purple_pounces_register_handler:
 340  * @ui:          The UI name.
 341  * @cb:          (scope call): The callback function.
 342  * @new_pounce:  The function called when a pounce is created.
 343  * @free_pounce: The function called when a pounce is freed.
 344  *
 345  * Registers a pounce handler for a UI.
 346  */
 347 void purple_pounces_register_handler(const char *ui, PurplePounceCb cb,
 348                                                                    void (*new_pounce)(PurplePounce *pounce),
 349                                                                    void (*free_pounce)(PurplePounce *pounce));
 350
 351 /**
 352  * purple_pounces_unregister_handler:
 353  * @ui: The UI name.
 354  *
 355  * Unregisters a pounce handle for a UI.
 356  */
 357 void purple_pounces_unregister_handler(const char *ui);
 358
 359 /**
 360  * purple_pounces_get_all:
 361  *
 362  * Returns a list of all registered buddy pounces.
 363  *
 364  * Returns: (element-type PurplePounce) (transfer none): The list of buddy pounces.
 365  */
 366 GList *purple_pounces_get_all(void);
 367
 368 /**
 369  * purple_pounces_get_all_for_ui:
 370  * @ui:  The ID of the UI using the core.
 371  *
 372  * Returns a list of registered buddy pounces for the ui-type.
 373  *
 374  * Returns: (element-type PurplePounce) (transfer container): The list of buddy pounces.
 375  */
 376 GList *purple_pounces_get_all_for_ui(const char *ui);
 377
 378 /**
 379  * purple_pounces_get_handle:
 380  *
 381  * Returns the buddy pounce subsystem handle.
 382  *
 383  * Returns: The subsystem handle.
 384  */
 385 void *purple_pounces_get_handle(void);
 386
 387 /**
 388  * purple_pounces_init:
 389  *
 390  * Initializes the pounces subsystem.
 391  */
 392 void purple_pounces_init(void);
 393
 394 /**
 395  * purple_pounces_uninit:
 396  *
 397  * Uninitializes the pounces subsystem.
 398  */
 399 void purple_pounces_uninit(void);
 400
 401 G_END_DECLS
 402
 403 #endif /* PURPLE_POUNCE_H */