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