diff options
Diffstat (limited to 'libpurple/blist.h')
| -rw-r--r-- | libpurple/blist.h | 43 |
1 files changed, 28 insertions, 15 deletions
diff --git a/libpurple/blist.h b/libpurple/blist.h index d425d94f29..895cc65d10 100644 --- a/libpurple/blist.h +++ b/libpurple/blist.h @@ -118,8 +118,8 @@ typedef enum /** * A Buddy list node. This can represent a group, a buddy, or anything else. - * This is a base class for struct buddy and struct group and for anything - * else that wants to put itself in the buddy list. */ + * This is a base class for PurpleBuddy, PurpleContact, PurpleGroup, and for + * anything else that wants to put itself in the buddy list. */ struct _PurpleBlistNode { PurpleBlistNodeType type; /**< The type of node this is */ PurpleBlistNode *prev; /**< The sibling before this buddy. */ @@ -207,7 +207,7 @@ struct _PurpleBlistUiOps PurpleBlistNode *node); /**< This will update a node in the buddy list. */ void (*remove)(PurpleBuddyList *list, PurpleBlistNode *node); /**< This removes a node from the list */ - void (*destroy)(PurpleBuddyList *list); /**< When the list gets destroyed, this gets called to destroy the UI. */ + void (*destroy)(PurpleBuddyList *list); /**< When the list is destroyed, this is called to destroy the UI. */ void (*set_visible)(PurpleBuddyList *list, gboolean show); /**< Hides or unhides the buddy list */ void (*request_add_buddy)(PurpleAccount *account, const char *username, @@ -276,7 +276,7 @@ GSList *purple_blist_get_buddies(void); * * @since 2.6.0 */ -void *purple_blist_get_ui_data(void); +gpointer purple_blist_get_ui_data(void); /** * Sets the UI data for the list. @@ -285,7 +285,7 @@ void *purple_blist_get_ui_data(void); * * @since 2.6.0 */ -void purple_blist_set_ui_data(void *ui_data); +void purple_blist_set_ui_data(gpointer ui_data); /** * Returns the next node of a given node. This function is to be used to iterate @@ -360,7 +360,7 @@ PurpleBlistNode *purple_blist_node_get_sibling_prev(PurpleBlistNode *node); * @return The UI data. * @since 2.6.0 */ -void *purple_blist_node_get_ui_data(const PurpleBlistNode *node); +gpointer purple_blist_node_get_ui_data(const PurpleBlistNode *node); /** * Sets the UI data of a given node. @@ -370,7 +370,7 @@ void *purple_blist_node_get_ui_data(const PurpleBlistNode *node); * * @since 2.6.0 */ -void purple_blist_node_set_ui_data(PurpleBlistNode *node, void *ui_data); +void purple_blist_node_set_ui_data(PurpleBlistNode *node, gpointer ui_data); /** * Shows the buddy list, creating a new one if necessary. @@ -393,6 +393,8 @@ void purple_blist_set_visible(gboolean show); /** * Updates a buddy's status. * + * This should only be called from within Purple. + * * @param buddy The buddy whose status has changed. * @param old_status The status from which we are changing. */ @@ -499,12 +501,19 @@ void purple_chat_destroy(PurpleChat *chat); void purple_blist_add_chat(PurpleChat *chat, PurpleGroup *group, PurpleBlistNode *node); /** - * Creates a new buddy + * Creates a new buddy. + * + * This function only creates the PurpleBuddy. Use purple_blist_add_buddy + * to add the buddy to the list and purple_account_add_buddy to sync up + * with the server. * * @param account The account this buddy will get added to * @param name The name of the new buddy * @param alias The alias of the new buddy (or NULL if unaliased) * @return A newly allocated buddy + * + * @see purple_account_add_buddy + * @see purple_blist_add_buddy */ PurpleBuddy *purple_buddy_new(PurpleAccount *account, const char *name, const char *alias); @@ -618,7 +627,7 @@ void purple_blist_add_buddy(PurpleBuddy *buddy, PurpleContact *contact, PurpleGr * Creates a new group * * You can't have more than one group with the same name. Sorry. If you pass - * this the * name of a group that already exists, it will return that group. + * this the name of a group that already exists, it will return that group. * * @param name The name of the new group * @return A new group struct @@ -727,18 +736,22 @@ void purple_contact_invalidate_priority_buddy(PurpleContact *contact); /** * Removes a buddy from the buddy list and frees the memory allocated to it. - * This doesn't actually try to remove the buddy from the server list, nor does - * it clean up the prpl_data. + * This doesn't actually try to remove the buddy from the server list. * * @param buddy The buddy to be removed + * + * @see purple_account_remove_buddy */ void purple_blist_remove_buddy(PurpleBuddy *buddy); /** * Removes a contact, and any buddies it contains, and frees the memory - * allocated to it. + * allocated to it. This calls purple_blist_remove_buddy and therefore + * doesn't remove the buddies from the server list. * * @param contact The contact to be removed + * + * @see purple_blist_remove_buddy */ void purple_blist_remove_contact(PurpleContact *contact); @@ -850,7 +863,7 @@ PurpleBuddy *purple_find_buddy_in_group(PurpleAccount *account, const char *name * Finds all PurpleBuddy structs given a name and an account * * @param account The account this buddy belongs to - * @param name The buddy's name (or NULL to return all buddies in the account) + * @param name The buddy's name (or NULL to return all buddies for the account) * * @return A GSList of buddies (which must be freed), or NULL if the buddy doesn't exist */ @@ -945,7 +958,7 @@ gboolean purple_group_on_account(PurpleGroup *g, PurpleAccount *account); const char *purple_group_get_name(PurpleGroup *group); /** - * Called when an account gets signed on. Tells the UI to update all the + * Called when an account connects. Tells the UI to update all the * buddies. * * @param account The account @@ -954,7 +967,7 @@ void purple_blist_add_account(PurpleAccount *account); /** - * Called when an account gets signed off. Sets the presence of all the buddies to 0 + * Called when an account disconnects. Sets the presence of all the buddies to 0 * and tells the UI to update them. * * @param account The account |