Mercurial > pidgin3 / file comparison

comparison: src/blist.h

src/blist.h

branch
cpw.khc.msnp14
changeset 20472
6a6d2ef151e6
parent 13912
463b4fa9f067
parent 20469
b2836a24d81e
child 20473
91e1b3a49d10
equal deleted inserted replaced
13912:463b4fa9f067 20472:6a6d2ef151e6
1 /**
2 * @file blist.h Buddy List API
3 * @ingroup core
4 *
5 * gaim
6 *
7 * Gaim 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 _GAIM_BLIST_H_
26 #define _GAIM_BLIST_H_
27
28 /* I can't believe I let ChipX86 inspire me to write good code. -Sean */
29
30 #include <glib.h>
31
32 typedef struct _GaimBuddyList GaimBuddyList;
33 typedef struct _GaimBlistUiOps GaimBlistUiOps;
34 typedef struct _GaimBlistNode GaimBlistNode;
35
36 typedef struct _GaimChat GaimChat;
37 typedef struct _GaimGroup GaimGroup;
38 typedef struct _GaimContact GaimContact;
39 typedef struct _GaimBuddy GaimBuddy;
40
41 /**************************************************************************/
42 /* Enumerations */
43 /**************************************************************************/
44 typedef enum
45 {
46 GAIM_BLIST_GROUP_NODE,
47 GAIM_BLIST_CONTACT_NODE,
48 GAIM_BLIST_BUDDY_NODE,
49 GAIM_BLIST_CHAT_NODE,
50 GAIM_BLIST_OTHER_NODE
51
52 } GaimBlistNodeType;
53
54 #define GAIM_BLIST_NODE_IS_CHAT(n) ((n)->type == GAIM_BLIST_CHAT_NODE)
55 #define GAIM_BLIST_NODE_IS_BUDDY(n) ((n)->type == GAIM_BLIST_BUDDY_NODE)
56 #define GAIM_BLIST_NODE_IS_CONTACT(n) ((n)->type == GAIM_BLIST_CONTACT_NODE)
57 #define GAIM_BLIST_NODE_IS_GROUP(n) ((n)->type == GAIM_BLIST_GROUP_NODE)
58
59 #define GAIM_BUDDY_IS_ONLINE(b) \
60 ((b) != NULL && gaim_account_is_connected((b)->account) && \
61 gaim_presence_is_online(gaim_buddy_get_presence(b)))
62
63 typedef enum
64 {
65 GAIM_BLIST_NODE_FLAG_NO_SAVE = 1 /**< node should not be saved with the buddy list */
66
67 } GaimBlistNodeFlags;
68
69 #define GAIM_BLIST_NODE_HAS_FLAG(b, f) ((b)->flags & (f))
70 #define GAIM_BLIST_NODE_SHOULD_SAVE(b) (! GAIM_BLIST_NODE_HAS_FLAG(b, GAIM_BLIST_NODE_FLAG_NO_SAVE))
71
72 #define GAIM_BLIST_NODE_NAME(n) ((n)->type == GAIM_BLIST_CHAT_NODE ? gaim_chat_get_name((GaimChat*)n) : \
73 (n)->type == GAIM_BLIST_BUDDY_NODE ? gaim_buddy_get_name((GaimBuddy*)n) : NULL)
74
75 #include "account.h"
76 #include "buddyicon.h"
77 #include "status.h"
78
79 /**************************************************************************/
80 /* Data Structures */
81 /**************************************************************************/
82
83 /**
84 * A Buddy list node. This can represent a group, a buddy, or anything else.
85 * This is a base class for struct buddy and struct group and for anything
86 * else that wants to put itself in the buddy list. */
87 struct _GaimBlistNode {
88 GaimBlistNodeType type; /**< The type of node this is */
89 GaimBlistNode *prev; /**< The sibling before this buddy. */
90 GaimBlistNode *next; /**< The sibling after this buddy. */
91 GaimBlistNode *parent; /**< The parent of this node */
92 GaimBlistNode *child; /**< The child of this node */
93 GHashTable *settings; /**< per-node settings */
94 void *ui_data; /**< The UI can put data here. */
95 GaimBlistNodeFlags flags; /**< The buddy flags */
96 };
97
98 /**
99 * A buddy. This contains everything Gaim will ever need to know about someone on the buddy list. Everything.
100 */
101 struct _GaimBuddy {
102 GaimBlistNode node; /**< The node that this buddy inherits from */
103 char *name; /**< The screenname of the buddy. */
104 char *alias; /**< The user-set alias of the buddy */
105 char *server_alias; /**< The server-specified alias of the buddy. (i.e. MSN "Friendly Names") */
106 void *proto_data; /**< This allows the prpl to associate whatever data it wants with a buddy */
107 GaimBuddyIcon *icon; /**< The buddy icon. */
108 GaimAccount *account; /**< the account this buddy belongs to */
109 GaimPresence *presence;
110 };
111
112 /**
113 * A contact. This contains everything Gaim will ever need to know about a contact.
114 */
115 struct _GaimContact {
116 GaimBlistNode node; /**< The node that this contact inherits from. */
117 char *alias; /**< The user-set alias of the contact */
118 int totalsize; /**< The number of buddies in this contact */
119 int currentsize; /**< The number of buddies in this contact corresponding to online accounts */
120 int online; /**< The number of buddies in this contact who are currently online */
121 GaimBuddy *priority; /**< The "top" buddy for this contact */
122 gboolean priority_valid; /**< Is priority valid? */
123 };
124
125
126 /**
127 * A group. This contains everything Gaim will ever need to know about a group.
128 */
129 struct _GaimGroup {
130 GaimBlistNode node; /**< The node that this group inherits from */
131 char *name; /**< The name of this group. */
132 int totalsize; /**< The number of chats and contacts in this group */
133 int currentsize; /**< The number of chats and contacts in this group corresponding to online accounts */
134 int online; /**< The number of chats and contacts in this group who are currently online */
135 };
136
137 /**
138 * A chat. This contains everything Gaim needs to put a chat room in the
139 * buddy list.
140 */
141 struct _GaimChat {
142 GaimBlistNode node; /**< The node that this chat inherits from */
143 char *alias; /**< The display name of this chat. */
144 GHashTable *components; /**< the stuff the protocol needs to know to join the chat */
145 GaimAccount *account; /**< The account this chat is attached to */
146 };
147
148
149 /**
150 * The Buddy List
151 */
152 struct _GaimBuddyList {
153 GaimBlistNode *root; /**< The first node in the buddy list */
154 GHashTable *buddies; /**< Every buddy in this list */
155 GaimBlistUiOps *ui_ops; /**< The UI operations for the buddy list */
156
157 void *ui_data; /**< UI-specific data. */
158 };
159
160 /**
161 * Buddy list UI operations.
162 *
163 * Any UI representing a buddy list must assign a filled-out GaimBlistUiOps
164 * structure to the buddy list core.
165 */
166 struct _GaimBlistUiOps
167 {
168 void (*new_list)(GaimBuddyList *list); /**< Sets UI-specific data on a buddy list. */
169 void (*new_node)(GaimBlistNode *node); /**< Sets UI-specific data on a node. */
170 void (*show)(GaimBuddyList *list); /**< The core will call this when it's finished doing its core stuff */
171 void (*update)(GaimBuddyList *list,
172 GaimBlistNode *node); /**< This will update a node in the buddy list. */
173 void (*remove)(GaimBuddyList *list,
174 GaimBlistNode *node); /**< This removes a node from the list */
175 void (*destroy)(GaimBuddyList *list); /**< When the list gets destroyed, this gets called to destroy the UI. */
176 void (*set_visible)(GaimBuddyList *list,
177 gboolean show); /**< Hides or unhides the buddy list */
178 void (*request_add_buddy)(GaimAccount *account, const char *username,
179 const char *group, const char *alias);
180 void (*request_add_chat)(GaimAccount *account, GaimGroup *group,
181 const char *alias, const char *name);
182 void (*request_add_group)(void);
183 };
184
185 #ifdef __cplusplus
186 extern "C" {
187 #endif
188
189 /**************************************************************************/
190 /** @name Buddy List API */
191 /**************************************************************************/
192 /*@{*/
193
194 /**
195 * Creates a new buddy list
196 *
197 * @return The new buddy list.
198 */
199 GaimBuddyList *gaim_blist_new(void);
200
201 /**
202 * Sets the main buddy list.
203 *
204 * @param blist The buddy list you want to use.
205 */
206 void gaim_set_blist(GaimBuddyList *blist);
207
208 /**
209 * Returns the main buddy list.
210 *
211 * @return The main buddy list.
212 */
213 GaimBuddyList *gaim_get_blist(void);
214
215 /**
216 * Returns the root node of the main buddy list.
217 *
218 * @return The root node.
219 */
220 GaimBlistNode *gaim_blist_get_root(void);
221
222 /**
223 * Returns the next node of a given node. This function is to be used to iterate
224 * over the tree returned by gaim_get_blist.
225 *
226 * @param node A node.
227 * @param offline Whether to include nodes for offline accounts
228 * @return The next node
229 */
230 GaimBlistNode *gaim_blist_node_next(GaimBlistNode *node, gboolean offline);
231
232 /**
233 * Shows the buddy list, creating a new one if necessary.
234 */
235 void gaim_blist_show(void);
236
237
238 /**
239 * Destroys the buddy list window.
240 */
241 void gaim_blist_destroy(void);
242
243 /**
244 * Hides or unhides the buddy list.
245 *
246 * @param show Whether or not to show the buddy list
247 */
248 void gaim_blist_set_visible(gboolean show);
249
250 /**
251 * Updates a buddy's status.
252 *
253 * @param buddy The buddy whose status has changed.
254 * @param old_status The status from which we are changing.
255 */
256 void gaim_blist_update_buddy_status(GaimBuddy *buddy, GaimStatus *old_status);
257
258 /**
259 * Updates a buddy's icon.
260 *
261 * @param buddy The buddy whose buddy icon has changed
262 */
263 void gaim_blist_update_buddy_icon(GaimBuddy *buddy);
264
265 /**
266 * Renames a buddy in the buddy list.
267 *
268 * @param buddy The buddy whose name will be changed.
269 * @param name The new name of the buddy.
270 */
271 void gaim_blist_rename_buddy(GaimBuddy *buddy, const char *name);
272
273 /**
274 * Aliases a contact in the buddy list.
275 *
276 * @param contact The contact whose alias will be changed.
277 * @param alias The contact's alias.
278 */
279 void gaim_blist_alias_contact(GaimContact *contact, const char *alias);
280
281 /**
282 * Aliases a buddy in the buddy list.
283 *
284 * @param buddy The buddy whose alias will be changed.
285 * @param alias The buddy's alias.
286 */
287 void gaim_blist_alias_buddy(GaimBuddy *buddy, const char *alias);
288
289 /**
290 * Sets the server-sent alias of a buddy in the buddy list.
291 *
292 * @param buddy The buddy whose alias will be changed.
293 * @param alias The buddy's "official" alias.
294 */
295 void gaim_blist_server_alias_buddy(GaimBuddy *buddy, const char *alias);
296
297 /**
298 * Aliases a chat in the buddy list.
299 *
300 * @param chat The chat whose alias will be changed.
301 * @param alias The chat's new alias.
302 */
303 void gaim_blist_alias_chat(GaimChat *chat, const char *alias);
304
305 /**
306 * Renames a group
307 *
308 * @param group The group to rename
309 * @param name The new name
310 */
311 void gaim_blist_rename_group(GaimGroup *group, const char *name);
312
313 /**
314 * Creates a new chat for the buddy list
315 *
316 * @param account The account this chat will get added to
317 * @param alias The alias of the new chat
318 * @param components The info the prpl needs to join the chat
319 * @return A newly allocated chat
320 */
321 GaimChat *gaim_chat_new(GaimAccount *account, const char *alias, GHashTable *components);
322
323 /**
324 * Adds a new chat to the buddy list.
325 *
326 * The chat will be inserted right after node or appended to the end
327 * of group if node is NULL. If both are NULL, the buddy will be added to
328 * the "Chats" group.
329 *
330 * @param chat The new chat who gets added
331 * @param group The group to add the new chat to.
332 * @param node The insertion point
333 */
334 void gaim_blist_add_chat(GaimChat *chat, GaimGroup *group, GaimBlistNode *node);
335
336 /**
337 * Creates a new buddy
338 *
339 * @param account The account this buddy will get added to
340 * @param screenname The screenname of the new buddy
341 * @param alias The alias of the new buddy (or NULL if unaliased)
342 * @return A newly allocated buddy
343 */
344 GaimBuddy *gaim_buddy_new(GaimAccount *account, const char *screenname, const char *alias);
345
346 /**
347 * Sets a buddy's icon.
348 *
349 * This should only be called from within Gaim. You probably want to
350 * call gaim_buddy_icon_set_data().
351 *
352 * @param buddy The buddy.
353 * @param icon The buddy icon.
354 *
355 * @see gaim_buddy_icon_set_data()
356 */
357 void gaim_buddy_set_icon(GaimBuddy *buddy, GaimBuddyIcon *icon);
358
359 /**
360 * Returns a buddy's account.
361 *
362 * @param buddy The buddy.
363 *
364 * @return The account
365 */
366 GaimAccount *gaim_buddy_get_account(const GaimBuddy *buddy);
367
368 /**
369 * Returns a buddy's name
370 *
371 * @param buddy The buddy.
372 *
373 * @return The name.
374 */
375 const char *gaim_buddy_get_name(const GaimBuddy *buddy);
376
377 /**
378 * Returns a buddy's icon.
379 *
380 * @param buddy The buddy.
381 *
382 * @return The buddy icon.
383 */
384 GaimBuddyIcon *gaim_buddy_get_icon(const GaimBuddy *buddy);
385
386 /**
387 * Returns a buddy's contact.
388 *
389 * @param buddy The buddy.
390 *
391 * @return The buddy's contact.
392 */
393 GaimContact *gaim_buddy_get_contact(GaimBuddy *buddy);
394
395 /**
396 * Returns a buddy's presence.
397 *
398 * @param buddy The buddy.
399 *
400 * @return The buddy's presence.
401 */
402 GaimPresence *gaim_buddy_get_presence(const GaimBuddy *buddy);
403
404 /**
405 * Adds a new buddy to the buddy list.
406 *
407 * The buddy will be inserted right after node or prepended to the
408 * group if node is NULL. If both are NULL, the buddy will be added to
409 * the "Buddies" group.
410 *
411 * @param buddy The new buddy who gets added
412 * @param contact The optional contact to place the buddy in.
413 * @param group The group to add the new buddy to.
414 * @param node The insertion point
415 */
416 void gaim_blist_add_buddy(GaimBuddy *buddy, GaimContact *contact, GaimGroup *group, GaimBlistNode *node);
417
418 /**
419 * Creates a new group
420 *
421 * You can't have more than one group with the same name. Sorry. If you pass
422 * this the * name of a group that already exists, it will return that group.
423 *
424 * @param name The name of the new group
425 * @return A new group struct
426 */
427 GaimGroup *gaim_group_new(const char *name);
428
429 /**
430 * Adds a new group to the buddy list.
431 *
432 * The new group will be inserted after insert or prepended to the list if
433 * node is NULL.
434 *
435 * @param group The group
436 * @param node The insertion point
437 */
438 void gaim_blist_add_group(GaimGroup *group, GaimBlistNode *node);
439
440 /**
441 * Creates a new contact
442 *
443 * @return A new contact struct
444 */
445 GaimContact *gaim_contact_new(void);
446
447 /**
448 * Adds a new contact to the buddy list.
449 *
450 * The new contact will be inserted after insert or prepended to the list if
451 * node is NULL.
452 *
453 * @param contact The contact
454 * @param group The group to add the contact to
455 * @param node The insertion point
456 */
457 void gaim_blist_add_contact(GaimContact *contact, GaimGroup *group, GaimBlistNode *node);
458
459 /**
460 * Merges two contacts
461 *
462 * All of the buddies from source will be moved to target
463 *
464 * @param source The contact to merge
465 * @param node The place to merge to (a buddy or contact)
466 */
467 void gaim_blist_merge_contact(GaimContact *source, GaimBlistNode *node);
468
469 /**
470 * Returns the highest priority buddy for a given contact.
471 *
472 * @param contact The contact
473 * @return The highest priority buddy
474 */
475 GaimBuddy *gaim_contact_get_priority_buddy(GaimContact *contact);
476
477 /**
478 * Sets the alias for a contact.
479 *
480 * @param contact The contact
481 * @param alias The alias to set, or NULL to unset
482 */
483 void gaim_contact_set_alias(GaimContact *contact, const char *alias);
484
485 /**
486 * Gets the alias for a contact.
487 *
488 * @param contact The contact
489 * @return The alias, or NULL if it is not set.
490 */
491 const char *gaim_contact_get_alias(GaimContact *contact);
492
493 /**
494 * Determines whether an account owns any buddies in a given contact
495 *
496 * @param contact The contact to search through.
497 * @param account The account.
498 *
499 * @return TRUE if there are any buddies from account in the contact, or FALSE otherwise.
500 */
501 gboolean gaim_contact_on_account(GaimContact *contact, GaimAccount *account);
502
503 /**
504 * Invalidates the priority buddy so that the next call to
505 * gaim_contact_get_priority_buddy recomputes it.
506 *
507 * @param contact The contact
508 */
509 void gaim_contact_invalidate_priority_buddy(GaimContact *contact);
510 /**
511 * Removes a buddy from the buddy list and frees the memory allocated to it.
512 *
513 * @param buddy The buddy to be removed
514 */
515 void gaim_blist_remove_buddy(GaimBuddy *buddy);
516
517 /**
518 * Removes a contact, and any buddies it contains, and frees the memory
519 * allocated to it.
520 *
521 * @param contact The contact to be removed
522 */
523 void gaim_blist_remove_contact(GaimContact *contact);
524
525 /**
526 * Removes a chat from the buddy list and frees the memory allocated to it.
527 *
528 * @param chat The chat to be removed
529 */
530 void gaim_blist_remove_chat(GaimChat *chat);
531
532 /**
533 * Removes a group from the buddy list and frees the memory allocated to it and to
534 * its children
535 *
536 * @param group The group to be removed
537 */
538 void gaim_blist_remove_group(GaimGroup *group);
539
540 /**
541 * Returns the alias of a buddy.
542 *
543 * @param buddy The buddy whose name will be returned.
544 * @return The alias (if set), server alias (if set),
545 * or NULL.
546 */
547 const char *gaim_buddy_get_alias_only(GaimBuddy *buddy);
548
549
550 /**
551 * Returns the correct name to display for a buddy, taking the contact alias
552 * into account. In order of precedence: the buddy's alias; the buddy's
553 * contact alias; the buddy's server alias; the buddy's user name.
554 *
555 * @param buddy The buddy whose name will be returned
556 * @return The appropriate name or alias, or NULL.
557 *
558 */
559 const char *gaim_buddy_get_contact_alias(GaimBuddy *buddy);
560
561 /**
562 * Returns the correct alias for this user, ignoring server aliases. Used
563 * when a user-recognizable name is required. In order: buddy's alias; buddy's
564 * contact alias; buddy's user name.
565 *
566 * @param buddy The buddy whose alias will be returned.
567 * @return The appropriate name or alias.
568 */
569 const char *gaim_buddy_get_local_alias(GaimBuddy *buddy);
570
571 /**
572 * Returns the correct name to display for a buddy. In order of precedence:
573 * the buddy's alias; the buddy's server alias; the buddy's contact alias;
574 * the buddy's user name.
575 *
576 * @param buddy The buddy whose name will be returned.
577 * @return The appropriate name or alias, or NULL
578 */
579 const char *gaim_buddy_get_alias(GaimBuddy *buddy);
580
581 /**
582 * Returns the correct name to display for a blist chat.
583 *
584 * @param chat The chat whose name will be returned.
585 * @return The alias (if set), or first component value.
586 */
587 const char *gaim_chat_get_name(GaimChat *chat);
588
589 /**
590 * Finds the buddy struct given a screenname and an account
591 *
592 * @param account The account this buddy belongs to
593 * @param name The buddy's screenname
594 * @return The buddy or NULL if the buddy does not exist
595 */
596 GaimBuddy *gaim_find_buddy(GaimAccount *account, const char *name);
597
598 /**
599 * Finds the buddy struct given a screenname, an account, and a group
600 *
601 * @param account The account this buddy belongs to
602 * @param name The buddy's screenname
603 * @param group The group to look in
604 * @return The buddy or NULL if the buddy does not exist in the group
605 */
606 GaimBuddy *gaim_find_buddy_in_group(GaimAccount *account, const char *name,
607 GaimGroup *group);
608
609 /**
610 * Finds all GaimBuddy structs given a screenname and an account
611 *
612 * @param account The account this buddy belongs to
613 * @param name The buddy's screenname
614 *
615 * @return A GSList of buddies (which must be freed), or NULL if the buddy doesn't exist
616 */
617 GSList *gaim_find_buddies(GaimAccount *account, const char *name);
618
619
620 /**
621 * Finds a group by name
622 *
623 * @param name The groups name
624 * @return The group or NULL if the group does not exist
625 */
626 GaimGroup *gaim_find_group(const char *name);
627
628 /**
629 * Finds a chat by name.
630 *
631 * @param account The chat's account.
632 * @param name The chat's name.
633 *
634 * @return The chat, or @c NULL if the chat does not exist.
635 */
636 GaimChat *gaim_blist_find_chat(GaimAccount *account, const char *name);
637
638 /**
639 * Returns the group of which the chat is a member.
640 *
641 * @param chat The chat.
642 *
643 * @return The parent group, or @c NULL if the chat is not in a group.
644 */
645 GaimGroup *gaim_chat_get_group(GaimChat *chat);
646
647 /**
648 * Returns the group of which the buddy is a member.
649 *
650 * @param buddy The buddy
651 * @return The group or NULL if the buddy is not in a group
652 */
653 GaimGroup *gaim_buddy_get_group(GaimBuddy *buddy);
654
655
656 /**
657 * Returns a list of accounts that have buddies in this group
658 *
659 * @param g The group
660 *
661 * @return A list of gaim_accounts
662 */
663 GSList *gaim_group_get_accounts(GaimGroup *g);
664
665 /**
666 * Determines whether an account owns any buddies in a given group
667 *
668 * @param g The group to search through.
669 * @param account The account.
670 *
671 * @return TRUE if there are any buddies in the group, or FALSE otherwise.
672 */
673 gboolean gaim_group_on_account(GaimGroup *g, GaimAccount *account);
674
675 /**
676 * Called when an account gets signed on. Tells the UI to update all the
677 * buddies.
678 *
679 * @param account The account
680 */
681 void gaim_blist_add_account(GaimAccount *account);
682
683
684 /**
685 * Called when an account gets signed off. Sets the presence of all the buddies to 0
686 * and tells the UI to update them.
687 *
688 * @param account The account
689 */
690 void gaim_blist_remove_account(GaimAccount *account);
691
692
693 /**
694 * Determines the total size of a group
695 *
696 * @param group The group
697 * @param offline Count buddies in offline accounts
698 * @return The number of buddies in the group
699 */
700 int gaim_blist_get_group_size(GaimGroup *group, gboolean offline);
701
702 /**
703 * Determines the number of online buddies in a group
704 *
705 * @param group The group
706 * @return The number of online buddies in the group, or 0 if the group is NULL
707 */
708 int gaim_blist_get_group_online_count(GaimGroup *group);
709
710 /*@}*/
711
712 /****************************************************************************************/
713 /** @name Buddy list file management API */
714 /****************************************************************************************/
715
716 /**
717 * Loads the buddy list from ~/.gaim/blist.xml.
718 */
719 void gaim_blist_load(void);
720
721 /**
722 * Schedule a save of the blist.xml file. This is used by the privacy
723 * API whenever the privacy settings are changed. If you make a change
724 * to blist.xml using one of the functions in the buddy list API, then
725 * the buddy list is saved automatically, so you should not need to
726 * call this.
727 */
728 void gaim_blist_schedule_save(void);
729
730 /**
731 * Requests from the user information needed to add a buddy to the
732 * buddy list.
733 *
734 * @param account The account the buddy is added to.
735 * @param username The username of the buddy.
736 * @param group The name of the group to place the buddy in.
737 * @param alias The optional alias for the buddy.
738 */
739 void gaim_blist_request_add_buddy(GaimAccount *account, const char *username,
740 const char *group, const char *alias);
741
742 /**
743 * Requests from the user information needed to add a chat to the
744 * buddy list.
745 *
746 * @param account The account the buddy is added to.
747 * @param group The optional group to add the chat to.
748 * @param alias The optional alias for the chat.
749 * @param name The required chat name.
750 */
751 void gaim_blist_request_add_chat(GaimAccount *account, GaimGroup *group,
752 const char *alias, const char *name);
753
754 /**
755 * Requests from the user information needed to add a group to the
756 * buddy list.
757 */
758 void gaim_blist_request_add_group(void);
759
760 /**
761 * Associates a boolean with a node in the buddy list
762 *
763 * @param node The node to associate the data with
764 * @param key The identifier for the data
765 * @param value The value to set
766 */
767 void gaim_blist_node_set_bool(GaimBlistNode *node, const char *key, gboolean value);
768
769 /**
770 * Retrieves a named boolean setting from a node in the buddy list
771 *
772 * @param node The node to retrieve the data from
773 * @param key The identifier of the data
774 *
775 * @return The value, or FALSE if there is no setting
776 */
777 gboolean gaim_blist_node_get_bool(GaimBlistNode *node, const char *key);
778
779 /**
780 * Associates an integer with a node in the buddy list
781 *
782 * @param node The node to associate the data with
783 * @param key The identifier for the data
784 * @param value The value to set
785 */
786 void gaim_blist_node_set_int(GaimBlistNode *node, const char *key, int value);
787
788 /**
789 * Retrieves a named integer setting from a node in the buddy list
790 *
791 * @param node The node to retrieve the data from
792 * @param key The identifier of the data
793 *
794 * @return The value, or 0 if there is no setting
795 */
796 int gaim_blist_node_get_int(GaimBlistNode *node, const char *key);
797
798 /**
799 * Associates a string with a node in the buddy list
800 *
801 * @param node The node to associate the data with
802 * @param key The identifier for the data
803 * @param value The value to set
804 */
805 void gaim_blist_node_set_string(GaimBlistNode *node, const char *key,
806 const char *value);
807
808 /**
809 * Retrieves a named string setting from a node in the buddy list
810 *
811 * @param node The node to retrieve the data from
812 * @param key The identifier of the data
813 *
814 * @return The value, or NULL if there is no setting
815 */
816 const char *gaim_blist_node_get_string(GaimBlistNode *node, const char *key);
817
818 /**
819 * Removes a named setting from a blist node
820 *
821 * @param node The node from which to remove the setting
822 * @param key The name of the setting
823 */
824 void gaim_blist_node_remove_setting(GaimBlistNode *node, const char *key);
825
826 /**
827 * Set the flags for the given node. Setting a node's flags will overwrite
828 * the old flags, so if you want to save them, you must first call
829 * gaim_blist_node_get_flags and modify that appropriately.
830 *
831 * @param node The node on which to set the flags.
832 * @param flags The flags to set. This is a bitmask.
833 */
834 void gaim_blist_node_set_flags(GaimBlistNode *node, GaimBlistNodeFlags flags);
835
836 /**
837 * Get the current flags on a given node.
838 *
839 * @param node The node from which to get the flags.
840 *
841 * @return The flags on the node. This is a bitmask.
842 */
843 GaimBlistNodeFlags gaim_blist_node_get_flags(GaimBlistNode *node);
844
845 /*@}*/
846
847 /**
848 * Retrieves the extended menu items for a buddy list node.
849 * @param n The blist node for which to obtain the extended menu items.
850 * @return A list of GaimMenuAction items, as harvested by the
851 * blist-node-extended-menu signal.
852 */
853 GList *gaim_blist_node_get_extended_menu(GaimBlistNode *n);
854
855 /**************************************************************************/
856 /** @name UI Registration Functions */
857 /**************************************************************************/
858 /*@{*/
859
860 /**
861 * Sets the UI operations structure to be used for the buddy list.
862 *
863 * @param ops The ops struct.
864 */
865 void gaim_blist_set_ui_ops(GaimBlistUiOps *ops);
866
867 /**
868 * Returns the UI operations structure to be used for the buddy list.
869 *
870 * @return The UI operations structure.
871 */
872 GaimBlistUiOps *gaim_blist_get_ui_ops(void);
873
874 /*@}*/
875
876 /**************************************************************************/
877 /** @name Buddy List Subsystem */
878 /**************************************************************************/
879 /*@{*/
880
881 /**
882 * Returns the handle for the buddy list subsystem.
883 *
884 * @return The buddy list subsystem handle.
885 */
886 void *gaim_blist_get_handle(void);
887
888 /**
889 * Initializes the buddy list subsystem.
890 */
891 void gaim_blist_init(void);
892
893 /**
894 * Uninitializes the buddy list subsystem.
895 */
896 void gaim_blist_uninit(void);
897
898 /*@}*/
899
900 #ifdef __cplusplus
901 }
902 #endif
903
904 #endif /* _GAIM_BLIST_H_ */

Mercurial Repository: pidgin3

mercurial