Mercurial > pidgin
comparison libpurple/blist.h @ 26689:8a77e6cd7eac
merge of 'ac3524a1092f2874db1b7f443cd91144bbd8a3a4'
and 'bcb04d16f3ca4e36afd84bde4ebe44396dc6c2b3'
author | Paul Aurich <paul@darkrain42.org> |
---|---|
date | Sun, 26 Apr 2009 02:18:03 +0000 |
parents | 872d30754311 |
children | 9331016df8ac |
comparison
equal
deleted
inserted
replaced
26654:4a3a0c47dfe1 | 26689:8a77e6cd7eac |
---|---|
116 | 116 |
117 #if !(defined PURPLE_HIDE_STRUCTS) || (defined _PURPLE_BLIST_C_) | 117 #if !(defined PURPLE_HIDE_STRUCTS) || (defined _PURPLE_BLIST_C_) |
118 | 118 |
119 /** | 119 /** |
120 * A Buddy list node. This can represent a group, a buddy, or anything else. | 120 * A Buddy list node. This can represent a group, a buddy, or anything else. |
121 * This is a base class for struct buddy and struct group and for anything | 121 * This is a base class for PurpleBuddy, PurpleContact, PurpleGroup, and for |
122 * else that wants to put itself in the buddy list. */ | 122 * anything else that wants to put itself in the buddy list. */ |
123 struct _PurpleBlistNode { | 123 struct _PurpleBlistNode { |
124 PurpleBlistNodeType type; /**< The type of node this is */ | 124 PurpleBlistNodeType type; /**< The type of node this is */ |
125 PurpleBlistNode *prev; /**< The sibling before this buddy. */ | 125 PurpleBlistNode *prev; /**< The sibling before this buddy. */ |
126 PurpleBlistNode *next; /**< The sibling after this buddy. */ | 126 PurpleBlistNode *next; /**< The sibling after this buddy. */ |
127 PurpleBlistNode *parent; /**< The parent of this node */ | 127 PurpleBlistNode *parent; /**< The parent of this node */ |
205 void (*show)(PurpleBuddyList *list); /**< The core will call this when it's finished doing its core stuff */ | 205 void (*show)(PurpleBuddyList *list); /**< The core will call this when it's finished doing its core stuff */ |
206 void (*update)(PurpleBuddyList *list, | 206 void (*update)(PurpleBuddyList *list, |
207 PurpleBlistNode *node); /**< This will update a node in the buddy list. */ | 207 PurpleBlistNode *node); /**< This will update a node in the buddy list. */ |
208 void (*remove)(PurpleBuddyList *list, | 208 void (*remove)(PurpleBuddyList *list, |
209 PurpleBlistNode *node); /**< This removes a node from the list */ | 209 PurpleBlistNode *node); /**< This removes a node from the list */ |
210 void (*destroy)(PurpleBuddyList *list); /**< When the list gets destroyed, this gets called to destroy the UI. */ | 210 void (*destroy)(PurpleBuddyList *list); /**< When the list is destroyed, this is called to destroy the UI. */ |
211 void (*set_visible)(PurpleBuddyList *list, | 211 void (*set_visible)(PurpleBuddyList *list, |
212 gboolean show); /**< Hides or unhides the buddy list */ | 212 gboolean show); /**< Hides or unhides the buddy list */ |
213 void (*request_add_buddy)(PurpleAccount *account, const char *username, | 213 void (*request_add_buddy)(PurpleAccount *account, const char *username, |
214 const char *group, const char *alias); | 214 const char *group, const char *alias); |
215 void (*request_add_chat)(PurpleAccount *account, PurpleGroup *group, | 215 void (*request_add_chat)(PurpleAccount *account, PurpleGroup *group, |
274 * | 274 * |
275 * @return The UI data for the list. | 275 * @return The UI data for the list. |
276 * | 276 * |
277 * @since 2.6.0 | 277 * @since 2.6.0 |
278 */ | 278 */ |
279 void *purple_blist_get_ui_data(void); | 279 gpointer purple_blist_get_ui_data(void); |
280 | 280 |
281 /** | 281 /** |
282 * Sets the UI data for the list. | 282 * Sets the UI data for the list. |
283 * | 283 * |
284 * @param ui_data The UI data for the list. | 284 * @param ui_data The UI data for the list. |
285 * | 285 * |
286 * @since 2.6.0 | 286 * @since 2.6.0 |
287 */ | 287 */ |
288 void purple_blist_set_ui_data(void *ui_data); | 288 void purple_blist_set_ui_data(gpointer ui_data); |
289 | 289 |
290 /** | 290 /** |
291 * Returns the next node of a given node. This function is to be used to iterate | 291 * Returns the next node of a given node. This function is to be used to iterate |
292 * over the tree returned by purple_get_blist. | 292 * over the tree returned by purple_get_blist. |
293 * | 293 * |
358 * | 358 * |
359 * @param node The node. | 359 * @param node The node. |
360 * @return The UI data. | 360 * @return The UI data. |
361 * @since 2.6.0 | 361 * @since 2.6.0 |
362 */ | 362 */ |
363 void *purple_blist_node_get_ui_data(const PurpleBlistNode *node); | 363 gpointer purple_blist_node_get_ui_data(const PurpleBlistNode *node); |
364 | 364 |
365 /** | 365 /** |
366 * Sets the UI data of a given node. | 366 * Sets the UI data of a given node. |
367 * | 367 * |
368 * @param node The node. | 368 * @param node The node. |
369 * @param ui_data The UI data. | 369 * @param ui_data The UI data. |
370 * | 370 * |
371 * @since 2.6.0 | 371 * @since 2.6.0 |
372 */ | 372 */ |
373 void purple_blist_node_set_ui_data(PurpleBlistNode *node, void *ui_data); | 373 void purple_blist_node_set_ui_data(PurpleBlistNode *node, gpointer ui_data); |
374 | 374 |
375 /** | 375 /** |
376 * Shows the buddy list, creating a new one if necessary. | 376 * Shows the buddy list, creating a new one if necessary. |
377 */ | 377 */ |
378 void purple_blist_show(void); | 378 void purple_blist_show(void); |
390 */ | 390 */ |
391 void purple_blist_set_visible(gboolean show); | 391 void purple_blist_set_visible(gboolean show); |
392 | 392 |
393 /** | 393 /** |
394 * Updates a buddy's status. | 394 * Updates a buddy's status. |
395 * | |
396 * This should only be called from within Purple. | |
395 * | 397 * |
396 * @param buddy The buddy whose status has changed. | 398 * @param buddy The buddy whose status has changed. |
397 * @param old_status The status from which we are changing. | 399 * @param old_status The status from which we are changing. |
398 */ | 400 */ |
399 void purple_blist_update_buddy_status(PurpleBuddy *buddy, PurpleStatus *old_status); | 401 void purple_blist_update_buddy_status(PurpleBuddy *buddy, PurpleStatus *old_status); |
497 * @param node The insertion point | 499 * @param node The insertion point |
498 */ | 500 */ |
499 void purple_blist_add_chat(PurpleChat *chat, PurpleGroup *group, PurpleBlistNode *node); | 501 void purple_blist_add_chat(PurpleChat *chat, PurpleGroup *group, PurpleBlistNode *node); |
500 | 502 |
501 /** | 503 /** |
502 * Creates a new buddy | 504 * Creates a new buddy. |
505 * | |
506 * This function only creates the PurpleBuddy. Use purple_blist_add_buddy | |
507 * to add the buddy to the list and purple_account_add_buddy to sync up | |
508 * with the server. | |
503 * | 509 * |
504 * @param account The account this buddy will get added to | 510 * @param account The account this buddy will get added to |
505 * @param name The name of the new buddy | 511 * @param name The name of the new buddy |
506 * @param alias The alias of the new buddy (or NULL if unaliased) | 512 * @param alias The alias of the new buddy (or NULL if unaliased) |
507 * @return A newly allocated buddy | 513 * @return A newly allocated buddy |
514 * | |
515 * @see purple_account_add_buddy | |
516 * @see purple_blist_add_buddy | |
508 */ | 517 */ |
509 PurpleBuddy *purple_buddy_new(PurpleAccount *account, const char *name, const char *alias); | 518 PurpleBuddy *purple_buddy_new(PurpleAccount *account, const char *name, const char *alias); |
510 | 519 |
511 /** | 520 /** |
512 * Destroys a buddy | 521 * Destroys a buddy |
616 | 625 |
617 /** | 626 /** |
618 * Creates a new group | 627 * Creates a new group |
619 * | 628 * |
620 * You can't have more than one group with the same name. Sorry. If you pass | 629 * You can't have more than one group with the same name. Sorry. If you pass |
621 * this the * name of a group that already exists, it will return that group. | 630 * this the name of a group that already exists, it will return that group. |
622 * | 631 * |
623 * @param name The name of the new group | 632 * @param name The name of the new group |
624 * @return A new group struct | 633 * @return A new group struct |
625 */ | 634 */ |
626 PurpleGroup *purple_group_new(const char *name); | 635 PurpleGroup *purple_group_new(const char *name); |
725 */ | 734 */ |
726 void purple_contact_invalidate_priority_buddy(PurpleContact *contact); | 735 void purple_contact_invalidate_priority_buddy(PurpleContact *contact); |
727 | 736 |
728 /** | 737 /** |
729 * Removes a buddy from the buddy list and frees the memory allocated to it. | 738 * Removes a buddy from the buddy list and frees the memory allocated to it. |
730 * This doesn't actually try to remove the buddy from the server list, nor does | 739 * This doesn't actually try to remove the buddy from the server list. |
731 * it clean up the prpl_data. | |
732 * | 740 * |
733 * @param buddy The buddy to be removed | 741 * @param buddy The buddy to be removed |
742 * | |
743 * @see purple_account_remove_buddy | |
734 */ | 744 */ |
735 void purple_blist_remove_buddy(PurpleBuddy *buddy); | 745 void purple_blist_remove_buddy(PurpleBuddy *buddy); |
736 | 746 |
737 /** | 747 /** |
738 * Removes a contact, and any buddies it contains, and frees the memory | 748 * Removes a contact, and any buddies it contains, and frees the memory |
739 * allocated to it. | 749 * allocated to it. This calls purple_blist_remove_buddy and therefore |
750 * doesn't remove the buddies from the server list. | |
740 * | 751 * |
741 * @param contact The contact to be removed | 752 * @param contact The contact to be removed |
753 * | |
754 * @see purple_blist_remove_buddy | |
742 */ | 755 */ |
743 void purple_blist_remove_contact(PurpleContact *contact); | 756 void purple_blist_remove_contact(PurpleContact *contact); |
744 | 757 |
745 /** | 758 /** |
746 * Removes a chat from the buddy list and frees the memory allocated to it. | 759 * Removes a chat from the buddy list and frees the memory allocated to it. |
848 | 861 |
849 /** | 862 /** |
850 * Finds all PurpleBuddy structs given a name and an account | 863 * Finds all PurpleBuddy structs given a name and an account |
851 * | 864 * |
852 * @param account The account this buddy belongs to | 865 * @param account The account this buddy belongs to |
853 * @param name The buddy's name (or NULL to return all buddies in the account) | 866 * @param name The buddy's name (or NULL to return all buddies for the account) |
854 * | 867 * |
855 * @return A GSList of buddies (which must be freed), or NULL if the buddy doesn't exist | 868 * @return A GSList of buddies (which must be freed), or NULL if the buddy doesn't exist |
856 */ | 869 */ |
857 GSList *purple_find_buddies(PurpleAccount *account, const char *name); | 870 GSList *purple_find_buddies(PurpleAccount *account, const char *name); |
858 | 871 |
943 * @return The name of the group. | 956 * @return The name of the group. |
944 */ | 957 */ |
945 const char *purple_group_get_name(PurpleGroup *group); | 958 const char *purple_group_get_name(PurpleGroup *group); |
946 | 959 |
947 /** | 960 /** |
948 * Called when an account gets signed on. Tells the UI to update all the | 961 * Called when an account connects. Tells the UI to update all the |
949 * buddies. | 962 * buddies. |
950 * | 963 * |
951 * @param account The account | 964 * @param account The account |
952 */ | 965 */ |
953 void purple_blist_add_account(PurpleAccount *account); | 966 void purple_blist_add_account(PurpleAccount *account); |
954 | 967 |
955 | 968 |
956 /** | 969 /** |
957 * Called when an account gets signed off. Sets the presence of all the buddies to 0 | 970 * Called when an account disconnects. Sets the presence of all the buddies to 0 |
958 * and tells the UI to update them. | 971 * and tells the UI to update them. |
959 * | 972 * |
960 * @param account The account | 973 * @param account The account |
961 */ | 974 */ |
962 void purple_blist_remove_account(PurpleAccount *account); | 975 void purple_blist_remove_account(PurpleAccount *account); |