15374
|
1 /**
|
|
2 * @file pounce.h Buddy Pounce API
|
|
3 * @ingroup core
|
20074
|
4 */
|
|
5
|
|
6 /* purple
|
15374
|
7 *
|
15823
|
8 * Purple is the legal property of its developers, whose names are too numerous
|
15374
|
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
|
19680
44b4e8bd759b
The FSF changed its address a while ago; our files were out of date.
John Bailey <rekkanoryo@rekkanoryo.org>
diff
changeset
|
24 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
|
15374
|
25 */
|
15823
|
26 #ifndef _PURPLE_POUNCE_H_
|
|
27 #define _PURPLE_POUNCE_H_
|
15374
|
28
|
15823
|
29 typedef struct _PurplePounce PurplePounce;
|
15374
|
30
|
|
31 #include <glib.h>
|
|
32 #include "account.h"
|
|
33
|
|
34 /**
|
|
35 * Events that trigger buddy pounces.
|
|
36 */
|
|
37 typedef enum
|
|
38 {
|
15823
|
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 */
|
15374
|
50
|
15823
|
51 } PurplePounceEvent;
|
15374
|
52
|
|
53 typedef enum
|
|
54 {
|
15823
|
55 PURPLE_POUNCE_OPTION_NONE = 0x00, /**< No Option */
|
|
56 PURPLE_POUNCE_OPTION_AWAY = 0x01 /**< Pounce only when away */
|
|
57 } PurplePounceOption;
|
15374
|
58
|
|
59 /** A pounce callback. */
|
15823
|
60 typedef void (*PurplePounceCb)(PurplePounce *, PurplePounceEvent, void *);
|
15374
|
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 */
|
15823
|
70 struct _PurplePounce
|
15374
|
71 {
|
|
72 char *ui_type; /**< The type of UI. */
|
|
73
|
15823
|
74 PurplePounceEvent events; /**< The event(s) to pounce on. */
|
|
75 PurplePounceOption options; /**< The pounce options */
|
|
76 PurpleAccount *pouncer; /**< The user who is pouncing. */
|
15374
|
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 */
|
15823
|
107 PurplePounce *purple_pounce_new(const char *ui_type, PurpleAccount *pouncer,
|
|
108 const char *pouncee, PurplePounceEvent event,
|
|
109 PurplePounceOption option);
|
15374
|
110
|
|
111 /**
|
|
112 * Destroys a buddy pounce.
|
|
113 *
|
|
114 * @param pounce The buddy pounce.
|
|
115 */
|
15823
|
116 void purple_pounce_destroy(PurplePounce *pounce);
|
15374
|
117
|
|
118 /**
|
|
119 * Destroys all buddy pounces for the account
|
|
120 *
|
|
121 * @param account The account to remove all pounces from.
|
|
122 */
|
15823
|
123 void purple_pounce_destroy_all_by_account(PurpleAccount *account);
|
15374
|
124
|
|
125 /**
|
|
126 * Sets the events a pounce should watch for.
|
|
127 *
|
|
128 * @param pounce The buddy pounce.
|
|
129 * @param events The events to watch for.
|
|
130 */
|
15823
|
131 void purple_pounce_set_events(PurplePounce *pounce, PurplePounceEvent events);
|
15374
|
132
|
|
133 /**
|
|
134 * Sets the options for a pounce.
|
|
135 *
|
|
136 * @param pounce The buddy pounce.
|
|
137 * @param options The options for the pounce.
|
|
138 */
|
15823
|
139 void purple_pounce_set_options(PurplePounce *pounce, PurplePounceOption options);
|
15374
|
140
|
|
141 /**
|
|
142 * Sets the account that will do the pouncing.
|
|
143 *
|
|
144 * @param pounce The buddy pounce.
|
|
145 * @param pouncer The account that will pounce.
|
|
146 */
|
15823
|
147 void purple_pounce_set_pouncer(PurplePounce *pounce, PurpleAccount *pouncer);
|
15374
|
148
|
|
149 /**
|
|
150 * Sets the buddy a pounce should pounce on.
|
|
151 *
|
|
152 * @param pounce The buddy pounce.
|
|
153 * @param pouncee The buddy to pounce on.
|
|
154 */
|
15823
|
155 void purple_pounce_set_pouncee(PurplePounce *pounce, const char *pouncee);
|
15374
|
156
|
|
157 /**
|
|
158 * Sets whether or not the pounce should be saved after execution.
|
|
159 *
|
|
160 * @param pounce The buddy pounce.
|
|
161 * @param save @c TRUE if the pounce should be saved, or @c FALSE otherwise.
|
|
162 */
|
15823
|
163 void purple_pounce_set_save(PurplePounce *pounce, gboolean save);
|
15374
|
164
|
|
165 /**
|
|
166 * Registers an action type for the pounce.
|
|
167 *
|
|
168 * @param pounce The buddy pounce.
|
|
169 * @param name The action name.
|
|
170 */
|
15823
|
171 void purple_pounce_action_register(PurplePounce *pounce, const char *name);
|
15374
|
172
|
|
173 /**
|
|
174 * Enables or disables an action for a pounce.
|
|
175 *
|
|
176 * @param pounce The buddy pounce.
|
|
177 * @param action The name of the action.
|
|
178 * @param enabled The enabled state.
|
|
179 */
|
15823
|
180 void purple_pounce_action_set_enabled(PurplePounce *pounce, const char *action,
|
15374
|
181 gboolean enabled);
|
|
182
|
|
183 /**
|
|
184 * Sets a value for an attribute in an action.
|
|
185 *
|
|
186 * If @a value is @c NULL, the value will be unset.
|
|
187 *
|
|
188 * @param pounce The buddy pounce.
|
|
189 * @param action The action name.
|
|
190 * @param attr The attribute name.
|
|
191 * @param value The value.
|
|
192 */
|
15823
|
193 void purple_pounce_action_set_attribute(PurplePounce *pounce, const char *action,
|
15374
|
194 const char *attr, const char *value);
|
|
195
|
|
196 /**
|
|
197 * Sets the pounce-specific data.
|
|
198 *
|
|
199 * @param pounce The buddy pounce.
|
|
200 * @param data Data specific to the pounce.
|
|
201 */
|
15823
|
202 void purple_pounce_set_data(PurplePounce *pounce, void *data);
|
15374
|
203
|
|
204 /**
|
|
205 * Returns the events a pounce should watch for.
|
|
206 *
|
|
207 * @param pounce The buddy pounce.
|
|
208 *
|
|
209 * @return The events the pounce is watching for.
|
|
210 */
|
15823
|
211 PurplePounceEvent purple_pounce_get_events(const PurplePounce *pounce);
|
15374
|
212
|
|
213 /**
|
|
214 * Returns the options for a pounce.
|
|
215 *
|
|
216 * @param pounce The buddy pounce.
|
|
217 *
|
|
218 * @return The options for the pounce.
|
|
219 */
|
15823
|
220 PurplePounceOption purple_pounce_get_options(const PurplePounce *pounce);
|
15374
|
221
|
|
222 /**
|
|
223 * Returns the account that will do the pouncing.
|
|
224 *
|
|
225 * @param pounce The buddy pounce.
|
|
226 *
|
|
227 * @return The account that will pounce.
|
|
228 */
|
15823
|
229 PurpleAccount *purple_pounce_get_pouncer(const PurplePounce *pounce);
|
15374
|
230
|
|
231 /**
|
|
232 * Returns the buddy a pounce should pounce on.
|
|
233 *
|
|
234 * @param pounce The buddy pounce.
|
|
235 *
|
|
236 * @return The buddy to pounce on.
|
|
237 */
|
15823
|
238 const char *purple_pounce_get_pouncee(const PurplePounce *pounce);
|
15374
|
239
|
|
240 /**
|
|
241 * Returns whether or not the pounce should save after execution.
|
|
242 *
|
|
243 * @param pounce The buddy pounce.
|
|
244 *
|
|
245 * @return @c TRUE if the pounce should be saved after execution, or
|
|
246 * @c FALSE otherwise.
|
|
247 */
|
15823
|
248 gboolean purple_pounce_get_save(const PurplePounce *pounce);
|
15374
|
249
|
|
250 /**
|
|
251 * Returns whether or not an action is enabled.
|
|
252 *
|
|
253 * @param pounce The buddy pounce.
|
|
254 * @param action The action name.
|
|
255 *
|
|
256 * @return @c TRUE if the action is enabled, or @c FALSE otherwise.
|
|
257 */
|
15823
|
258 gboolean purple_pounce_action_is_enabled(const PurplePounce *pounce,
|
15374
|
259 const char *action);
|
|
260
|
|
261 /**
|
|
262 * Returns the value for an attribute in an action.
|
|
263 *
|
|
264 * @param pounce The buddy pounce.
|
|
265 * @param action The action name.
|
|
266 * @param attr The attribute name.
|
|
267 *
|
|
268 * @return The attribute value, if it exists, or @c NULL.
|
|
269 */
|
15823
|
270 const char *purple_pounce_action_get_attribute(const PurplePounce *pounce,
|
15374
|
271 const char *action,
|
|
272 const char *attr);
|
|
273
|
|
274 /**
|
|
275 * Returns the pounce-specific data.
|
|
276 *
|
|
277 * @param pounce The buddy pounce.
|
|
278 *
|
|
279 * @return The data specific to a buddy pounce.
|
|
280 */
|
15823
|
281 void *purple_pounce_get_data(const PurplePounce *pounce);
|
15374
|
282
|
|
283 /**
|
|
284 * Executes a pounce with the specified pouncer, pouncee, and event type.
|
|
285 *
|
|
286 * @param pouncer The account that will do the pouncing.
|
|
287 * @param pouncee The buddy that is being pounced.
|
|
288 * @param events The events that triggered the pounce.
|
|
289 */
|
15823
|
290 void purple_pounce_execute(const PurpleAccount *pouncer, const char *pouncee,
|
|
291 PurplePounceEvent events);
|
15374
|
292
|
|
293 /*@}*/
|
|
294
|
|
295 /**************************************************************************/
|
|
296 /** @name Buddy Pounce Subsystem API */
|
|
297 /**************************************************************************/
|
|
298 /*@{*/
|
|
299
|
|
300 /**
|
|
301 * Finds a pounce with the specified event(s) and buddy.
|
|
302 *
|
|
303 * @param pouncer The account to match against.
|
|
304 * @param pouncee The buddy to match against.
|
|
305 * @param events The event(s) to match against.
|
|
306 *
|
|
307 * @return The pounce if found, or @c NULL otherwise.
|
|
308 */
|
15823
|
309 PurplePounce *purple_find_pounce(const PurpleAccount *pouncer,
|
|
310 const char *pouncee, PurplePounceEvent events);
|
15374
|
311
|
|
312
|
|
313 /**
|
|
314 * Loads the pounces.
|
|
315 *
|
|
316 * @return @c TRUE if the pounces could be loaded.
|
|
317 */
|
15823
|
318 gboolean purple_pounces_load(void);
|
15374
|
319
|
|
320 /**
|
|
321 * Registers a pounce handler for a UI.
|
|
322 *
|
|
323 * @param ui The UI name.
|
|
324 * @param cb The callback function.
|
|
325 * @param new_pounce The function called when a pounce is created.
|
|
326 * @param free_pounce The function called when a pounce is freed.
|
|
327 */
|
15823
|
328 void purple_pounces_register_handler(const char *ui, PurplePounceCb cb,
|
|
329 void (*new_pounce)(PurplePounce *pounce),
|
|
330 void (*free_pounce)(PurplePounce *pounce));
|
15374
|
331
|
|
332 /**
|
|
333 * Unregisters a pounce handle for a UI.
|
|
334 *
|
|
335 * @param ui The UI name.
|
|
336 */
|
15823
|
337 void purple_pounces_unregister_handler(const char *ui);
|
15374
|
338
|
|
339 /**
|
|
340 * Returns a list of all registered buddy pounces.
|
|
341 *
|
20891
59c9c04879af
Replace a bunch of @return markers with @constreturn markers. I believe these
Etan Reisner <pidgin@unreliablesource.net>
diff
changeset
|
342 * @constreturn The list of buddy pounces.
|
15374
|
343 */
|
15823
|
344 GList *purple_pounces_get_all(void);
|
15374
|
345
|
|
346 /**
|
18137
323272a9bb65
Fix #1574. (Pidgin and Finch show each other's pounces, interact in
Sadrul Habib Chowdhury <imadil@gmail.com>
diff
changeset
|
347 * Returns a list of registered buddy pounces for the ui-type.
|
323272a9bb65
Fix #1574. (Pidgin and Finch show each other's pounces, interact in
Sadrul Habib Chowdhury <imadil@gmail.com>
diff
changeset
|
348 *
|
323272a9bb65
Fix #1574. (Pidgin and Finch show each other's pounces, interact in
Sadrul Habib Chowdhury <imadil@gmail.com>
diff
changeset
|
349 * @param ui The ID of the UI using the core.
|
323272a9bb65
Fix #1574. (Pidgin and Finch show each other's pounces, interact in
Sadrul Habib Chowdhury <imadil@gmail.com>
diff
changeset
|
350 *
|
323272a9bb65
Fix #1574. (Pidgin and Finch show each other's pounces, interact in
Sadrul Habib Chowdhury <imadil@gmail.com>
diff
changeset
|
351 * @return The list of buddy pounces. The list should be freed by
|
323272a9bb65
Fix #1574. (Pidgin and Finch show each other's pounces, interact in
Sadrul Habib Chowdhury <imadil@gmail.com>
diff
changeset
|
352 * the caller when it's no longer used.
|
323272a9bb65
Fix #1574. (Pidgin and Finch show each other's pounces, interact in
Sadrul Habib Chowdhury <imadil@gmail.com>
diff
changeset
|
353 * @since 2.1.0
|
323272a9bb65
Fix #1574. (Pidgin and Finch show each other's pounces, interact in
Sadrul Habib Chowdhury <imadil@gmail.com>
diff
changeset
|
354 */
|
323272a9bb65
Fix #1574. (Pidgin and Finch show each other's pounces, interact in
Sadrul Habib Chowdhury <imadil@gmail.com>
diff
changeset
|
355 GList *purple_pounces_get_all_for_ui(const char *ui);
|
323272a9bb65
Fix #1574. (Pidgin and Finch show each other's pounces, interact in
Sadrul Habib Chowdhury <imadil@gmail.com>
diff
changeset
|
356
|
323272a9bb65
Fix #1574. (Pidgin and Finch show each other's pounces, interact in
Sadrul Habib Chowdhury <imadil@gmail.com>
diff
changeset
|
357 /**
|
15374
|
358 * Returns the buddy pounce subsystem handle.
|
|
359 *
|
|
360 * @return The subsystem handle.
|
|
361 */
|
15823
|
362 void *purple_pounces_get_handle(void);
|
15374
|
363
|
|
364 /**
|
|
365 * Initializes the pounces subsystem.
|
|
366 */
|
15823
|
367 void purple_pounces_init(void);
|
15374
|
368
|
|
369 /**
|
|
370 * Uninitializes the pounces subsystem.
|
|
371 */
|
15823
|
372 void purple_pounces_uninit(void);
|
15374
|
373
|
|
374 /*@}*/
|
|
375
|
|
376 #ifdef __cplusplus
|
|
377 }
|
|
378 #endif
|
|
379
|
15823
|
380 #endif /* _PURPLE_POUNCE_H_ */
|