blist.h File Reference
libpurple

Buddy List API. More...

`#include <glib.h>`
`#include "account.h"`
`#include "buddyicon.h"`
`#include "media.h"`
`#include "status.h"`

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_IS_VISIBLE(b) (! PURPLE_BLIST_NODE_HAS_FLAG(b, PURPLE_BLIST_NODE_FLAG_INVISIBLE))
#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. More...
typedef struct _PurpleBlistUiOps | PurpleBlistUiOps
| Buddy list UI operations. More...
typedef struct _PurpleBlistNode | PurpleBlistNode
| A Buddy list node. More...
typedef struct _PurpleChat | PurpleChat
| A chat. More...
typedef struct _PurpleGroup | PurpleGroup
| A group. More...
typedef struct _PurpleContact | PurpleContact
| A contact. More...
typedef struct _PurpleBuddy | PurpleBuddy
| A buddy. More...

## 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 , PURPLE_BLIST_NODE_FLAG_INVISIBLE = 1 << 1 }

## Functions

Buddy List API <br>
PurpleBuddyList * | purple_blist_new (void)
| Creates a new buddy list. More...
void | purple_set_blist (PurpleBuddyList *blist)
| Sets the main buddy list. More...
PurpleBuddyList * | purple_get_blist (void)
| Returns the main buddy list. More...
PurpleBlistNode * | purple_blist_get_root (void)
| Returns the root node of the main buddy list. More...
GSList * | purple_blist_get_buddies (void)
| Returns a list of every buddy in the list. More...
gpointer | purple_blist_get_ui_data (void)
| Returns the UI data for the list. More...
void | purple_blist_set_ui_data (gpointer ui_data)
| Sets the UI data for the list. More...
PurpleBlistNode * | purple_blist_node_next (PurpleBlistNode *node, gboolean offline)
| Returns the next node of a given node. More...
PurpleBlistNode * | purple_blist_node_get_parent (PurpleBlistNode *node)
| Returns the parent node of a given node. More...
PurpleBlistNode * | purple_blist_node_get_first_child (PurpleBlistNode *node)
| Returns the the first child node of a given node. More...
PurpleBlistNode * | purple_blist_node_get_sibling_next (PurpleBlistNode *node)
| Returns the sibling node of a given node. More...
PurpleBlistNode * | purple_blist_node_get_sibling_prev (PurpleBlistNode *node)
| Returns the previous sibling node of a given node. More...
gpointer | purple_blist_node_get_ui_data (const PurpleBlistNode *node)
| Returns the UI data of a given node. More...
void | purple_blist_node_set_ui_data (PurpleBlistNode *node, gpointer ui_data)
| Sets the UI data of a given node. More...
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. More...
void | purple_blist_set_visible (gboolean show)
| Hides or unhides the buddy list. More...
void | purple_blist_update_buddy_status (PurpleBuddy *buddy, PurpleStatus *old_status)
| Updates a buddy's status. More...
void | purple_blist_update_node_icon (PurpleBlistNode *node)
| Updates a node's custom icon. More...
void | purple_blist_update_buddy_icon (PurpleBuddy *buddy)
| Updates a buddy's icon. More...
void | purple_blist_rename_buddy (PurpleBuddy *buddy, const char *name)
| Renames a buddy in the buddy list. More...
void | purple_blist_alias_contact (PurpleContact *contact, const char *alias)
| Aliases a contact in the buddy list. More...
void | purple_blist_alias_buddy (PurpleBuddy *buddy, const char *alias)
| Aliases a buddy in the buddy list. More...
void | purple_blist_server_alias_buddy (PurpleBuddy *buddy, const char *alias)
| Sets the server-sent alias of a buddy in the buddy list. More...
void | purple_blist_alias_chat (PurpleChat *chat, const char *alias)
| Aliases a chat in the buddy list. More...
void | purple_blist_rename_group (PurpleGroup *group, const char *name)
| Renames a group. More...
PurpleChat * | purple_chat_new (PurpleAccount *account, const char *alias, GHashTable *components)
| Creates a new chat for the buddy list. More...
void | purple_chat_destroy (PurpleChat *chat)
| Destroys a chat. More...
void | purple_blist_add_chat (PurpleChat *chat, PurpleGroup *group, PurpleBlistNode *node)
| Adds a new chat to the buddy list. More...
PurpleBuddy * | purple_buddy_new (PurpleAccount *account, const char *name, const char *alias)
| Creates a new buddy. More...
void | purple_buddy_destroy (PurpleBuddy *buddy)
| Destroys a buddy. More...
void | purple_buddy_set_icon (PurpleBuddy *buddy, PurpleBuddyIcon *icon)
| Sets a buddy's icon. More...
PurpleAccount * | purple_buddy_get_account (const PurpleBuddy *buddy)
| Returns a buddy's account. More...
const char * | purple_buddy_get_name (const PurpleBuddy *buddy)
| Returns a buddy's name. More...
PurpleBuddyIcon * | purple_buddy_get_icon (const PurpleBuddy *buddy)
| Returns a buddy's icon. More...
gpointer | purple_buddy_get_protocol_data (const PurpleBuddy *buddy)
| Returns a buddy's protocol-specific data. More...
void | purple_buddy_set_protocol_data (PurpleBuddy *buddy, gpointer data)
| Sets a buddy's protocol-specific data. More...
PurpleContact * | purple_buddy_get_contact (PurpleBuddy *buddy)
| Returns a buddy's contact. More...
PurplePresence * | purple_buddy_get_presence (const PurpleBuddy *buddy)
| Returns a buddy's presence. More...
PurpleMediaCaps | purple_buddy_get_media_caps (const PurpleBuddy *buddy)
| Gets the media caps from a buddy. More...
void | purple_buddy_set_media_caps (PurpleBuddy *buddy, PurpleMediaCaps media_caps)
| Sets the media caps for a buddy. More...
void | purple_blist_add_buddy (PurpleBuddy *buddy, PurpleContact *contact, PurpleGroup *group, PurpleBlistNode *node)
| Adds a new buddy to the buddy list. More...
PurpleGroup * | purple_group_new (const char *name)
| Creates a new group. More...
void | purple_group_destroy (PurpleGroup *group)
| Destroys a group. More...
void | purple_blist_add_group (PurpleGroup *group, PurpleBlistNode *node)
| Adds a new group to the buddy list. More...
PurpleContact * | purple_contact_new (void)
| Creates a new contact. More...
void | purple_contact_destroy (PurpleContact *contact)
| Destroys a contact. More...
PurpleGroup * | purple_contact_get_group (const PurpleContact *contact)
| Gets the PurpleGroup from a PurpleContact. More...
void | purple_blist_add_contact (PurpleContact *contact, PurpleGroup *group, PurpleBlistNode *node)
| Adds a new contact to the buddy list. More...
void | purple_blist_merge_contact (PurpleContact *source, PurpleBlistNode *node)
| Merges two contacts. More...
PurpleBuddy * | purple_contact_get_priority_buddy (PurpleContact *contact)
| Returns the highest priority buddy for a given contact. More...
void | purple_contact_set_alias (PurpleContact *contact, const char *alias)
| Sets the alias for a contact. More...
const char * | purple_contact_get_alias (PurpleContact *contact)
| Gets the alias for a contact. More...
gboolean | purple_contact_on_account (PurpleContact *contact, PurpleAccount *account)
| Determines whether an account owns any buddies in a given contact. More...
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. More...
void | purple_blist_remove_buddy (PurpleBuddy *buddy)
| Removes a buddy from the buddy list and frees the memory allocated to it. More...
void | purple_blist_remove_contact (PurpleContact *contact)
| Removes a contact, and any buddies it contains, and frees the memory allocated to it. More...
void | purple_blist_remove_chat (PurpleChat *chat)
| Removes a chat from the buddy list and frees the memory allocated to it. More...
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. More...
const char * | purple_buddy_get_alias_only (PurpleBuddy *buddy)
| Returns the alias of a buddy. More...
const char * | purple_buddy_get_server_alias (PurpleBuddy *buddy)
| Gets the server alias for a buddy. More...
const char * | purple_buddy_get_contact_alias (PurpleBuddy *buddy)
| Returns the correct name to display for a buddy, taking the contact alias into account. More...
const char * | purple_buddy_get_local_alias (PurpleBuddy *buddy)
| Returns the correct alias for this user, ignoring server aliases. More...
const char * | purple_buddy_get_alias (PurpleBuddy *buddy)
| Returns the correct name to display for a buddy. More...
const char * | purple_buddy_get_local_buddy_alias (PurpleBuddy *buddy)
| Returns the local alias for the buddy, or `NULL` if none exists. More...
const char * | purple_chat_get_name (PurpleChat *chat)
| Returns the correct name to display for a blist chat. More...
PurpleBuddy * | purple_find_buddy (PurpleAccount *account, const char *name)
| Finds the buddy struct given a name and an account. More...
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. More...
GSList * | purple_find_buddies (PurpleAccount *account, const char *name)
| Finds all PurpleBuddy structs given a name and an account. More...
PurpleGroup * | purple_find_group (const char *name)
| Finds a group by name. More...
PurpleChat * | purple_blist_find_chat (PurpleAccount *account, const char *name)
| Finds a chat by name. More...
PurpleGroup * | purple_chat_get_group (PurpleChat *chat)
| Returns the group of which the chat is a member. More...
PurpleAccount * | purple_chat_get_account (PurpleChat *chat)
| Returns the account the chat belongs to. More...
GHashTable * | purple_chat_get_components (PurpleChat *chat)
| Get a hashtable containing information about a chat. More...
PurpleGroup * | purple_buddy_get_group (PurpleBuddy *buddy)
| Returns the group of which the buddy is a member. More...
GSList * | purple_group_get_accounts (PurpleGroup *g)
| Returns a list of accounts that have buddies in this group. More...
gboolean | purple_group_on_account (PurpleGroup *g, PurpleAccount *account)
| Determines whether an account owns any buddies in a given group. More...
const char * | purple_group_get_name (PurpleGroup *group)
| Returns the name of a group. More...
void | purple_blist_add_account (PurpleAccount *account)
| Called when an account connects. More...
void | purple_blist_remove_account (PurpleAccount *account)
| Called when an account disconnects. More...
int | purple_blist_get_group_size (PurpleGroup *group, gboolean offline)
| Determines the total size of a group. More...
int | purple_blist_get_group_online_count (PurpleGroup *group)
| Determines the number of online buddies in a group. More...
Buddy list file management API <br>
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. More...
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. More...
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. More...
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. More...
gboolean | purple_blist_node_get_bool (PurpleBlistNode *node, const char *key)
| Retrieves a named boolean setting from a node in the buddy list. More...
void | purple_blist_node_set_int (PurpleBlistNode *node, const char *key, int value)
| Associates an integer with a node in the buddy list. More...
int | purple_blist_node_get_int (PurpleBlistNode *node, const char *key)
| Retrieves a named integer setting from a node in the buddy list. More...
void | purple_blist_node_set_string (PurpleBlistNode *node, const char *key, const char *value)
| Associates a string with a node in the buddy list. More...
const char * | purple_blist_node_get_string (PurpleBlistNode *node, const char *key)
| Retrieves a named string setting from a node in the buddy list. More...
void | purple_blist_node_remove_setting (PurpleBlistNode *node, const char *key)
| Removes a named setting from a blist node. More...
void | purple_blist_node_set_flags (PurpleBlistNode *node, PurpleBlistNodeFlags flags)
| Set the flags for the given node. More...
PurpleBlistNodeFlags | purple_blist_node_get_flags (PurpleBlistNode *node)
| Get the current flags on a given node. More...
PurpleBlistNodeType | purple_blist_node_get_type (PurpleBlistNode *node)
| Get the type of a given node. More...
GList * | purple_blist_node_get_extended_menu (PurpleBlistNode *n)
| Retrieves the extended menu items for a buddy list node. More...
UI Registration Functions <br>
void | purple_blist_set_ui_ops (PurpleBlistUiOps *ops)
| Sets the UI operations structure to be used for the buddy list. More...
PurpleBlistUiOps * | purple_blist_get_ui_ops (void)
| Returns the UI operations structure to be used for the buddy list. More...
Buddy List Subsystem <br>
void * | purple_blist_get_handle (void)
| Returns the handle for the buddy list subsystem. More...
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

## PURPLE_BLIST_NODE

#define PURPLE_BLIST_NODE | ( |  | obj | ) | ((PurpleBlistNode *)(obj))

Since
  2.6.0

Definition at line 82 of file blist.h.

## PURPLE_BLIST_NODE_NAME

#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)
purple_blist_node_get_type
PurpleBlistNodeType purple_blist_node_get_type(PurpleBlistNode *node)
Get the type of a given node.
purple_buddy_get_name
const char * purple_buddy_get_name(const PurpleBuddy *buddy)
Returns a buddy's name.
purple_chat_get_name
const char * purple_chat_get_name(PurpleChat *chat)
Returns the correct name to display for a blist chat.
_PurpleBuddy
A buddy.
Definition: blist.h:140
_PurpleChat
A chat.
Definition: blist.h:181

Definition at line 88 of file blist.h.

## PURPLE_BUDDY

#define PURPLE_BUDDY | ( |  | obj | ) | ((PurpleBuddy *)(obj))

Since
  2.6.0

Definition at line 104 of file blist.h.

## PURPLE_BUDDY_IS_ONLINE

#define PURPLE_BUDDY_IS_ONLINE | ( |  | b | ) |

Value:
((b) != NULL && purple_account_is_connected(purple_buddy_get_account(b)) && \
purple_presence_is_online(purple_buddy_get_presence(b)))
purple_account_is_connected
gboolean purple_account_is_connected(const PurpleAccount *account)
Returns whether or not the account is connected.
purple_buddy_get_presence
PurplePresence * purple_buddy_get_presence(const PurpleBuddy *buddy)
Returns a buddy's presence.
purple_buddy_get_account
PurpleAccount * purple_buddy_get_account(const PurpleBuddy *buddy)
Returns a buddy's account.
purple_presence_is_online
gboolean purple_presence_is_online(const PurplePresence *presence)
Returns whether or not a presence is online.

Definition at line 68 of file blist.h.

## PURPLE_CHAT

#define PURPLE_CHAT | ( |  | obj | ) | ((PurpleChat *)(obj))

Since
  2.6.0

Definition at line 109 of file blist.h.

## PURPLE_CONTACT

#define PURPLE_CONTACT | ( |  | obj | ) | ((PurpleContact *)(obj))

Since
  2.6.0

Definition at line 99 of file blist.h.

## PURPLE_GROUP

#define PURPLE_GROUP | ( |  | obj | ) | ((PurpleGroup *)(obj))

Since
  2.6.0

Definition at line 94 of file blist.h.

## Typedef Documentation

## PurpleBlistNode

typedef struct _PurpleBlistNode PurpleBlistNode

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 1 of file blist.h.

## PurpleBlistUiOps

typedef struct _PurpleBlistUiOps PurpleBlistUiOps

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 1 of file blist.h.

## PurpleBuddy

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 1 of file blist.h.

## PurpleBuddyList

typedef struct _PurpleBuddyList PurpleBuddyList

The Buddy List.

Definition at line 1 of file blist.h.

## PurpleChat

typedef struct _PurpleChat PurpleChat

A chat.

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

Definition at line 1 of file blist.h.

## PurpleContact

typedef struct _PurpleContact PurpleContact

A contact.

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

Definition at line 1 of file blist.h.

## PurpleGroup

typedef struct _PurpleGroup PurpleGroup

A group.

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

Definition at line 1 of file blist.h.

## Enumeration Type Documentation

## PurpleBlistNodeFlags

enum PurpleBlistNodeFlags

Enumerator
PURPLE_BLIST_NODE_FLAG_NO_SAVE | node should not be saved with the buddy list
PURPLE_BLIST_NODE_FLAG_INVISIBLE | node should not be displayed

Definition at line 72 of file blist.h.

## Function Documentation

## purple_blist_add_account()

void purple_blist_add_account | ( | PurpleAccount * | account | ) |

Called when an account connects.

Tells the UI to update all the buddies.

Parameters

  account | The account

## purple_blist_add_buddy()

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

  buddy | The new buddy who gets added
  contact | The optional contact to place the buddy in.
  group | The group to add the new buddy to.
  node | The insertion point. Pass in NULL to add the node as the first child in the given group.

## purple_blist_add_chat()

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

  chat | The new chat who gets added
  group | The group to add the new chat to.
  node | The insertion point

## purple_blist_add_contact()

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

  contact | The contact
  group | The group to add the contact to
  node | The insertion point

## purple_blist_add_group()

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

  group | The group
  node | The insertion point

## purple_blist_alias_buddy()

void purple_blist_alias_buddy | ( | PurpleBuddy * | buddy,
|  | const char * | alias
| ) |  |

Aliases a buddy in the buddy list.

Parameters

  buddy | The buddy whose alias will be changed.
  alias | The buddy's alias.

## purple_blist_alias_chat()

void purple_blist_alias_chat | ( | PurpleChat * | chat,
|  | const char * | alias
| ) |  |

Aliases a chat in the buddy list.

Parameters

  chat | The chat whose alias will be changed.
  alias | The chat's new alias.

## purple_blist_alias_contact()

void purple_blist_alias_contact | ( | PurpleContact * | contact,
|  | const char * | alias
| ) |  |

Aliases a contact in the buddy list.

Parameters

  contact | The contact whose alias will be changed.
  alias | The contact's alias.

## purple_blist_destroy()

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.

## purple_blist_find_chat()

PurpleChat* purple_blist_find_chat | ( | PurpleAccount * | account,
|  | const char * | name
| ) |  |

Finds a chat by name.

Parameters

  account | The chat's account.
  name | The chat's name.

Returns
  The chat, or `NULL` if the chat does not exist.

## purple_blist_get_buddies()

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

## purple_blist_get_group_online_count()

int purple_blist_get_group_online_count | ( | PurpleGroup * | group | ) |

Determines the number of online buddies in a group.

Parameters

  group | The group

Returns
  The number of online buddies in the group, or 0 if the group is NULL

## purple_blist_get_group_size()

int purple_blist_get_group_size | ( | PurpleGroup * | group,
|  | gboolean | offline
| ) |  |

Determines the total size of a group.

Parameters

  group | The group
  offline | Count buddies in offline accounts

Returns
  The number of buddies in the group

## purple_blist_get_handle()

void* purple_blist_get_handle | ( | void |  | ) |

Returns the handle for the buddy list subsystem.

Returns
  The buddy list subsystem handle.

## purple_blist_get_root()

PurpleBlistNode* purple_blist_get_root | ( | void |  | ) |

Returns the root node of the main buddy list.

Returns
  The root node.

## purple_blist_get_ui_data()

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

## purple_blist_get_ui_ops()

PurpleBlistUiOps* purple_blist_get_ui_ops | ( | void |  | ) |

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

Returns
  The UI operations structure.

## purple_blist_merge_contact()

void purple_blist_merge_contact | ( | PurpleContact * | source,
|  | PurpleBlistNode * | node
| ) |  |

Merges two contacts.

All of the buddies from source will be moved to target

Parameters

  source | The contact to merge
  node | The place to merge to (a buddy or contact)

## purple_blist_new()

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()

## purple_blist_node_get_bool()

gboolean purple_blist_node_get_bool | ( | PurpleBlistNode * | node,
|  | const char * | key
| ) |  |

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

Parameters

  node | The node to retrieve the data from
  key | The identifier of the data

Returns
  The value, or FALSE if there is no setting

## purple_blist_node_get_extended_menu()

GList* purple_blist_node_get_extended_menu | ( | PurpleBlistNode * | n | ) |

Retrieves the extended menu items for a buddy list node.

Parameters

  n | The 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.

## purple_blist_node_get_first_child()

PurpleBlistNode* purple_blist_node_get_first_child | ( | PurpleBlistNode * | node | ) |

Returns the the first child node of a given node.

Parameters

  node | A 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

## purple_blist_node_get_flags()

PurpleBlistNodeFlags purple_blist_node_get_flags | ( | PurpleBlistNode * | node | ) |

Get the current flags on a given node.

Parameters

  node | The node from which to get the flags.

Returns
  The flags on the node. This is a bitmask.

## purple_blist_node_get_int()

int purple_blist_node_get_int | ( | PurpleBlistNode * | node,
|  | const char * | key
| ) |  |

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

Parameters

  node | The node to retrieve the data from
  key | The identifier of the data

Returns
  The value, or 0 if there is no setting

## purple_blist_node_get_parent()

PurpleBlistNode* purple_blist_node_get_parent | ( | PurpleBlistNode * | node | ) |

Returns the parent node of a given node.

Parameters

  node | A 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

## purple_blist_node_get_sibling_next()

PurpleBlistNode* purple_blist_node_get_sibling_next | ( | PurpleBlistNode * | node | ) |

Returns the sibling node of a given node.

Parameters

  node | A 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

## purple_blist_node_get_sibling_prev()

PurpleBlistNode* purple_blist_node_get_sibling_prev | ( | PurpleBlistNode * | node | ) |

Returns the previous sibling node of a given node.

Parameters

  node | A 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

## purple_blist_node_get_string()

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

  node | The node to retrieve the data from
  key | The identifier of the data

Returns
  The value, or NULL if there is no setting

## purple_blist_node_get_type()

PurpleBlistNodeType purple_blist_node_get_type | ( | PurpleBlistNode * | node | ) |

Get the type of a given node.

Parameters

  node | The node.

Returns
  The type of the node.

Since
  2.1.0

## purple_blist_node_get_ui_data()

gpointer purple_blist_node_get_ui_data | ( | const PurpleBlistNode * | node | ) |

Returns the UI data of a given node.

Parameters

  node | The node.

Returns
  The UI data.

Since
  2.6.0

## purple_blist_node_next()

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

  node | A node.
  offline | Whether 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

## purple_blist_node_remove_setting()

void purple_blist_node_remove_setting | ( | PurpleBlistNode * | node,
|  | const char * | key
| ) |  |

Removes a named setting from a blist node.

Parameters

  node | The node from which to remove the setting
  key | The name of the setting

## purple_blist_node_set_bool()

void purple_blist_node_set_bool | ( | PurpleBlistNode * | node,
|  | const char * | key,
|  | gboolean | value
| ) |  |

Associates a boolean with a node in the buddy list.

Parameters

  node | The node to associate the data with
  key | The identifier for the data
  value | The value to set

## purple_blist_node_set_flags()

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

  node | The node on which to set the flags.
  flags | The flags to set. This is a bitmask.

## purple_blist_node_set_int()

void purple_blist_node_set_int | ( | PurpleBlistNode * | node,
|  | const char * | key,
|  | int | value
| ) |  |

Associates an integer with a node in the buddy list.

Parameters

  node | The node to associate the data with
  key | The identifier for the data
  value | The value to set

## purple_blist_node_set_string()

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

  node | The node to associate the data with
  key | The identifier for the data
  value | The value to set

## purple_blist_node_set_ui_data()

void purple_blist_node_set_ui_data | ( | PurpleBlistNode * | node,
|  | gpointer | ui_data
| ) |  |

Sets the UI data of a given node.

Parameters

  node | The node.
  ui_data | The UI data.

Since
  2.6.0

## purple_blist_remove_account()

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

  account | The account

## purple_blist_remove_buddy()

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

  buddy | The buddy to be removed

See also
  purple_account_remove_buddy

## purple_blist_remove_chat()

void purple_blist_remove_chat | ( | PurpleChat * | chat | ) |

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

Parameters

  chat | The chat to be removed

## purple_blist_remove_contact()

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

  contact | The contact to be removed

See also
  purple_blist_remove_buddy

## purple_blist_remove_group()

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

  group | The group to be removed

## purple_blist_rename_buddy()

void purple_blist_rename_buddy | ( | PurpleBuddy * | buddy,
|  | const char * | name
| ) |  |

Renames a buddy in the buddy list.

Parameters

  buddy | The buddy whose name will be changed.
  name | The new name of the buddy.

## purple_blist_rename_group()

void purple_blist_rename_group | ( | PurpleGroup * | group,
|  | const char * | name
| ) |  |

Renames a group.

Parameters

  group | The group to rename
  name | The new name

## purple_blist_request_add_buddy()

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

  account | The account the buddy is added to.
  username | The username of the buddy.
  group | The name of the group to place the buddy in.
  alias | The optional alias for the buddy.

## purple_blist_request_add_chat()

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

  account | The account the buddy is added to.
  group | The optional group to add the chat to.
  alias | The optional alias for the chat.
  name | The required chat name.

## purple_blist_schedule_save()

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.

## purple_blist_server_alias_buddy()

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

  buddy | The buddy whose alias will be changed.
  alias | The buddy's "official" alias.

## purple_blist_set_ui_data()

void purple_blist_set_ui_data | ( | gpointer | ui_data | ) |

Sets the UI data for the list.

Parameters

  ui_data | The UI data for the list.

Since
  2.6.0

## purple_blist_set_ui_ops()

void purple_blist_set_ui_ops | ( | PurpleBlistUiOps * | ops | ) |

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

Parameters

  ops | The ops struct.

## purple_blist_set_visible()

void purple_blist_set_visible | ( | gboolean | show | ) |

Hides or unhides the buddy list.

Parameters

  show | Whether or not to show the buddy list

## purple_blist_update_buddy_icon()

void purple_blist_update_buddy_icon | ( | PurpleBuddy * | buddy | ) |

Updates a buddy's icon.

Parameters

  buddy | The buddy whose buddy icon has changed

Deprecated:
  Use purple_blist_update_node_icon() instead.

## purple_blist_update_buddy_status()

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

  buddy | The buddy whose status has changed.
  old_status | The status from which we are changing.

## purple_blist_update_node_icon()

void purple_blist_update_node_icon | ( | PurpleBlistNode * | node | ) |

Updates a node's custom icon.

Parameters

  node | The PurpleBlistNode whose custom icon has changed.

Since
  2.5.0

## purple_buddy_destroy()

void purple_buddy_destroy | ( | PurpleBuddy * | buddy | ) |

Destroys a buddy.

Parameters

  buddy | The buddy to destroy

## purple_buddy_get_account()

PurpleAccount* purple_buddy_get_account | ( | const PurpleBuddy * | buddy | ) |

Returns a buddy's account.

Parameters

  buddy | The buddy.

Returns
  The account

## purple_buddy_get_alias()

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

  buddy | The buddy whose name will be returned.

Returns
  The appropriate name or alias, or NULL

## purple_buddy_get_alias_only()

const char* purple_buddy_get_alias_only | ( | PurpleBuddy * | buddy | ) |

Returns the alias of a buddy.

Parameters

  buddy | The buddy whose name will be returned.

Returns
  The alias (if set), server alias (if set), or NULL.

## purple_buddy_get_contact()

PurpleContact* purple_buddy_get_contact | ( | PurpleBuddy * | buddy | ) |

Returns a buddy's contact.

Parameters

  buddy | The buddy.

Returns
  The buddy's contact.

## purple_buddy_get_contact_alias()

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

  buddy | The buddy whose name will be returned

Returns
  The appropriate name or alias, or NULL.

## purple_buddy_get_group()

PurpleGroup* purple_buddy_get_group | ( | PurpleBuddy * | buddy | ) |

Returns the group of which the buddy is a member.

Parameters

  buddy | The buddy

Returns
  The group or NULL if the buddy is not in a group

## purple_buddy_get_icon()

PurpleBuddyIcon* purple_buddy_get_icon | ( | const PurpleBuddy * | buddy | ) |

Returns a buddy's icon.

Parameters

  buddy | The buddy.

Returns
  The buddy icon.

## purple_buddy_get_local_alias()

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

  buddy | The buddy whose alias will be returned.

Returns
  The appropriate name or alias.

Deprecated:
  Try purple_buddy_get_alias(), if server aliases are okay.

## purple_buddy_get_local_buddy_alias()

const char* purple_buddy_get_local_buddy_alias | ( | PurpleBuddy * | buddy | ) |

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

Parameters

  buddy | The buddy

Returns
  The local alias for the buddy

Since
  2.6.0

## purple_buddy_get_media_caps()

PurpleMediaCaps purple_buddy_get_media_caps | ( | const PurpleBuddy * | buddy | ) |

Gets the media caps from a buddy.

Parameters

  buddy | The buddy.

Returns
  The media caps.

Since
  2.7.0

## purple_buddy_get_name()

const char* purple_buddy_get_name | ( | const PurpleBuddy * | buddy | ) |

Returns a buddy's name.

Parameters

  buddy | The buddy.

Returns
  The name.

## purple_buddy_get_presence()

PurplePresence* purple_buddy_get_presence | ( | const PurpleBuddy * | buddy | ) |

Returns a buddy's presence.

Parameters

  buddy | The buddy.

Returns
  The buddy's presence.

## purple_buddy_get_protocol_data()

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

  buddy | The buddy.

Returns
  The protocol data.

See also
  purple_buddy_set_protocol_data()

Since
  2.6.0

## purple_buddy_get_server_alias()

const char* purple_buddy_get_server_alias | ( | PurpleBuddy * | buddy | ) |

Gets the server alias for a buddy.

Parameters

  buddy | The buddy whose name will be returned

Returns
  The server alias, or NULL if it is not set.

## purple_buddy_new()

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

  account | The account this buddy will get added to
  name | The name of the new buddy
  alias | The alias of the new buddy (or NULL if unaliased)

Returns
  A newly allocated buddy

See also
  purple_account_add_buddy
  purple_blist_add_buddy

## purple_buddy_set_icon()

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

  buddy | The buddy.
  icon | The buddy icon.

See also
  purple_buddy_icon_set_data()

## purple_buddy_set_media_caps()

void purple_buddy_set_media_caps | ( | PurpleBuddy * | buddy,
|  | PurpleMediaCaps | media_caps
| ) |  |

Sets the media caps for a buddy.

Parameters

  buddy | The PurpleBuddy.
  media_caps | The PurpleMediaCaps.

## purple_buddy_set_protocol_data()

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

  buddy | The buddy.
  data | The data.

See also
  purple_buddy_get_protocol_data()

Since
  2.6.0

## purple_chat_destroy()

void purple_chat_destroy | ( | PurpleChat * | chat | ) |

Destroys a chat.

Parameters

  chat | The chat to destroy

## purple_chat_get_account()

PurpleAccount* purple_chat_get_account | ( | PurpleChat * | chat | ) |

Returns the account the chat belongs to.

Parameters

  chat | The chat.

Returns
  The account the chat belongs to.

Since
  2.4.0

## purple_chat_get_components()

GHashTable* purple_chat_get_components | ( | PurpleChat * | chat | ) |

Get a hashtable containing information about a chat.

Parameters

  chat | The chat.

Note
  The return value of this function must not be modified or freed.

Returns
  The hashtable.

Since
  2.4.0

## purple_chat_get_group()

PurpleGroup* purple_chat_get_group | ( | PurpleChat * | chat | ) |

Returns the group of which the chat is a member.

Parameters

  chat | The chat.

Returns
  The parent group, or `NULL` if the chat is not in a group.

## purple_chat_get_name()

const char* purple_chat_get_name | ( | PurpleChat * | chat | ) |

Returns the correct name to display for a blist chat.

Parameters

  chat | The chat whose name will be returned.

Returns
  The alias (if set), or first component value.

## purple_chat_new()

PurpleChat* purple_chat_new | ( | PurpleAccount * | account,
|  | const char * | alias,
|  | GHashTable * | components
| ) |  |

Creates a new chat for the buddy list.

Parameters

  account | The account this chat will get added to
  alias | The alias of the new chat
  components | The 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

## purple_contact_destroy()

void purple_contact_destroy | ( | PurpleContact * | contact | ) |

Destroys a contact.

Parameters

  contact | The contact to destroy

## purple_contact_get_alias()

const char* purple_contact_get_alias | ( | PurpleContact * | contact | ) |

Gets the alias for a contact.

Parameters

  contact | The contact

Returns
  The alias, or NULL if it is not set.

## purple_contact_get_group()

PurpleGroup* purple_contact_get_group | ( | const PurpleContact * | contact | ) |

Gets the PurpleGroup from a PurpleContact.

Parameters

  contact | The contact

Returns
  The group

Since
  2.7.0

## purple_contact_get_priority_buddy()

PurpleBuddy* purple_contact_get_priority_buddy | ( | PurpleContact * | contact | ) |

Returns the highest priority buddy for a given contact.

Parameters

  contact | The contact

Returns
  The highest priority buddy

## purple_contact_invalidate_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

  contact | The contact

## purple_contact_new()

PurpleContact* purple_contact_new | ( | void |  | ) |

Creates a new contact.

Returns
  A new contact struct

## purple_contact_on_account()

gboolean purple_contact_on_account | ( | PurpleContact * | contact,
|  | PurpleAccount * | account
| ) |  |

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

Parameters

  contact | The contact to search through.
  account | The account.

Returns
  TRUE if there are any buddies from account in the contact, or FALSE otherwise.

## purple_contact_set_alias()

void purple_contact_set_alias | ( | PurpleContact * | contact,
|  | const char * | alias
| ) |  |

Sets the alias for a contact.

Parameters

  contact | The contact
  alias | The alias to set, or NULL to unset

Deprecated:
  Use purple_blist_alias_contact() instead.

## purple_find_buddies()

GSList* purple_find_buddies | ( | PurpleAccount * | account,
|  | const char * | name
| ) |  |

Finds all PurpleBuddy structs given a name and an account.

Parameters

  account | The account this buddy belongs to
  name | The 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

## purple_find_buddy()

PurpleBuddy* purple_find_buddy | ( | PurpleAccount * | account,
|  | const char * | name
| ) |  |

Finds the buddy struct given a name and an account.

Parameters

  account | The account this buddy belongs to
  name | The buddy's name

Returns
  The buddy or NULL if the buddy does not exist

## purple_find_buddy_in_group()

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

  account | The account this buddy belongs to
  name | The buddy's name
  group | The group to look in

Returns
  The buddy or NULL if the buddy does not exist in the group

## purple_find_group()

PurpleGroup* purple_find_group | ( | const char * | name | ) |

Finds a group by name.

Parameters

  name | The group's name

Returns
  The group or NULL if the group does not exist

## purple_get_blist()

PurpleBuddyList* purple_get_blist | ( | void |  | ) |

Returns the main buddy list.

Returns
  The main buddy list.

## purple_group_destroy()

void purple_group_destroy | ( | PurpleGroup * | group | ) |

Destroys a group.

Parameters

  group | The group to destroy

## purple_group_get_accounts()

GSList* purple_group_get_accounts | ( | PurpleGroup * | g | ) |

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

Parameters

  g | The group

Returns
  A GSList of accounts (which must be freed), or NULL if the group has no accounts.

## purple_group_get_name()

const char* purple_group_get_name | ( | PurpleGroup * | group | ) |

Returns the name of a group.

Parameters

  group | The group.

Returns
  The name of the group.

## purple_group_new()

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

  name | The name of the new group

Returns
  A new group struct

## purple_group_on_account()

gboolean purple_group_on_account | ( | PurpleGroup * | g,
|  | PurpleAccount * | account
| ) |  |

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

Parameters

  g | The group to search through.
  account | The account.

Returns
  TRUE if there are any buddies in the group, or FALSE otherwise.

## purple_set_blist()

void purple_set_blist | ( | PurpleBuddyList * | blist | ) |

Sets the main buddy list.

Parameters

  blist | The buddy list you want to use.

Deprecated:
  In 3.0.0, this will be handled by purple_blist_init()