Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/pounce.h
branchadium-1.5.11-merge
changeset 6013 f8d0dc659e3f
parent 5941 307f53385811
parent 6012 200a01709ba4
child 6014 fcb71cb71a3d
child 6015 2b01cc935b7c
equal deleted inserted replaced
5941:307f53385811 6013:f8d0dc659e3f
     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_ */