Buddy List API. More...

#include <glib.h>
#include "account.h"
#include "buddyicon.h"
#include "media.h"
#include "status.h"
Include dependency graph for blist.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  _PurpleBlistNode
 A Buddy list node. More...
struct  _PurpleBuddy
 A buddy. More...
struct  _PurpleContact
 A contact. More...
struct  _PurpleGroup
 A group. More...
struct  _PurpleChat
 A chat. More...
struct  _PurpleBuddyList
 The Buddy List. More...
struct  _PurpleBlistUiOps
 Buddy list UI operations. More...

Macros

#define PURPLE_BLIST_NODE_IS_CHAT(n)   (purple_blist_node_get_type(n) == PURPLE_BLIST_CHAT_NODE)
#define PURPLE_BLIST_NODE_IS_BUDDY(n)   (purple_blist_node_get_type(n) == PURPLE_BLIST_BUDDY_NODE)
#define PURPLE_BLIST_NODE_IS_CONTACT(n)   (purple_blist_node_get_type(n) == PURPLE_BLIST_CONTACT_NODE)
#define PURPLE_BLIST_NODE_IS_GROUP(n)   (purple_blist_node_get_type(n) == PURPLE_BLIST_GROUP_NODE)
#define PURPLE_BUDDY_IS_ONLINE(b)
#define PURPLE_BLIST_NODE(obj)   ((PurpleBlistNode *)(obj))
#define PURPLE_BLIST_NODE_HAS_FLAG(b, f)   (purple_blist_node_get_flags((PurpleBlistNode*)(b)) & (f))
#define PURPLE_BLIST_NODE_SHOULD_SAVE(b)   (! PURPLE_BLIST_NODE_HAS_FLAG(b, PURPLE_BLIST_NODE_FLAG_NO_SAVE))
#define PURPLE_BLIST_NODE_NAME(n)
#define PURPLE_GROUP(obj)   ((PurpleGroup *)(obj))
#define PURPLE_CONTACT(obj)   ((PurpleContact *)(obj))
#define PURPLE_BUDDY(obj)   ((PurpleBuddy *)(obj))
#define PURPLE_CHAT(obj)   ((PurpleChat *)(obj))

Typedefs

typedef struct _PurpleBuddyList PurpleBuddyList
 The Buddy List.
typedef struct _PurpleBlistUiOps PurpleBlistUiOps
 Buddy list UI operations.
typedef struct _PurpleBlistNode PurpleBlistNode
 A Buddy list node.
typedef struct _PurpleChat PurpleChat
 A chat.
typedef struct _PurpleGroup PurpleGroup
 A group.
typedef struct _PurpleContact PurpleContact
 A contact.
typedef struct _PurpleBuddy PurpleBuddy
 A buddy.

Enumerations

enum  PurpleBlistNodeType {
  PURPLE_BLIST_GROUP_NODE, PURPLE_BLIST_CONTACT_NODE, PURPLE_BLIST_BUDDY_NODE, PURPLE_BLIST_CHAT_NODE,
  PURPLE_BLIST_OTHER_NODE
}
enum  PurpleBlistNodeFlags { PURPLE_BLIST_NODE_FLAG_NO_SAVE = 1 << 0 }

Functions

GList * purple_blist_node_get_extended_menu (PurpleBlistNode *n)
 Retrieves the extended menu items for a buddy list node.
Buddy List API
PurpleBuddyListpurple_blist_new (void)
 Creates a new buddy list.
void purple_set_blist (PurpleBuddyList *blist)
 Sets the main buddy list.
PurpleBuddyListpurple_get_blist (void)
 Returns the main buddy list.
PurpleBlistNodepurple_blist_get_root (void)
 Returns the root node of the main buddy list.
GSList * purple_blist_get_buddies (void)
 Returns a list of every buddy in the list.
gpointer purple_blist_get_ui_data (void)
 Returns the UI data for the list.
void purple_blist_set_ui_data (gpointer ui_data)
 Sets the UI data for the list.
PurpleBlistNodepurple_blist_node_next (PurpleBlistNode *node, gboolean offline)
 Returns the next node of a given node.
PurpleBlistNodepurple_blist_node_get_parent (PurpleBlistNode *node)
 Returns the parent node of a given node.
PurpleBlistNodepurple_blist_node_get_first_child (PurpleBlistNode *node)
 Returns the the first child node of a given node.
PurpleBlistNodepurple_blist_node_get_sibling_next (PurpleBlistNode *node)
 Returns the sibling node of a given node.
PurpleBlistNodepurple_blist_node_get_sibling_prev (PurpleBlistNode *node)
 Returns the previous sibling node of a given node.
gpointer purple_blist_node_get_ui_data (const PurpleBlistNode *node)
 Returns the UI data of a given node.
void purple_blist_node_set_ui_data (PurpleBlistNode *node, gpointer ui_data)
 Sets the UI data of a given node.
void purple_blist_show (void)
 Shows the buddy list, creating a new one if necessary.
void purple_blist_destroy (void)
 Destroys the buddy list window.
void purple_blist_set_visible (gboolean show)
 Hides or unhides the buddy list.
void purple_blist_update_buddy_status (PurpleBuddy *buddy, PurpleStatus *old_status)
 Updates a buddy's status.
void purple_blist_update_node_icon (PurpleBlistNode *node)
 Updates a node's custom icon.
void purple_blist_update_buddy_icon (PurpleBuddy *buddy)
 Updates a buddy's icon.
void purple_blist_rename_buddy (PurpleBuddy *buddy, const char *name)
 Renames a buddy in the buddy list.
void purple_blist_alias_contact (PurpleContact *contact, const char *alias)
 Aliases a contact in the buddy list.
void purple_blist_alias_buddy (PurpleBuddy *buddy, const char *alias)
 Aliases a buddy in the buddy list.
void purple_blist_server_alias_buddy (PurpleBuddy *buddy, const char *alias)
 Sets the server-sent alias of a buddy in the buddy list.
void purple_blist_alias_chat (PurpleChat *chat, const char *alias)
 Aliases a chat in the buddy list.
void purple_blist_rename_group (PurpleGroup *group, const char *name)
 Renames a group.
PurpleChatpurple_chat_new (PurpleAccount *account, const char *alias, GHashTable *components)
 Creates a new chat for the buddy list.
void purple_chat_destroy (PurpleChat *chat)
 Destroys a chat.
void purple_blist_add_chat (PurpleChat *chat, PurpleGroup *group, PurpleBlistNode *node)
 Adds a new chat to the buddy list.
PurpleBuddypurple_buddy_new (PurpleAccount *account, const char *name, const char *alias)
 Creates a new buddy.
void purple_buddy_destroy (PurpleBuddy *buddy)
 Destroys a buddy.
void purple_buddy_set_icon (PurpleBuddy *buddy, PurpleBuddyIcon *icon)
 Sets a buddy's icon.
PurpleAccountpurple_buddy_get_account (const PurpleBuddy *buddy)
 Returns a buddy's account.
const char * purple_buddy_get_name (const PurpleBuddy *buddy)
 Returns a buddy's name.
PurpleBuddyIconpurple_buddy_get_icon (const PurpleBuddy *buddy)
 Returns a buddy's icon.
gpointer purple_buddy_get_protocol_data (const PurpleBuddy *buddy)
 Returns a buddy's protocol-specific data.
void purple_buddy_set_protocol_data (PurpleBuddy *buddy, gpointer data)
 Sets a buddy's protocol-specific data.
PurpleContactpurple_buddy_get_contact (PurpleBuddy *buddy)
 Returns a buddy's contact.
PurplePresence * purple_buddy_get_presence (const PurpleBuddy *buddy)
 Returns a buddy's presence.
PurpleMediaCaps purple_buddy_get_media_caps (const PurpleBuddy *buddy)
 Gets the media caps from a buddy.
void purple_buddy_set_media_caps (PurpleBuddy *buddy, PurpleMediaCaps media_caps)
 Sets the media caps for a buddy.
void purple_blist_add_buddy (PurpleBuddy *buddy, PurpleContact *contact, PurpleGroup *group, PurpleBlistNode *node)
 Adds a new buddy to the buddy list.
PurpleGrouppurple_group_new (const char *name)
 Creates a new group.
void purple_group_destroy (PurpleGroup *group)
 Destroys a group.
void purple_blist_add_group (PurpleGroup *group, PurpleBlistNode *node)
 Adds a new group to the buddy list.
PurpleContactpurple_contact_new (void)
 Creates a new contact.
void purple_contact_destroy (PurpleContact *contact)
 Destroys a contact.
PurpleGrouppurple_contact_get_group (const PurpleContact *contact)
 Gets the PurpleGroup from a PurpleContact.
void purple_blist_add_contact (PurpleContact *contact, PurpleGroup *group, PurpleBlistNode *node)
 Adds a new contact to the buddy list.
void purple_blist_merge_contact (PurpleContact *source, PurpleBlistNode *node)
 Merges two contacts.
PurpleBuddypurple_contact_get_priority_buddy (PurpleContact *contact)
 Returns the highest priority buddy for a given contact.
void purple_contact_set_alias (PurpleContact *contact, const char *alias)
 Sets the alias for a contact.
const char * purple_contact_get_alias (PurpleContact *contact)
 Gets the alias for a contact.
gboolean purple_contact_on_account (PurpleContact *contact, PurpleAccount *account)
 Determines whether an account owns any buddies in a given contact.
void purple_contact_invalidate_priority_buddy (PurpleContact *contact)
 Invalidates the priority buddy so that the next call to purple_contact_get_priority_buddy recomputes it.
void purple_blist_remove_buddy (PurpleBuddy *buddy)
 Removes a buddy from the buddy list and frees the memory allocated to it.
void purple_blist_remove_contact (PurpleContact *contact)
 Removes a contact, and any buddies it contains, and frees the memory allocated to it.
void purple_blist_remove_chat (PurpleChat *chat)
 Removes a chat from the buddy list and frees the memory allocated to it.
void purple_blist_remove_group (PurpleGroup *group)
 Removes a group from the buddy list and frees the memory allocated to it and to its children.
const char * purple_buddy_get_alias_only (PurpleBuddy *buddy)
 Returns the alias of a buddy.
const char * purple_buddy_get_server_alias (PurpleBuddy *buddy)
 Gets the server alias for a buddy.
const char * purple_buddy_get_contact_alias (PurpleBuddy *buddy)
 Returns the correct name to display for a buddy, taking the contact alias into account.
const char * purple_buddy_get_local_alias (PurpleBuddy *buddy)
 Returns the correct alias for this user, ignoring server aliases.
const char * purple_buddy_get_alias (PurpleBuddy *buddy)
 Returns the correct name to display for a buddy.
const char * purple_buddy_get_local_buddy_alias (PurpleBuddy *buddy)
 Returns the local alias for the buddy, or NULL if none exists.
const char * purple_chat_get_name (PurpleChat *chat)
 Returns the correct name to display for a blist chat.
PurpleBuddypurple_find_buddy (PurpleAccount *account, const char *name)
 Finds the buddy struct given a name and an account.
PurpleBuddypurple_find_buddy_in_group (PurpleAccount *account, const char *name, PurpleGroup *group)
 Finds the buddy struct given a name, an account, and a group.
GSList * purple_find_buddies (PurpleAccount *account, const char *name)
 Finds all PurpleBuddy structs given a name and an account.
PurpleGrouppurple_find_group (const char *name)
 Finds a group by name.
PurpleChatpurple_blist_find_chat (PurpleAccount *account, const char *name)
 Finds a chat by name.
PurpleGrouppurple_chat_get_group (PurpleChat *chat)
 Returns the group of which the chat is a member.
PurpleAccountpurple_chat_get_account (PurpleChat *chat)
 Returns the account the chat belongs to.
GHashTable * purple_chat_get_components (PurpleChat *chat)
 Get a hashtable containing information about a chat.
PurpleGrouppurple_buddy_get_group (PurpleBuddy *buddy)
 Returns the group of which the buddy is a member.
GSList * purple_group_get_accounts (PurpleGroup *g)
 Returns a list of accounts that have buddies in this group.
gboolean purple_group_on_account (PurpleGroup *g, PurpleAccount *account)
 Determines whether an account owns any buddies in a given group.
const char * purple_group_get_name (PurpleGroup *group)
 Returns the name of a group.
void purple_blist_add_account (PurpleAccount *account)
 Called when an account connects.
void purple_blist_remove_account (PurpleAccount *account)
 Called when an account disconnects.
int purple_blist_get_group_size (PurpleGroup *group, gboolean offline)
 Determines the total size of a group.
int purple_blist_get_group_online_count (PurpleGroup *group)
 Determines the number of online buddies in a group.
Buddy list file management API
void purple_blist_load (void)
 Loads the buddy list from ~/.purple/blist.xml.
void purple_blist_schedule_save (void)
 Schedule a save of the blist.xml file.
void purple_blist_request_add_buddy (PurpleAccount *account, const char *username, const char *group, const char *alias)
 Requests from the user information needed to add a buddy to the buddy list.
void purple_blist_request_add_chat (PurpleAccount *account, PurpleGroup *group, const char *alias, const char *name)
 Requests from the user information needed to add a chat to the buddy list.
void purple_blist_request_add_group (void)
 Requests from the user information needed to add a group to the buddy list.
void purple_blist_node_set_bool (PurpleBlistNode *node, const char *key, gboolean value)
 Associates a boolean with a node in the buddy list.
gboolean purple_blist_node_get_bool (PurpleBlistNode *node, const char *key)
 Retrieves a named boolean setting from a node in the buddy list.
void purple_blist_node_set_int (PurpleBlistNode *node, const char *key, int value)
 Associates an integer with a node in the buddy list.
int purple_blist_node_get_int (PurpleBlistNode *node, const char *key)
 Retrieves a named integer setting from a node in the buddy list.
void purple_blist_node_set_string (PurpleBlistNode *node, const char *key, const char *value)
 Associates a string with a node in the buddy list.
const char * purple_blist_node_get_string (PurpleBlistNode *node, const char *key)
 Retrieves a named string setting from a node in the buddy list.
void purple_blist_node_remove_setting (PurpleBlistNode *node, const char *key)
 Removes a named setting from a blist node.
void purple_blist_node_set_flags (PurpleBlistNode *node, PurpleBlistNodeFlags flags)
 Set the flags for the given node.
PurpleBlistNodeFlags purple_blist_node_get_flags (PurpleBlistNode *node)
 Get the current flags on a given node.
PurpleBlistNodeType purple_blist_node_get_type (PurpleBlistNode *node)
 Get the type of a given node.
UI Registration Functions
void purple_blist_set_ui_ops (PurpleBlistUiOps *ops)
 Sets the UI operations structure to be used for the buddy list.
PurpleBlistUiOpspurple_blist_get_ui_ops (void)
 Returns the UI operations structure to be used for the buddy list.
Buddy List Subsystem
void * purple_blist_get_handle (void)
 Returns the handle for the buddy list subsystem.
void purple_blist_init (void)
 Initializes the buddy list subsystem.
void purple_blist_uninit (void)
 Uninitializes the buddy list subsystem.

Detailed Description

Buddy List API.

See Also
Buddy List Signals

Definition in file blist.h.

Macro Definition Documentation

#define PURPLE_BLIST_NODE (   obj)    ((PurpleBlistNode *)(obj))
Since
2.6.0

Definition at line 81 of file blist.h.

#define PURPLE_BLIST_NODE_NAME (   n)
Value:
(purple_blist_node_get_type(n) == PURPLE_BLIST_CHAT_NODE ? purple_chat_get_name((PurpleChat*)n) : \
purple_blist_node_get_type(n) == PURPLE_BLIST_BUDDY_NODE ? purple_buddy_get_name((PurpleBuddy*)n) : NULL)

Definition at line 86 of file blist.h.

#define PURPLE_BUDDY (   obj)    ((PurpleBuddy *)(obj))
Since
2.6.0

Definition at line 102 of file blist.h.

#define PURPLE_BUDDY_IS_ONLINE (   b)
#define PURPLE_CHAT (   obj)    ((PurpleChat *)(obj))
Since
2.6.0

Definition at line 107 of file blist.h.

#define PURPLE_CONTACT (   obj)    ((PurpleContact *)(obj))
Since
2.6.0

Definition at line 97 of file blist.h.

#define PURPLE_GROUP (   obj)    ((PurpleGroup *)(obj))
Since
2.6.0

Definition at line 92 of file blist.h.

Typedef Documentation

A Buddy list node.

This can represent a group, a buddy, or anything else. This is a base class for PurpleBuddy, PurpleContact, PurpleGroup, and for anything else that wants to put itself in the buddy list.

Definition at line 39 of file blist.h.

Buddy list UI operations.

Any UI representing a buddy list must assign a filled-out PurpleBlistUiOps structure to the buddy list core.

Definition at line 37 of file blist.h.

typedef struct _PurpleBuddy PurpleBuddy

A buddy.

This contains everything Purple will ever need to know about someone on the buddy list. Everything.

Definition at line 48 of file blist.h.

The Buddy List.

Definition at line 35 of file blist.h.

typedef struct _PurpleChat PurpleChat

A chat.

This contains everything Purple needs to put a chat room in the buddy list.

Definition at line 42 of file blist.h.

typedef struct _PurpleContact PurpleContact

A contact.

This contains everything Purple will ever need to know about a contact.

Definition at line 46 of file blist.h.

typedef struct _PurpleGroup PurpleGroup

A group.

This contains everything Purple will ever need to know about a group.

Definition at line 44 of file blist.h.

Enumeration Type Documentation

Enumerator:
PURPLE_BLIST_NODE_FLAG_NO_SAVE 

node should not be saved with the buddy list

Definition at line 72 of file blist.h.

Function Documentation

void purple_blist_add_account ( PurpleAccount account)

Called when an account connects.

Tells the UI to update all the buddies.

Parameters
accountThe account
void purple_blist_add_buddy ( PurpleBuddy buddy,
PurpleContact contact,
PurpleGroup group,
PurpleBlistNode node 
)

Adds a new buddy to the buddy list.

The buddy will be inserted right after node or prepended to the group if node is NULL. If both are NULL, the buddy will be added to the "Buddies" group.

Parameters
buddyThe new buddy who gets added
contactThe optional contact to place the buddy in.
groupThe group to add the new buddy to.
nodeThe insertion point. Pass in NULL to add the node as the first child in the given group.
void purple_blist_add_chat ( PurpleChat chat,
PurpleGroup group,
PurpleBlistNode node 
)

Adds a new chat to the buddy list.

The chat will be inserted right after node or appended to the end of group if node is NULL. If both are NULL, the buddy will be added to the "Chats" group.

Parameters
chatThe new chat who gets added
groupThe group to add the new chat to.
nodeThe insertion point
void purple_blist_add_contact ( PurpleContact contact,
PurpleGroup group,
PurpleBlistNode node 
)

Adds a new contact to the buddy list.

The new contact will be inserted after insert or prepended to the list if node is NULL.

Parameters
contactThe contact
groupThe group to add the contact to
nodeThe insertion point
void purple_blist_add_group ( PurpleGroup group,
PurpleBlistNode node 
)

Adds a new group to the buddy list.

The new group will be inserted after insert or prepended to the list if node is NULL.

Parameters
groupThe group
nodeThe insertion point
void purple_blist_alias_buddy ( PurpleBuddy buddy,
const char *  alias 
)

Aliases a buddy in the buddy list.

Parameters
buddyThe buddy whose alias will be changed.
aliasThe buddy's alias.
void purple_blist_alias_chat ( PurpleChat chat,
const char *  alias 
)

Aliases a chat in the buddy list.

Parameters
chatThe chat whose alias will be changed.
aliasThe chat's new alias.
void purple_blist_alias_contact ( PurpleContact contact,
const char *  alias 
)

Aliases a contact in the buddy list.

Parameters
contactThe contact whose alias will be changed.
aliasThe contact's alias.
void purple_blist_destroy ( void  )

Destroys the buddy list window.

Deprecated:
The UI is responsible for cleaning up the PurpleBuddyList->ui_data. purple_blist_uninit() will free the PurpleBuddyList* itself.
PurpleChat* purple_blist_find_chat ( PurpleAccount account,
const char *  name 
)

Finds a chat by name.

Parameters
accountThe chat's account.
nameThe chat's name.
Returns
The chat, or NULL if the chat does not exist.
GSList* purple_blist_get_buddies ( void  )

Returns a list of every buddy in the list.

Use of this function is discouraged if you do not actually need every buddy in the list. Use purple_find_buddies instead.

Returns
A list of every buddy in the list. Caller is responsible for freeing the list.
See Also
purple_find_buddies
Since
2.6.0
int purple_blist_get_group_online_count ( PurpleGroup group)

Determines the number of online buddies in a group.

Parameters
groupThe group
Returns
The number of online buddies in the group, or 0 if the group is NULL
int purple_blist_get_group_size ( PurpleGroup group,
gboolean  offline 
)

Determines the total size of a group.

Parameters
groupThe group
offlineCount buddies in offline accounts
Returns
The number of buddies in the group
void* purple_blist_get_handle ( void  )

Returns the handle for the buddy list subsystem.

Returns
The buddy list subsystem handle.
PurpleBlistNode* purple_blist_get_root ( void  )

Returns the root node of the main buddy list.

Returns
The root node.
gpointer purple_blist_get_ui_data ( void  )

Returns the UI data for the list.

Returns
The UI data for the list.
Since
2.6.0
PurpleBlistUiOps* purple_blist_get_ui_ops ( void  )

Returns the UI operations structure to be used for the buddy list.

Returns
The UI operations structure.
void purple_blist_merge_contact ( PurpleContact source,
PurpleBlistNode node 
)

Merges two contacts.

All of the buddies from source will be moved to target

Parameters
sourceThe contact to merge
nodeThe place to merge to (a buddy or contact)
PurpleBuddyList* purple_blist_new ( void  )

Creates a new buddy list.

Returns
The new buddy list.
Deprecated:
In 3.0.0, this will be handled by purple_blist_init()
gboolean purple_blist_node_get_bool ( PurpleBlistNode node,
const char *  key 
)

Retrieves a named boolean setting from a node in the buddy list.

Parameters
nodeThe node to retrieve the data from
keyThe identifier of the data
Returns
The value, or FALSE if there is no setting
GList* purple_blist_node_get_extended_menu ( PurpleBlistNode n)

Retrieves the extended menu items for a buddy list node.

Parameters
nThe blist node for which to obtain the extended menu items.
Returns
A list of PurpleMenuAction items, as harvested by the blist-node-extended-menu signal.
PurpleBlistNode* purple_blist_node_get_first_child ( PurpleBlistNode node)

Returns the the first child node of a given node.

Parameters
nodeA node.
Returns
The child node.
Since
2.4.0
See Also
purple_blist_node_get_parent
purple_blist_node_get_sibling_next
purple_blist_node_get_sibling_prev
purple_blist_node_next
PurpleBlistNodeFlags purple_blist_node_get_flags ( PurpleBlistNode node)

Get the current flags on a given node.

Parameters
nodeThe node from which to get the flags.
Returns
The flags on the node. This is a bitmask.
int purple_blist_node_get_int ( PurpleBlistNode node,
const char *  key 
)

Retrieves a named integer setting from a node in the buddy list.

Parameters
nodeThe node to retrieve the data from
keyThe identifier of the data
Returns
The value, or 0 if there is no setting
PurpleBlistNode* purple_blist_node_get_parent ( PurpleBlistNode node)

Returns the parent node of a given node.

Parameters
nodeA node.
Returns
The parent node.
Since
2.4.0
See Also
purple_blist_node_get_first_child
purple_blist_node_get_sibling_next
purple_blist_node_get_sibling_prev
purple_blist_node_next
PurpleBlistNode* purple_blist_node_get_sibling_next ( PurpleBlistNode node)

Returns the sibling node of a given node.

Parameters
nodeA node.
Returns
The sibling node.
Since
2.4.0
See Also
purple_blist_node_get_parent
purple_blist_node_get_first_child
purple_blist_node_get_sibling_prev
purple_blist_node_next
PurpleBlistNode* purple_blist_node_get_sibling_prev ( PurpleBlistNode node)

Returns the previous sibling node of a given node.

Parameters
nodeA node.
Returns
The sibling node.
Since
2.4.0
See Also
purple_blist_node_get_parent
purple_blist_node_get_first_child
purple_blist_node_get_sibling_next
purple_blist_node_next
const char* purple_blist_node_get_string ( PurpleBlistNode node,
const char *  key 
)

Retrieves a named string setting from a node in the buddy list.

Parameters
nodeThe node to retrieve the data from
keyThe identifier of the data
Returns
The value, or NULL if there is no setting
PurpleBlistNodeType purple_blist_node_get_type ( PurpleBlistNode node)

Get the type of a given node.

Parameters
nodeThe node.
Returns
The type of the node.
Since
2.1.0
gpointer purple_blist_node_get_ui_data ( const PurpleBlistNode node)

Returns the UI data of a given node.

Parameters
nodeThe node.
Returns
The UI data.
Since
2.6.0
PurpleBlistNode* purple_blist_node_next ( PurpleBlistNode node,
gboolean  offline 
)

Returns the next node of a given node.

This function is to be used to iterate over the tree returned by purple_get_blist.

Parameters
nodeA node.
offlineWhether to include nodes for offline accounts
Returns
The next node
See Also
purple_blist_node_get_parent
purple_blist_node_get_first_child
purple_blist_node_get_sibling_next
purple_blist_node_get_sibling_prev
void purple_blist_node_remove_setting ( PurpleBlistNode node,
const char *  key 
)

Removes a named setting from a blist node.

Parameters
nodeThe node from which to remove the setting
keyThe name of the setting
void purple_blist_node_set_bool ( PurpleBlistNode node,
const char *  key,
gboolean  value 
)

Associates a boolean with a node in the buddy list.

Parameters
nodeThe node to associate the data with
keyThe identifier for the data
valueThe value to set
void purple_blist_node_set_flags ( PurpleBlistNode node,
PurpleBlistNodeFlags  flags 
)

Set the flags for the given node.

Setting a node's flags will overwrite the old flags, so if you want to save them, you must first call purple_blist_node_get_flags and modify that appropriately.

Parameters
nodeThe node on which to set the flags.
flagsThe flags to set. This is a bitmask.
void purple_blist_node_set_int ( PurpleBlistNode node,
const char *  key,
int  value 
)

Associates an integer with a node in the buddy list.

Parameters
nodeThe node to associate the data with
keyThe identifier for the data
valueThe value to set
void purple_blist_node_set_string ( PurpleBlistNode node,
const char *  key,
const char *  value 
)

Associates a string with a node in the buddy list.

Parameters
nodeThe node to associate the data with
keyThe identifier for the data
valueThe value to set
void purple_blist_node_set_ui_data ( PurpleBlistNode node,
gpointer  ui_data 
)

Sets the UI data of a given node.

Parameters
nodeThe node.
ui_dataThe UI data.
Since
2.6.0
void purple_blist_remove_account ( PurpleAccount account)

Called when an account disconnects.

Sets the presence of all the buddies to 0 and tells the UI to update them.

Parameters
accountThe account
void purple_blist_remove_buddy ( PurpleBuddy buddy)

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.

Parameters
buddyThe buddy to be removed
See Also
purple_account_remove_buddy
void purple_blist_remove_chat ( PurpleChat chat)

Removes a chat from the buddy list and frees the memory allocated to it.

Parameters
chatThe chat to be removed
void purple_blist_remove_contact ( PurpleContact contact)

Removes a contact, and any buddies it contains, and frees the memory allocated to it.

This calls purple_blist_remove_buddy and therefore doesn't remove the buddies from the server list.

Parameters
contactThe contact to be removed
See Also
purple_blist_remove_buddy
void purple_blist_remove_group ( PurpleGroup group)

Removes a group from the buddy list and frees the memory allocated to it and to its children.

Parameters
groupThe group to be removed
void purple_blist_rename_buddy ( PurpleBuddy buddy,
const char *  name 
)

Renames a buddy in the buddy list.

Parameters
buddyThe buddy whose name will be changed.
nameThe new name of the buddy.
void purple_blist_rename_group ( PurpleGroup group,
const char *  name 
)

Renames a group.

Parameters
groupThe group to rename
nameThe new name
void purple_blist_request_add_buddy ( PurpleAccount account,
const char *  username,
const char *  group,
const char *  alias 
)

Requests from the user information needed to add a buddy to the buddy list.

Parameters
accountThe account the buddy is added to.
usernameThe username of the buddy.
groupThe name of the group to place the buddy in.
aliasThe optional alias for the buddy.
void purple_blist_request_add_chat ( PurpleAccount account,
PurpleGroup group,
const char *  alias,
const char *  name 
)

Requests from the user information needed to add a chat to the buddy list.

Parameters
accountThe account the buddy is added to.
groupThe optional group to add the chat to.
aliasThe optional alias for the chat.
nameThe required chat name.
void purple_blist_schedule_save ( void  )

Schedule a save of the blist.xml file.

This is used by the privacy API whenever the privacy settings are changed. If you make a change to blist.xml using one of the functions in the buddy list API, then the buddy list is saved automatically, so you should not need to call this.

void purple_blist_server_alias_buddy ( PurpleBuddy buddy,
const char *  alias 
)

Sets the server-sent alias of a buddy in the buddy list.

PRPLs should call serv_got_alias() instead of this.

Parameters
buddyThe buddy whose alias will be changed.
aliasThe buddy's "official" alias.
void purple_blist_set_ui_data ( gpointer  ui_data)

Sets the UI data for the list.

Parameters
ui_dataThe UI data for the list.
Since
2.6.0
void purple_blist_set_ui_ops ( PurpleBlistUiOps ops)

Sets the UI operations structure to be used for the buddy list.

Parameters
opsThe ops struct.
void purple_blist_set_visible ( gboolean  show)

Hides or unhides the buddy list.

Parameters
showWhether or not to show the buddy list
void purple_blist_update_buddy_icon ( PurpleBuddy buddy)

Updates a buddy's icon.

Parameters
buddyThe buddy whose buddy icon has changed
Deprecated:
Use purple_blist_update_node_icon() instead.
void purple_blist_update_buddy_status ( PurpleBuddy buddy,
PurpleStatus *  old_status 
)

Updates a buddy's status.

This should only be called from within Purple.

Parameters
buddyThe buddy whose status has changed.
old_statusThe status from which we are changing.
void purple_blist_update_node_icon ( PurpleBlistNode node)

Updates a node's custom icon.

Parameters
nodeThe PurpleBlistNode whose custom icon has changed.
Since
2.5.0
void purple_buddy_destroy ( PurpleBuddy buddy)

Destroys a buddy.

Parameters
buddyThe buddy to destroy
PurpleAccount* purple_buddy_get_account ( const PurpleBuddy buddy)

Returns a buddy's account.

Parameters
buddyThe buddy.
Returns
The account
const char* purple_buddy_get_alias ( PurpleBuddy buddy)

Returns the correct name to display for a buddy.

In order of precedence: the buddy's alias; the buddy's server alias; the buddy's contact alias; the buddy's user name.

Parameters
buddyThe buddy whose name will be returned.
Returns
The appropriate name or alias, or NULL
const char* purple_buddy_get_alias_only ( PurpleBuddy buddy)

Returns the alias of a buddy.

Parameters
buddyThe buddy whose name will be returned.
Returns
The alias (if set), server alias (if set), or NULL.
PurpleContact* purple_buddy_get_contact ( PurpleBuddy buddy)

Returns a buddy's contact.

Parameters
buddyThe buddy.
Returns
The buddy's contact.
const char* purple_buddy_get_contact_alias ( PurpleBuddy buddy)

Returns the correct name to display for a buddy, taking the contact alias into account.

In order of precedence: the buddy's alias; the buddy's contact alias; the buddy's server alias; the buddy's user name.

Parameters
buddyThe buddy whose name will be returned
Returns
The appropriate name or alias, or NULL.
PurpleGroup* purple_buddy_get_group ( PurpleBuddy buddy)

Returns the group of which the buddy is a member.

Parameters
buddyThe buddy
Returns
The group or NULL if the buddy is not in a group
PurpleBuddyIcon* purple_buddy_get_icon ( const PurpleBuddy buddy)

Returns a buddy's icon.

Parameters
buddyThe buddy.
Returns
The buddy icon.
const char* purple_buddy_get_local_alias ( PurpleBuddy buddy)

Returns the correct alias for this user, ignoring server aliases.

Used when a user-recognizable name is required. In order: buddy's alias; buddy's contact alias; buddy's user name.

Parameters
buddyThe buddy whose alias will be returned.
Returns
The appropriate name or alias.
Deprecated:
Try purple_buddy_get_alias(), if server aliases are okay.
const char* purple_buddy_get_local_buddy_alias ( PurpleBuddy buddy)

Returns the local alias for the buddy, or NULL if none exists.

Parameters
buddyThe buddy
Returns
The local alias for the buddy
Since
2.6.0
PurpleMediaCaps purple_buddy_get_media_caps ( const PurpleBuddy buddy)

Gets the media caps from a buddy.

Parameters
buddyThe buddy.
Returns
The media caps.
Since
2.7.0
const char* purple_buddy_get_name ( const PurpleBuddy buddy)

Returns a buddy's name.

Parameters
buddyThe buddy.
Returns
The name.
PurplePresence* purple_buddy_get_presence ( const PurpleBuddy buddy)

Returns a buddy's presence.

Parameters
buddyThe buddy.
Returns
The buddy's presence.
gpointer purple_buddy_get_protocol_data ( const PurpleBuddy buddy)

Returns a buddy's protocol-specific data.

This should only be called from the associated prpl.

Parameters
buddyThe buddy.
Returns
The protocol data.
See Also
purple_buddy_set_protocol_data()
Since
2.6.0
const char* purple_buddy_get_server_alias ( PurpleBuddy buddy)

Gets the server alias for a buddy.

Parameters
buddyThe buddy whose name will be returned
Returns
The server alias, or NULL if it is not set.
PurpleBuddy* purple_buddy_new ( PurpleAccount account,
const char *  name,
const char *  alias 
)

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.

Parameters
accountThe account this buddy will get added to
nameThe name of the new buddy
aliasThe alias of the new buddy (or NULL if unaliased)
Returns
A newly allocated buddy
See Also
purple_account_add_buddy
purple_blist_add_buddy
void purple_buddy_set_icon ( PurpleBuddy buddy,
PurpleBuddyIcon icon 
)

Sets a buddy's icon.

This should only be called from within Purple. You probably want to call purple_buddy_icon_set_data().

Parameters
buddyThe buddy.
iconThe buddy icon.
See Also
purple_buddy_icon_set_data()
void purple_buddy_set_media_caps ( PurpleBuddy buddy,
PurpleMediaCaps  media_caps 
)

Sets the media caps for a buddy.

Parameters
buddyThe PurpleBuddy.
media_capsThe PurpleMediaCaps.
void purple_buddy_set_protocol_data ( PurpleBuddy buddy,
gpointer  data 
)

Sets a buddy's protocol-specific data.

This should only be called from the associated prpl.

Parameters
buddyThe buddy.
dataThe data.
See Also
purple_buddy_get_protocol_data()
Since
2.6.0
void purple_chat_destroy ( PurpleChat chat)

Destroys a chat.

Parameters
chatThe chat to destroy
PurpleAccount* purple_chat_get_account ( PurpleChat chat)

Returns the account the chat belongs to.

Parameters
chatThe chat.
Returns
The account the chat belongs to.
Since
2.4.0
GHashTable* purple_chat_get_components ( PurpleChat chat)

Get a hashtable containing information about a chat.

Parameters
chatThe chat.
Note
The return value of this function must not be modified or freed.
Returns
The hashtable.
Since
2.4.0
PurpleGroup* purple_chat_get_group ( PurpleChat chat)

Returns the group of which the chat is a member.

Parameters
chatThe chat.
Returns
The parent group, or NULL if the chat is not in a group.
const char* purple_chat_get_name ( PurpleChat chat)

Returns the correct name to display for a blist chat.

Parameters
chatThe chat whose name will be returned.
Returns
The alias (if set), or first component value.
PurpleChat* purple_chat_new ( PurpleAccount account,
const char *  alias,
GHashTable *  components 
)

Creates a new chat for the buddy list.

Parameters
accountThe account this chat will get added to
aliasThe alias of the new chat
componentsThe info the prpl needs to join the chat. The hash function should be g_str_hash() and the equal function should be g_str_equal().
Returns
A newly allocated chat
void purple_contact_destroy ( PurpleContact contact)

Destroys a contact.

Parameters
contactThe contact to destroy
const char* purple_contact_get_alias ( PurpleContact contact)

Gets the alias for a contact.

Parameters
contactThe contact
Returns
The alias, or NULL if it is not set.
PurpleGroup* purple_contact_get_group ( const PurpleContact contact)

Gets the PurpleGroup from a PurpleContact.

Parameters
contactThe contact
Returns
The group
Since
2.7.0
PurpleBuddy* purple_contact_get_priority_buddy ( PurpleContact contact)

Returns the highest priority buddy for a given contact.

Parameters
contactThe contact
Returns
The highest priority buddy
void purple_contact_invalidate_priority_buddy ( PurpleContact contact)

Invalidates the priority buddy so that the next call to purple_contact_get_priority_buddy recomputes it.

Parameters
contactThe contact
PurpleContact* purple_contact_new ( void  )

Creates a new contact.

Returns
A new contact struct
gboolean purple_contact_on_account ( PurpleContact contact,
PurpleAccount account 
)

Determines whether an account owns any buddies in a given contact.

Parameters
contactThe contact to search through.
accountThe account.
Returns
TRUE if there are any buddies from account in the contact, or FALSE otherwise.
void purple_contact_set_alias ( PurpleContact contact,
const char *  alias 
)

Sets the alias for a contact.

Parameters
contactThe contact
aliasThe alias to set, or NULL to unset
Deprecated:
Use purple_blist_alias_contact() instead.
GSList* purple_find_buddies ( PurpleAccount account,
const char *  name 
)

Finds all PurpleBuddy structs given a name and an account.

Parameters
accountThe account this buddy belongs to
nameThe buddy's name (or NULL to return all buddies for the account)
Returns
A GSList of buddies (which must be freed), or NULL if the buddy doesn't exist
PurpleBuddy* purple_find_buddy ( PurpleAccount account,
const char *  name 
)

Finds the buddy struct given a name and an account.

Parameters
accountThe account this buddy belongs to
nameThe buddy's name
Returns
The buddy or NULL if the buddy does not exist
PurpleBuddy* purple_find_buddy_in_group ( PurpleAccount account,
const char *  name,
PurpleGroup group 
)

Finds the buddy struct given a name, an account, and a group.

Parameters
accountThe account this buddy belongs to
nameThe buddy's name
groupThe group to look in
Returns
The buddy or NULL if the buddy does not exist in the group
PurpleGroup* purple_find_group ( const char *  name)

Finds a group by name.

Parameters
nameThe group's name
Returns
The group or NULL if the group does not exist
PurpleBuddyList* purple_get_blist ( void  )

Returns the main buddy list.

Returns
The main buddy list.
void purple_group_destroy ( PurpleGroup group)

Destroys a group.

Parameters
groupThe group to destroy
GSList* purple_group_get_accounts ( PurpleGroup g)

Returns a list of accounts that have buddies in this group.

Parameters
gThe group
Returns
A GSList of accounts (which must be freed), or NULL if the group has no accounts.
const char* purple_group_get_name ( PurpleGroup group)

Returns the name of a group.

Parameters
groupThe group.
Returns
The name of the group.
PurpleGroup* purple_group_new ( const char *  name)

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.

Parameters
nameThe name of the new group
Returns
A new group struct
gboolean purple_group_on_account ( PurpleGroup g,
PurpleAccount account 
)

Determines whether an account owns any buddies in a given group.

Parameters
gThe group to search through.
accountThe account.
Returns
TRUE if there are any buddies in the group, or FALSE otherwise.
void purple_set_blist ( PurpleBuddyList blist)

Sets the main buddy list.

Parameters
blistThe buddy list you want to use.
Deprecated:
In 3.0.0, this will be handled by purple_blist_init()
All information, including names and email addresses, entered onto this website or sent to mailing lists affiliated with this website will be public. Do not post confidential information, especially passwords!