1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/pounce.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,380 @@
1.4 +/**
1.5 + * @file pounce.h Buddy Pounce API
1.6 + * @ingroup core
1.7 + */
1.8 +
1.9 +/* purple
1.10 + *
1.11 + * Purple is the legal property of its developers, whose names are too numerous
1.12 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.13 + * source distribution.
1.14 + *
1.15 + * This program is free software; you can redistribute it and/or modify
1.16 + * it under the terms of the GNU General Public License as published by
1.17 + * the Free Software Foundation; either version 2 of the License, or
1.18 + * (at your option) any later version.
1.19 + *
1.20 + * This program is distributed in the hope that it will be useful,
1.21 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.22 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.23 + * GNU General Public License for more details.
1.24 + *
1.25 + * You should have received a copy of the GNU General Public License
1.26 + * along with this program; if not, write to the Free Software
1.27 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.28 + */
1.29 +#ifndef _PURPLE_POUNCE_H_
1.30 +#define _PURPLE_POUNCE_H_
1.31 +
1.32 +typedef struct _PurplePounce PurplePounce;
1.33 +
1.34 +#include <glib.h>
1.35 +#include "account.h"
1.36 +
1.37 +/**
1.38 + * Events that trigger buddy pounces.
1.39 + */
1.40 +typedef enum
1.41 +{
1.42 + PURPLE_POUNCE_NONE = 0x000, /**< No events. */
1.43 + PURPLE_POUNCE_SIGNON = 0x001, /**< The buddy signed on. */
1.44 + PURPLE_POUNCE_SIGNOFF = 0x002, /**< The buddy signed off. */
1.45 + PURPLE_POUNCE_AWAY = 0x004, /**< The buddy went away. */
1.46 + PURPLE_POUNCE_AWAY_RETURN = 0x008, /**< The buddy returned from away. */
1.47 + PURPLE_POUNCE_IDLE = 0x010, /**< The buddy became idle. */
1.48 + PURPLE_POUNCE_IDLE_RETURN = 0x020, /**< The buddy is no longer idle. */
1.49 + PURPLE_POUNCE_TYPING = 0x040, /**< The buddy started typing. */
1.50 + PURPLE_POUNCE_TYPED = 0x080, /**< The buddy has entered text. */
1.51 + PURPLE_POUNCE_TYPING_STOPPED = 0x100, /**< The buddy stopped typing. */
1.52 + PURPLE_POUNCE_MESSAGE_RECEIVED = 0x200 /**< The buddy sent a message */
1.53 +
1.54 +} PurplePounceEvent;
1.55 +
1.56 +typedef enum
1.57 +{
1.58 + PURPLE_POUNCE_OPTION_NONE = 0x00, /**< No Option */
1.59 + PURPLE_POUNCE_OPTION_AWAY = 0x01 /**< Pounce only when away */
1.60 +} PurplePounceOption;
1.61 +
1.62 +/** A pounce callback. */
1.63 +typedef void (*PurplePounceCb)(PurplePounce *, PurplePounceEvent, void *);
1.64 +
1.65 +/**
1.66 + * A buddy pounce structure.
1.67 + *
1.68 + * Buddy pounces are actions triggered by a buddy-related event. For
1.69 + * example, a sound can be played or an IM window opened when a buddy
1.70 + * signs on or returns from away. Such responses are handled in the
1.71 + * UI. The events themselves are done in the core.
1.72 + */
1.73 +struct _PurplePounce
1.74 +{
1.75 + char *ui_type; /**< The type of UI. */
1.76 +
1.77 + PurplePounceEvent events; /**< The event(s) to pounce on. */
1.78 + PurplePounceOption options; /**< The pounce options */
1.79 + PurpleAccount *pouncer; /**< The user who is pouncing. */
1.80 +
1.81 + char *pouncee; /**< The buddy to pounce on. */
1.82 +
1.83 + GHashTable *actions; /**< The registered actions. */
1.84 +
1.85 + gboolean save; /**< Whether or not the pounce should
1.86 + be saved after activation. */
1.87 + void *data; /**< Pounce-specific data. */
1.88 +};
1.89 +
1.90 +#ifdef __cplusplus
1.91 +extern "C" {
1.92 +#endif
1.93 +
1.94 +/**************************************************************************/
1.95 +/** @name Buddy Pounce API */
1.96 +/**************************************************************************/
1.97 +/*@{*/
1.98 +
1.99 +/**
1.100 + * Creates a new buddy pounce.
1.101 + *
1.102 + * @param ui_type The type of UI the pounce is for.
1.103 + * @param pouncer The account that will pounce.
1.104 + * @param pouncee The buddy to pounce on.
1.105 + * @param event The event(s) to pounce on.
1.106 + * @param option Pounce options.
1.107 + *
1.108 + * @return The new buddy pounce structure.
1.109 + */
1.110 +PurplePounce *purple_pounce_new(const char *ui_type, PurpleAccount *pouncer,
1.111 + const char *pouncee, PurplePounceEvent event,
1.112 + PurplePounceOption option);
1.113 +
1.114 +/**
1.115 + * Destroys a buddy pounce.
1.116 + *
1.117 + * @param pounce The buddy pounce.
1.118 + */
1.119 +void purple_pounce_destroy(PurplePounce *pounce);
1.120 +
1.121 +/**
1.122 + * Destroys all buddy pounces for the account
1.123 + *
1.124 + * @param account The account to remove all pounces from.
1.125 + */
1.126 +void purple_pounce_destroy_all_by_account(PurpleAccount *account);
1.127 +
1.128 +/**
1.129 + * Sets the events a pounce should watch for.
1.130 + *
1.131 + * @param pounce The buddy pounce.
1.132 + * @param events The events to watch for.
1.133 + */
1.134 +void purple_pounce_set_events(PurplePounce *pounce, PurplePounceEvent events);
1.135 +
1.136 +/**
1.137 + * Sets the options for a pounce.
1.138 + *
1.139 + * @param pounce The buddy pounce.
1.140 + * @param options The options for the pounce.
1.141 + */
1.142 +void purple_pounce_set_options(PurplePounce *pounce, PurplePounceOption options);
1.143 +
1.144 +/**
1.145 + * Sets the account that will do the pouncing.
1.146 + *
1.147 + * @param pounce The buddy pounce.
1.148 + * @param pouncer The account that will pounce.
1.149 + */
1.150 +void purple_pounce_set_pouncer(PurplePounce *pounce, PurpleAccount *pouncer);
1.151 +
1.152 +/**
1.153 + * Sets the buddy a pounce should pounce on.
1.154 + *
1.155 + * @param pounce The buddy pounce.
1.156 + * @param pouncee The buddy to pounce on.
1.157 + */
1.158 +void purple_pounce_set_pouncee(PurplePounce *pounce, const char *pouncee);
1.159 +
1.160 +/**
1.161 + * Sets whether or not the pounce should be saved after execution.
1.162 + *
1.163 + * @param pounce The buddy pounce.
1.164 + * @param save @c TRUE if the pounce should be saved, or @c FALSE otherwise.
1.165 + */
1.166 +void purple_pounce_set_save(PurplePounce *pounce, gboolean save);
1.167 +
1.168 +/**
1.169 + * Registers an action type for the pounce.
1.170 + *
1.171 + * @param pounce The buddy pounce.
1.172 + * @param name The action name.
1.173 + */
1.174 +void purple_pounce_action_register(PurplePounce *pounce, const char *name);
1.175 +
1.176 +/**
1.177 + * Enables or disables an action for a pounce.
1.178 + *
1.179 + * @param pounce The buddy pounce.
1.180 + * @param action The name of the action.
1.181 + * @param enabled The enabled state.
1.182 + */
1.183 +void purple_pounce_action_set_enabled(PurplePounce *pounce, const char *action,
1.184 + gboolean enabled);
1.185 +
1.186 +/**
1.187 + * Sets a value for an attribute in an action.
1.188 + *
1.189 + * If @a value is @c NULL, the value will be unset.
1.190 + *
1.191 + * @param pounce The buddy pounce.
1.192 + * @param action The action name.
1.193 + * @param attr The attribute name.
1.194 + * @param value The value.
1.195 + */
1.196 +void purple_pounce_action_set_attribute(PurplePounce *pounce, const char *action,
1.197 + const char *attr, const char *value);
1.198 +
1.199 +/**
1.200 + * Sets the pounce-specific data.
1.201 + *
1.202 + * @param pounce The buddy pounce.
1.203 + * @param data Data specific to the pounce.
1.204 + */
1.205 +void purple_pounce_set_data(PurplePounce *pounce, void *data);
1.206 +
1.207 +/**
1.208 + * Returns the events a pounce should watch for.
1.209 + *
1.210 + * @param pounce The buddy pounce.
1.211 + *
1.212 + * @return The events the pounce is watching for.
1.213 + */
1.214 +PurplePounceEvent purple_pounce_get_events(const PurplePounce *pounce);
1.215 +
1.216 +/**
1.217 + * Returns the options for a pounce.
1.218 + *
1.219 + * @param pounce The buddy pounce.
1.220 + *
1.221 + * @return The options for the pounce.
1.222 + */
1.223 +PurplePounceOption purple_pounce_get_options(const PurplePounce *pounce);
1.224 +
1.225 +/**
1.226 + * Returns the account that will do the pouncing.
1.227 + *
1.228 + * @param pounce The buddy pounce.
1.229 + *
1.230 + * @return The account that will pounce.
1.231 + */
1.232 +PurpleAccount *purple_pounce_get_pouncer(const PurplePounce *pounce);
1.233 +
1.234 +/**
1.235 + * Returns the buddy a pounce should pounce on.
1.236 + *
1.237 + * @param pounce The buddy pounce.
1.238 + *
1.239 + * @return The buddy to pounce on.
1.240 + */
1.241 +const char *purple_pounce_get_pouncee(const PurplePounce *pounce);
1.242 +
1.243 +/**
1.244 + * Returns whether or not the pounce should save after execution.
1.245 + *
1.246 + * @param pounce The buddy pounce.
1.247 + *
1.248 + * @return @c TRUE if the pounce should be saved after execution, or
1.249 + * @c FALSE otherwise.
1.250 + */
1.251 +gboolean purple_pounce_get_save(const PurplePounce *pounce);
1.252 +
1.253 +/**
1.254 + * Returns whether or not an action is enabled.
1.255 + *
1.256 + * @param pounce The buddy pounce.
1.257 + * @param action The action name.
1.258 + *
1.259 + * @return @c TRUE if the action is enabled, or @c FALSE otherwise.
1.260 + */
1.261 +gboolean purple_pounce_action_is_enabled(const PurplePounce *pounce,
1.262 + const char *action);
1.263 +
1.264 +/**
1.265 + * Returns the value for an attribute in an action.
1.266 + *
1.267 + * @param pounce The buddy pounce.
1.268 + * @param action The action name.
1.269 + * @param attr The attribute name.
1.270 + *
1.271 + * @return The attribute value, if it exists, or @c NULL.
1.272 + */
1.273 +const char *purple_pounce_action_get_attribute(const PurplePounce *pounce,
1.274 + const char *action,
1.275 + const char *attr);
1.276 +
1.277 +/**
1.278 + * Returns the pounce-specific data.
1.279 + *
1.280 + * @param pounce The buddy pounce.
1.281 + *
1.282 + * @return The data specific to a buddy pounce.
1.283 + */
1.284 +void *purple_pounce_get_data(const PurplePounce *pounce);
1.285 +
1.286 +/**
1.287 + * Executes a pounce with the specified pouncer, pouncee, and event type.
1.288 + *
1.289 + * @param pouncer The account that will do the pouncing.
1.290 + * @param pouncee The buddy that is being pounced.
1.291 + * @param events The events that triggered the pounce.
1.292 + */
1.293 +void purple_pounce_execute(const PurpleAccount *pouncer, const char *pouncee,
1.294 + PurplePounceEvent events);
1.295 +
1.296 +/*@}*/
1.297 +
1.298 +/**************************************************************************/
1.299 +/** @name Buddy Pounce Subsystem API */
1.300 +/**************************************************************************/
1.301 +/*@{*/
1.302 +
1.303 +/**
1.304 + * Finds a pounce with the specified event(s) and buddy.
1.305 + *
1.306 + * @param pouncer The account to match against.
1.307 + * @param pouncee The buddy to match against.
1.308 + * @param events The event(s) to match against.
1.309 + *
1.310 + * @return The pounce if found, or @c NULL otherwise.
1.311 + */
1.312 +PurplePounce *purple_find_pounce(const PurpleAccount *pouncer,
1.313 + const char *pouncee, PurplePounceEvent events);
1.314 +
1.315 +
1.316 +/**
1.317 + * Loads the pounces.
1.318 + *
1.319 + * @return @c TRUE if the pounces could be loaded.
1.320 + */
1.321 +gboolean purple_pounces_load(void);
1.322 +
1.323 +/**
1.324 + * Registers a pounce handler for a UI.
1.325 + *
1.326 + * @param ui The UI name.
1.327 + * @param cb The callback function.
1.328 + * @param new_pounce The function called when a pounce is created.
1.329 + * @param free_pounce The function called when a pounce is freed.
1.330 + */
1.331 +void purple_pounces_register_handler(const char *ui, PurplePounceCb cb,
1.332 + void (*new_pounce)(PurplePounce *pounce),
1.333 + void (*free_pounce)(PurplePounce *pounce));
1.334 +
1.335 +/**
1.336 + * Unregisters a pounce handle for a UI.
1.337 + *
1.338 + * @param ui The UI name.
1.339 + */
1.340 +void purple_pounces_unregister_handler(const char *ui);
1.341 +
1.342 +/**
1.343 + * Returns a list of all registered buddy pounces.
1.344 + *
1.345 + * @constreturn The list of buddy pounces.
1.346 + */
1.347 +GList *purple_pounces_get_all(void);
1.348 +
1.349 +/**
1.350 + * Returns a list of registered buddy pounces for the ui-type.
1.351 + *
1.352 + * @param ui The ID of the UI using the core.
1.353 + *
1.354 + * @return The list of buddy pounces. The list should be freed by
1.355 + * the caller when it's no longer used.
1.356 + * @since 2.1.0
1.357 + */
1.358 +GList *purple_pounces_get_all_for_ui(const char *ui);
1.359 +
1.360 +/**
1.361 + * Returns the buddy pounce subsystem handle.
1.362 + *
1.363 + * @return The subsystem handle.
1.364 + */
1.365 +void *purple_pounces_get_handle(void);
1.366 +
1.367 +/**
1.368 + * Initializes the pounces subsystem.
1.369 + */
1.370 +void purple_pounces_init(void);
1.371 +
1.372 +/**
1.373 + * Uninitializes the pounces subsystem.
1.374 + */
1.375 +void purple_pounces_uninit(void);
1.376 +
1.377 +/*@}*/
1.378 +
1.379 +#ifdef __cplusplus
1.380 +}
1.381 +#endif
1.382 +
1.383 +#endif /* _PURPLE_POUNCE_H_ */