5228
|
1 /**
|
5234
|
2 * @file list.h Buddy List API
|
5228
|
3 * @ingroup core
|
|
4 *
|
|
5 * gaim
|
|
6 *
|
|
7 * Copyright (C) 2003, Sean Egan <sean.egan@binghamton.edu>
|
|
8 *
|
|
9 * This program is free software; you can redistribute it and/or modify
|
|
10 * it under the terms of the GNU General Public License as published by
|
|
11 * the Free Software Foundation; either version 2 of the License, or
|
|
12 * (at your option) any later version.
|
|
13 *
|
|
14 * This program is distributed in the hope that it will be useful,
|
|
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
17 * GNU General Public License for more details.
|
|
18 *
|
|
19 * You should have received a copy of the GNU General Public License
|
|
20 * along with this program; if not, write to the Free Software
|
|
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
22 */
|
|
23
|
|
24 /* I can't believe I let ChipX86 inspire me to write good code. -Sean */
|
|
25
|
|
26 #ifndef _LIST_H_
|
|
27 #define _LIST_H_
|
|
28
|
|
29 #include <glib.h>
|
|
30
|
|
31 /**************************************************************************/
|
|
32 /* Enumerations */
|
|
33 /**************************************************************************/
|
|
34 enum gaim_blist_node_type {
|
|
35 GAIM_BLIST_GROUP_NODE,
|
|
36 GAIM_BLIST_BUDDY_NODE,
|
5234
|
37 GAIM_BLIST_CHAT_NODE,
|
5228
|
38 GAIM_BLIST_OTHER_NODE,
|
|
39 };
|
|
40
|
5234
|
41 #define GAIM_BLIST_NODE_IS_CHAT(n) ((n)->type == GAIM_BLIST_CHAT_NODE)
|
5228
|
42 #define GAIM_BLIST_NODE_IS_BUDDY(n) ((n)->type == GAIM_BLIST_BUDDY_NODE)
|
|
43 #define GAIM_BLIST_NODE_IS_GROUP(n) ((n)->type == GAIM_BLIST_GROUP_NODE)
|
|
44
|
|
45 enum gaim_buddy_presence_state {
|
|
46 GAIM_BUDDY_SIGNING_OFF = -1,
|
|
47 GAIM_BUDDY_OFFLINE = 0,
|
|
48 GAIM_BUDDY_ONLINE,
|
|
49 GAIM_BUDDY_SIGNING_ON,
|
|
50 };
|
|
51
|
|
52 #define GAIM_BUDDY_IS_ONLINE(b) ((b)->present == GAIM_BUDDY_ONLINE || \
|
|
53 (b)->present == GAIM_BUDDY_SIGNING_ON)
|
|
54
|
|
55
|
|
56 /**************************************************************************/
|
|
57 /* Data Structures */
|
|
58 /**************************************************************************/
|
|
59
|
|
60 typedef struct _GaimBlistNode GaimBlistNode;
|
|
61 /**
|
|
62 * A Buddy list node. This can represent a group, a buddy, or anything else. This is a base class for struct buddy and
|
|
63 * struct group and for anything else that wants to put itself in the buddy list. */
|
|
64 struct _GaimBlistNode {
|
|
65 enum gaim_blist_node_type type; /**< The type of node this is */
|
|
66 GaimBlistNode *prev; /**< The sibling before this buddy. */
|
|
67 GaimBlistNode *next; /**< The sibling after this buddy. */
|
|
68 GaimBlistNode *parent; /**< The parent of this node */
|
|
69 GaimBlistNode *child; /**< The child of this node */
|
|
70 void *ui_data; /**< The UI can put data here. */
|
|
71 };
|
|
72
|
|
73 /**
|
|
74 * A buddy. This contains everything Gaim will ever need to know about someone on the buddy list. Everything.
|
|
75 */
|
|
76 struct buddy {
|
|
77 GaimBlistNode node; /**< The node that this buddy inherits from */
|
|
78 char *name; /**< The screenname of the buddy. */
|
|
79 char *alias; /**< The user-set alias of the buddy */
|
|
80 char *server_alias; /**< The server-specified alias of the buddy. (i.e. MSN "Friendly Names") */
|
|
81 enum gaim_buddy_presence_state present; /**< This is 0 if the buddy appears offline, 1 if he appears online, and 2 if
|
|
82 he has recently signed on */
|
|
83 int evil; /**< The warning level */
|
|
84 time_t signon; /**< The time the buddy signed on. */
|
|
85 int idle; /**< The time the buddy has been idle in minutes. */
|
|
86 int uc; /**< This is a cryptic bitmask that makes sense only to the prpl. This will get changed */
|
|
87 void *proto_data; /**< This allows the prpl to associate whatever data it wants with a buddy */
|
|
88 struct gaim_account *account; /**< the account this buddy belongs to */
|
|
89 GHashTable *settings; /**< per-buddy settings from the XML buddy list, set by plugins and the likes. */
|
|
90 guint timer; /**< The timer handle. */
|
|
91 };
|
|
92
|
|
93 /**
|
|
94 * A group. This contains everything Gaim will ever need to know about a group.
|
|
95 */
|
|
96 struct group {
|
|
97 GaimBlistNode node; /**< The node that this group inherits from */
|
|
98 char *name; /**< The name of this group. */
|
|
99 GHashTable *settings; /**< per-group settings from the XML buddy list, set by plugins and the likes. */
|
|
100 };
|
|
101
|
5234
|
102 /**
|
|
103 * A group. This contains everything Gaim needs to put a chat room in the
|
|
104 * buddy list.
|
|
105 */
|
|
106 struct chat {
|
|
107 GaimBlistNode node; /**< The node that this chat inherits from */
|
|
108 char *alias; /**< The display name of this chat. */
|
|
109 GHashTable *components; /**< the stuff the protocol needs to know to join the chat */
|
|
110 struct gaim_account *account; /**< The account this chat is attached to */
|
|
111 };
|
|
112
|
5228
|
113
|
|
114 /**
|
|
115 * The Buddy List
|
|
116 */
|
|
117 struct gaim_buddy_list {
|
|
118 GaimBlistNode *root; /**< The first node in the buddy list */
|
|
119 struct gaim_blist_ui_ops *ui_ops; /**< The UI operations for the buddy list */
|
|
120
|
|
121 void *ui_data; /**< UI-specific data. */
|
|
122 };
|
|
123
|
|
124 /**
|
|
125 * Buddy list UI operations.
|
|
126 *
|
|
127 * Any UI representing a buddy list must assign a filled-out gaim_window_ops
|
|
128 * structure to the buddy list core.
|
|
129 */
|
|
130 struct gaim_blist_ui_ops
|
|
131 {
|
|
132 void (*new_list)(struct gaim_buddy_list *list); /**< Sets UI-specific data on a buddy list. */
|
|
133 void (*new_node)(GaimBlistNode *node); /**< Sets UI-specific data on a node. */
|
|
134 void (*show)(struct gaim_buddy_list *list); /**< The core will call this when its finished doing it's core stuff */
|
|
135 void (*update)(struct gaim_buddy_list *list,
|
|
136 GaimBlistNode *node); /**< This will update a node in the buddy list. */
|
|
137 void (*remove)(struct gaim_buddy_list *list,
|
|
138 GaimBlistNode *node); /**< This removes a node from the list */
|
|
139 void (*destroy)(struct gaim_buddy_list *list); /**< When the list gets destroyed, this gets called to destroy the UI. */
|
|
140 void (*set_visible)(struct gaim_buddy_list *list,
|
|
141 gboolean show); /**< Hides or unhides the buddy list */
|
|
142
|
|
143 };
|
|
144
|
|
145 /**************************************************************************/
|
|
146 /** @name Buddy List API */
|
|
147 /**************************************************************************/
|
|
148 /*@{*/
|
|
149
|
|
150 /**
|
|
151 * Creates a new buddy list
|
|
152 */
|
|
153 struct gaim_buddy_list *gaim_blist_new();
|
|
154
|
|
155 /**
|
|
156 * Sets the main buddy list.
|
|
157 *
|
|
158 * @return The main buddy list.
|
|
159 */
|
|
160 void gaim_set_blist(struct gaim_buddy_list *blist);
|
|
161
|
|
162 /**
|
|
163 * Returns the main buddy list.
|
|
164 *
|
|
165 * @return The main buddy list.
|
|
166 */
|
|
167 struct gaim_buddy_list *gaim_get_blist(void);
|
|
168
|
|
169 /**
|
|
170 * Shows the buddy list, creating a new one if necessary.
|
|
171 *
|
|
172 */
|
|
173 void gaim_blist_show();
|
|
174
|
|
175
|
|
176 /**
|
|
177 * Destroys the buddy list window.
|
|
178 */
|
|
179 void gaim_blist_destroy();
|
|
180
|
|
181 /**
|
|
182 * Hides or unhides the buddy list.
|
|
183 *
|
|
184 * @param show Whether or not to show the buddy list
|
|
185 */
|
|
186 void gaim_blist_set_visible(gboolean show);
|
|
187
|
|
188 /**
|
|
189 * Updates a buddy's status.
|
5234
|
190 *
|
5228
|
191 * This needs to not take an int.
|
|
192 *
|
|
193 * @param buddy The buddy whose status has changed
|
|
194 * @param status The new status in cryptic prpl-understood code
|
|
195 */
|
|
196 void gaim_blist_update_buddy_status(struct buddy *buddy, int status);
|
|
197
|
|
198
|
|
199 /**
|
|
200 * Updates a buddy's presence.
|
|
201 *
|
|
202 * @param buddy The buddy whose presence has changed
|
|
203 * @param presence The new presence
|
|
204 */
|
|
205 void gaim_blist_update_buddy_presence(struct buddy *buddy, int presence);
|
|
206
|
|
207
|
|
208 /**
|
|
209 * Updates a buddy's idle time.
|
|
210 *
|
|
211 * @param buddy The buddy whose idle time has changed
|
|
212 * @param idle The buddy's idle time in minutes.
|
|
213 */
|
|
214 void gaim_blist_update_buddy_idle(struct buddy *buddy, int idle);
|
|
215
|
|
216
|
|
217 /**
|
|
218 * Updates a buddy's warning level.
|
|
219 *
|
|
220 * @param buddy The buddy whose warning level has changed
|
|
221 * @param evil The warning level as an int from 0 to 100 (or higher, I guess... but that'd be weird)
|
|
222 */
|
|
223 void gaim_blist_update_buddy_evil(struct buddy *buddy, int warning);
|
|
224
|
|
225 /**
|
|
226 * Updates a buddy's icon.
|
|
227 *
|
|
228 * @param buddy The buddy whose buddy icon has changed
|
|
229 */
|
|
230 void gaim_blist_update_buddy_icon(struct buddy *buddy);
|
|
231
|
|
232
|
|
233
|
|
234 /**
|
|
235 * Renames a buddy in the buddy list.
|
|
236 *
|
|
237 * @param buddy The buddy whose name will be changed.
|
|
238 * @param name The new name of the buddy.
|
|
239 */
|
|
240 void gaim_blist_rename_buddy(struct buddy *buddy, const char *name);
|
|
241
|
|
242
|
|
243 /**
|
|
244 * Aliases a buddy in the buddy list.
|
|
245 *
|
|
246 * @param buddy The buddy whose alias will be changed.
|
|
247 * @param alias The buddy's alias.
|
|
248 */
|
|
249 void gaim_blist_alias_buddy(struct buddy *buddy, const char *alias);
|
|
250
|
5234
|
251 /**
|
|
252 * Aliases a chat in the buddy list.
|
|
253 *
|
|
254 * @param chat The chat whose alias will be changed.
|
|
255 * @param alias The chat's new alias.
|
|
256 */
|
|
257 void gaim_blist_alias_chat(struct chat *chat, const char *alias);
|
5228
|
258
|
|
259 /**
|
|
260 * Renames a group
|
|
261 *
|
|
262 * @param group The group to rename
|
|
263 * @param name The new name
|
|
264 */
|
|
265 void gaim_blist_rename_group(struct group *group, const char *name);
|
|
266
|
5234
|
267 /**
|
|
268 * Creates a new chat for the buddy list
|
|
269 *
|
|
270 * @param account The account this chat will get added to
|
|
271 * @param alias The alias of the new chat
|
|
272 * @param components The info the prpl needs to join the chat
|
|
273 * @return A newly allocated chat
|
|
274 */
|
|
275 struct chat *gaim_chat_new(struct gaim_account *account, const char *alias, GHashTable *components);
|
|
276
|
|
277 /**
|
|
278 * Adds a new chat to the buddy list.
|
|
279 *
|
|
280 * The chat will be inserted right after node or appended to the end
|
|
281 * of group if node is NULL. If both are NULL, the buddy will be added to
|
|
282 * the "Chats" group.
|
|
283 *
|
|
284 * @param chat The new chat who gets added
|
|
285 * @param group The group to add the new chat to.
|
|
286 * @param node The insertion point
|
|
287 */
|
|
288 void gaim_blist_add_chat(struct chat *chat, struct group *group, GaimBlistNode *node);
|
5228
|
289
|
|
290 /**
|
|
291 * Creates a new buddy
|
|
292 *
|
|
293 * @param account The account this buddy will get added to
|
|
294 * @param screenname The screenname of the new buddy
|
|
295 * @param alias The alias of the new buddy (or NULL if unaliased)
|
|
296 * @return A newly allocated buddy
|
|
297 */
|
|
298 struct buddy *gaim_buddy_new(struct gaim_account *account, const char *screenname, const char *alias);
|
|
299
|
|
300 /**
|
|
301 * Adds a new buddy to the buddy list.
|
|
302 *
|
|
303 * The buddy will be inserted right after node or appended to the end
|
|
304 * of group if node is NULL. If both are NULL, the buddy will be added to
|
|
305 * the "Buddies" group.
|
|
306 *
|
|
307 * @param buddy The new buddy who gets added
|
|
308 * @param group The group to add the new buddy to.
|
|
309 * @param node The insertion point
|
|
310 */
|
|
311 void gaim_blist_add_buddy(struct buddy *buddy, struct group *group, GaimBlistNode *node);
|
|
312
|
|
313 /**
|
|
314 * Creates a new group
|
|
315 *
|
|
316 * You can't have more than one group with the same name. Sorry. If you pass this the
|
|
317 * name of a group that already exists, it will return that group.
|
|
318 *
|
|
319 * @param name The name of the new group
|
|
320 * @return A new group struct
|
|
321 */
|
|
322 struct group *gaim_group_new(const char *name);
|
|
323
|
|
324 /**
|
|
325 * Adds a new group to the buddy list.
|
|
326 *
|
|
327 * The new group will be inserted after insert or appended to the end of
|
|
328 * the list if node is NULL.
|
|
329 *
|
|
330 * @param group The group to add the new buddy to.
|
|
331 * @param node The insertion point
|
|
332 */
|
|
333 void gaim_blist_add_group(struct group *group, GaimBlistNode *node);
|
|
334
|
|
335 /**
|
|
336 * Removes a buddy from the buddy list and frees the memory allocated to it.
|
|
337 *
|
|
338 * @param buddy The buddy to be removed
|
|
339 */
|
|
340 void gaim_blist_remove_buddy(struct buddy *buddy);
|
|
341
|
|
342 /**
|
5234
|
343 * Removes a chat from the buddy list and frees the memory allocated to it.
|
|
344 *
|
|
345 * @param chat The chat to be removed
|
|
346 */
|
|
347 void gaim_blist_remove_chat(struct chat *chat);
|
|
348
|
|
349 /**
|
5228
|
350 * Removes a group from the buddy list and frees the memory allocated to it and to
|
|
351 * its children
|
|
352 *
|
|
353 * @param group The group to be removed
|
|
354 */
|
|
355 void gaim_blist_remove_group(struct group *group);
|
|
356
|
|
357 /**
|
|
358 * Returns the alias of a buddy.
|
|
359 *
|
|
360 * @param buddy The buddy whose name will be returned.
|
|
361 * @return The alias (if set), server alias (if option is set), or NULL.
|
|
362 */
|
|
363 char *gaim_get_buddy_alias_only(struct buddy *buddy);
|
|
364
|
|
365
|
|
366 /**
|
|
367 * Returns the correct name to display for a buddy.
|
|
368 *
|
|
369 * @param buddy The buddy whose name will be returned.
|
|
370 * @return The alias (if set), server alias (if option is set), screenname, or "Unknown"
|
|
371 */
|
|
372 char *gaim_get_buddy_alias(struct buddy *buddy);
|
|
373
|
|
374 /**
|
|
375 * Finds the buddy struct given a screenname and an account
|
|
376 *
|
|
377 * @param name The buddy's screenname
|
|
378 * @param account The account this buddy belongs to
|
|
379 * @return The buddy or NULL if the buddy does not exist
|
|
380 */
|
|
381 struct buddy *gaim_find_buddy(struct gaim_account *account, const char *name);
|
|
382
|
|
383 /**
|
|
384 * Finds a group by name
|
|
385 *
|
|
386 * @param name The groups name
|
|
387 * @return The group or NULL if the group does not exist
|
|
388 */
|
|
389 struct group *gaim_find_group(const char *name);
|
|
390
|
|
391 /**
|
|
392 * Returns the group of which the buddy is a member.
|
|
393 *
|
|
394 * @param buddy The buddy
|
|
395 * @return The group or NULL if the buddy is not in a group
|
|
396 */
|
|
397 struct group *gaim_find_buddys_group(struct buddy *buddy);
|
|
398
|
|
399
|
|
400 /**
|
|
401 * Returns a list of accounts that have buddies in this group
|
|
402 *
|
|
403 * @param group The group
|
|
404 * @return A list of gaim_accounts
|
|
405 */
|
|
406 GSList *gaim_group_get_accounts(struct group *g);
|
|
407
|
|
408 /**
|
|
409 * Determines whether an account owns any buddies in a given group
|
|
410 *
|
|
411 * @param g The group to search through.
|
|
412 * @param account The account.
|
|
413 */
|
|
414 gboolean gaim_group_on_account(struct group *g, struct gaim_account *account);
|
|
415
|
|
416 /**
|
5234
|
417 * Called when an account gets signed on. Tells the UI to update all the
|
|
418 * buddies.
|
|
419 *
|
|
420 * @param account The account
|
|
421 */
|
|
422 void gaim_blist_add_account(struct gaim_account *account);
|
|
423
|
|
424
|
|
425 /**
|
5228
|
426 * Called when an account gets signed off. Sets the presence of all the buddies to 0
|
|
427 * and tells the UI to update them.
|
|
428 *
|
|
429 * @param account The account
|
|
430 */
|
|
431 void gaim_blist_remove_account(struct gaim_account *account);
|
|
432
|
|
433
|
|
434 /**
|
|
435 * Determines the total size of a group
|
|
436 *
|
|
437 * @param group The group
|
|
438 * @param offline Count buddies in offline accounts
|
|
439 * @return The number of buddies in the group
|
|
440 */
|
|
441 int gaim_blist_get_group_size(struct group *group, gboolean offline);
|
|
442
|
|
443 /**
|
|
444 * Determines the number of online buddies in a group
|
|
445 *
|
|
446 * @param group The group
|
|
447 * @return The number of online buddies in the group, or 0 if the group is NULL
|
|
448 */
|
|
449 int gaim_blist_get_group_online_count(struct group *group);
|
|
450
|
|
451 /*@}*/
|
|
452
|
|
453 /****************************************************************************************/
|
|
454 /** @name Buddy list file management API */
|
|
455 /****************************************************************************************/
|
|
456
|
|
457 /*@{*/
|
|
458 /**
|
|
459 * Saves the buddy list to file
|
|
460 */
|
|
461 void gaim_blist_save();
|
|
462
|
|
463 /**
|
|
464 * Parses the toc-style buddy list used in older versions of Gaim and for SSI in toc.c
|
|
465 *
|
|
466 * @param account This is the account that the buddies and groups from config will get added to
|
|
467 * @param config This is the toc-style buddy list data
|
|
468 */
|
|
469 void parse_toc_buddy_list(struct gaim_account *account, char *config);
|
|
470
|
|
471
|
|
472 /**
|
|
473 * Loads the buddy list from ~/.gaim/blist.xml.
|
|
474 */
|
|
475 void gaim_blist_load();
|
|
476
|
|
477 /**
|
|
478 * Associates some data with the group in the xml buddy list
|
|
479 *
|
|
480 * @param g The group the data is associated with
|
|
481 * @param key The key used to retrieve the data
|
|
482 * @param value The data to set
|
|
483 */
|
|
484 void gaim_group_set_setting(struct group *g, const char *key, const char *value);
|
|
485
|
|
486 /**
|
|
487 * Retrieves data from the XML buddy list set by gaim_group_set_setting())
|
|
488 *
|
|
489 * @param g The group to retrieve data from
|
|
490 * @param key The key to retrieve the data with
|
|
491 * @return The associated data or NULL if no data is associated
|
|
492 */
|
|
493 char *gaim_group_get_setting(struct group *g, const char *key);
|
|
494
|
|
495
|
|
496 /**
|
|
497 * Associates some data with the buddy in the xml buddy list
|
|
498 *
|
|
499 * @param b The buddy the data is associated with
|
|
500 * @param key The key used to retrieve the data
|
|
501 * @param value The data to set
|
|
502 */
|
|
503 void gaim_buddy_set_setting(struct buddy *b, const char *key, const char *value);
|
|
504
|
|
505 /**
|
|
506 * Retrieves data from the XML buddy list set by gaim_buddy_set_setting())
|
|
507 *
|
|
508 * @param b The buddy to retrieve data from
|
|
509 * @param key The key to retrieve the data with
|
|
510 * @return The associated data or NULL if no data is associated
|
|
511 */
|
|
512 char *gaim_buddy_get_setting(struct buddy *b, const char *key);
|
|
513
|
|
514 /*@}*/
|
|
515
|
|
516 /**************************************************************************/
|
|
517 /** @name UI Registration Functions */
|
|
518 /**************************************************************************/
|
|
519 /*@{*/
|
|
520
|
|
521 /**
|
|
522 * Sets the UI operations structure to be used for the buddy list.
|
|
523 *
|
|
524 * @param ops The ops struct.
|
|
525 */
|
|
526 void gaim_set_blist_ui_ops(struct gaim_blist_ui_ops *ops);
|
|
527
|
|
528 /**
|
|
529 * Returns the UI operations structure to be used for the buddy list.
|
|
530 *
|
|
531 * @return The UI operations structure.
|
|
532 */
|
|
533 struct gaim_blist_ui_ops *gaim_get_blist_ui_ops(void);
|
|
534
|
|
535 /*@}*/
|
|
536
|
|
537 #endif /* _LIST_H_ */
|