Buddy Icon API. More...

#include "account.h"
#include "blist.h"
#include "imgstore.h"
#include "prpl.h"
#include "util.h"

Include dependency graph for buddyicon.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef struct _PurpleBuddyIcon	PurpleBuddyIcon
	An opaque structure representing a buddy icon for a particular user on a particular PurpleAccount.

Functions
Buddy Icon API <br>
PurpleBuddyIcon *	purple_buddy_icon_new (PurpleAccount account, const char username, void icon_data, size_t icon_len, const char checksum)
	Creates a new buddy icon structure and populates it.

PurpleBuddyIcon *	purple_buddy_icon_ref (PurpleBuddyIcon *icon)
	Increments the reference count on a buddy icon.

PurpleBuddyIcon *	purple_buddy_icon_unref (PurpleBuddyIcon *icon)
	Decrements the reference count on a buddy icon.

void	purple_buddy_icon_update (PurpleBuddyIcon *icon)
	Updates every instance of this icon.

void	purple_buddy_icon_set_data (PurpleBuddyIcon icon, guchar data, size_t len, const char *checksum)
	Sets the buddy icon's data.

PurpleAccount *	purple_buddy_icon_get_account (const PurpleBuddyIcon *icon)
	Returns the buddy icon's account.

const char *	purple_buddy_icon_get_username (const PurpleBuddyIcon *icon)
	Returns the buddy icon's username.

const char *	purple_buddy_icon_get_checksum (const PurpleBuddyIcon *icon)
	Returns the buddy icon's checksum.

gconstpointer	purple_buddy_icon_get_data (const PurpleBuddyIcon icon, size_t len)
	Returns the buddy icon's data.

const char *	purple_buddy_icon_get_extension (const PurpleBuddyIcon *icon)
	Returns an extension corresponding to the buddy icon's file type.

char *	purple_buddy_icon_get_full_path (PurpleBuddyIcon *icon)
	Returns a full path to an icon.

Buddy Icon Subsystem API <br>
void	purple_buddy_icons_set_for_user (PurpleAccount account, const char username, void icon_data, size_t icon_len, const char checksum)
	Sets a buddy icon for a user.

const char *	purple_buddy_icons_get_checksum_for_user (PurpleBuddy *buddy)
	Returns the checksum for the buddy icon of a specified buddy.

PurpleBuddyIcon *	purple_buddy_icons_find (PurpleAccount account, const char username)
	Returns the buddy icon information for a user.

PurpleStoredImage *	purple_buddy_icons_find_account_icon (PurpleAccount *account)
	Returns the buddy icon image for an account.

PurpleStoredImage *	purple_buddy_icons_set_account_icon (PurpleAccount account, guchar icon_data, size_t icon_len)
	Sets a buddy icon for an account.

time_t	purple_buddy_icons_get_account_icon_timestamp (PurpleAccount *account)
	Returns the timestamp of when the icon was set.

gboolean	purple_buddy_icons_node_has_custom_icon (PurpleBlistNode *node)
	Returns a boolean indicating if a given blist node has a custom buddy icon.

PurpleStoredImage *	purple_buddy_icons_node_find_custom_icon (PurpleBlistNode *node)
	Returns the custom buddy icon image for a blist node.

PurpleStoredImage *	purple_buddy_icons_node_set_custom_icon (PurpleBlistNode node, guchar icon_data, size_t icon_len)
	Sets a custom buddy icon for a blist node.

PurpleStoredImage *	purple_buddy_icons_node_set_custom_icon_from_file (PurpleBlistNode node, const gchar filename)
	Sets a custom buddy icon for a blist node.

gboolean	purple_buddy_icons_has_custom_icon (PurpleContact *contact)
	PurpleContact version of purple_buddy_icons_node_has_custom_icon.

PurpleStoredImage *	purple_buddy_icons_find_custom_icon (PurpleContact *contact)
	PurpleContact version of purple_buddy_icons_node_find_custom_icon.

PurpleStoredImage *	purple_buddy_icons_set_custom_icon (PurpleContact contact, guchar icon_data, size_t icon_len)
	PurpleContact version of purple_buddy_icons_node_set_custom_icon.

void	purple_buddy_icons_set_caching (gboolean caching)
	Sets whether or not buddy icon caching is enabled.

gboolean	purple_buddy_icons_is_caching (void)
	Returns whether or not buddy icon caching should be enabled.

void	purple_buddy_icons_set_cache_dir (const char *cache_dir)
	Sets the directory used to store buddy icon cache files.

const char *	purple_buddy_icons_get_cache_dir (void)
	Returns the directory used to store buddy icon cache files.

void *	purple_buddy_icons_get_handle (void)
	Returns the buddy icon subsystem handle.

void	purple_buddy_icons_init (void)
	Initializes the buddy icon subsystem.

void	purple_buddy_icons_uninit (void)
	Uninitializes the buddy icon subsystem.

Buddy Icon Helper API <br>
void	purple_buddy_icon_get_scale_size (PurpleBuddyIconSpec spec, int width, int *height)
	Gets display size for a buddy icon.

Detailed Description

Buddy Icon API.

Definition in file buddyicon.h.

Typedef Documentation

◆ PurpleBuddyIcon

typedef struct _PurpleBuddyIcon PurpleBuddyIcon

An opaque structure representing a buddy icon for a particular user on a particular PurpleAccount.

Instances are reference-counted; use purple_buddy_icon_ref() and purple_buddy_icon_unref() to take and release references.

Definition at line 34 of file buddyicon.h.

Function Documentation

◆ purple_buddy_icon_get_account()

PurpleAccount * purple_buddy_icon_get_account ( const PurpleBuddyIcon * icon )

Returns the buddy icon's account.

Parameters

icon	The buddy icon.

Returns: The account.

◆ purple_buddy_icon_get_checksum()

const char * purple_buddy_icon_get_checksum ( const PurpleBuddyIcon * icon )

Returns the buddy icon's checksum.

This function is really only for prpl use.

Parameters

icon	The buddy icon.

Returns: The checksum.

◆ purple_buddy_icon_get_data()

gconstpointer purple_buddy_icon_get_data	(	const PurpleBuddyIcon *	icon,
		size_t *	len
	)

Returns the buddy icon's data.

Parameters

icon	The buddy icon.
len	If not `NULL`, the length of the icon data returned will be set in the location pointed to by this.

Returns: A pointer to the icon data.

◆ purple_buddy_icon_get_extension()

const char * purple_buddy_icon_get_extension ( const PurpleBuddyIcon * icon )

Returns an extension corresponding to the buddy icon's file type.

Parameters

icon	The buddy icon.

Returns: The icon's extension, "icon" if unknown, or NULL if the image data has disappeared.

◆ purple_buddy_icon_get_full_path()

char * purple_buddy_icon_get_full_path ( PurpleBuddyIcon * icon )

Returns a full path to an icon.

If the icon has data and the file exists in the cache, this will return a full path to the cache file.

In general, it is not appropriate to be poking in the icon cache directly. If you find yourself wanting to use this function, think very long and hard about it, and then don't.

Parameters

icon	The buddy icon

Returns: A full path to the file, or NULL under various conditions.

◆ purple_buddy_icon_get_username()

const char * purple_buddy_icon_get_username ( const PurpleBuddyIcon * icon )

Returns the buddy icon's username.

Parameters

icon	The buddy icon.

Returns: The username.

◆ purple_buddy_icon_new()

PurpleBuddyIcon * purple_buddy_icon_new	(	PurpleAccount *	account,
		const char *	username,
		void *	icon_data,
		size_t	icon_len,
		const char *	checksum
	)

Creates a new buddy icon structure and populates it.

If the buddy icon already exists, you'll get a reference to that structure, which will have been updated with the data supplied.

Parameters

account	The account the user is on.
username	The username the icon belongs to.
icon_data	The buddy icon data.
icon_len	The buddy icon length.
checksum	A protocol checksum from the prpl or `NULL`.

Returns: The buddy icon structure, with a reference for the caller.

◆ purple_buddy_icon_ref()

PurpleBuddyIcon * purple_buddy_icon_ref ( PurpleBuddyIcon * icon )

Increments the reference count on a buddy icon.

Parameters

icon	The buddy icon.

Returns: icon.

◆ purple_buddy_icon_set_data()

void purple_buddy_icon_set_data	(	PurpleBuddyIcon *	icon,
		guchar *	data,
		size_t	len,
		const char *	checksum
	)

Sets the buddy icon's data.

Parameters

icon	The buddy icon.
data	The buddy icon data, which the buddy icon code takes ownership of and will free.
len	The length of the data in data.
checksum	A protocol checksum from the prpl or `NULL`.

◆ purple_buddy_icon_unref()

PurpleBuddyIcon * purple_buddy_icon_unref ( PurpleBuddyIcon * icon )

Decrements the reference count on a buddy icon.

If the reference count reaches 0, the icon will be destroyed.

Parameters

icon	The buddy icon.

Returns: icon, or NULL if the reference count reached 0.

◆ purple_buddy_icon_update()

void purple_buddy_icon_update ( PurpleBuddyIcon * icon )

Updates every instance of this icon.

Parameters

icon	The buddy icon.

◆ purple_buddy_icons_find()

PurpleBuddyIcon * purple_buddy_icons_find	(	PurpleAccount *	account,
		const char *	username
	)

Returns the buddy icon information for a user.

Parameters

account	The account the user is on.
username	The username of the user.

Returns: The icon (with a reference for the caller) if found, or NULL if not found.

◆ purple_buddy_icons_find_account_icon()

PurpleStoredImage * purple_buddy_icons_find_account_icon ( PurpleAccount * account )

Returns the buddy icon image for an account.

The caller owns a reference to the image in the store, and must dereference the image with purple_imgstore_unref() for it to be freed.

This function deals with loading the icon from the cache, if needed, so it should be called in any case where you want the appropriate icon.

Parameters

account The account

Returns: The account's buddy icon image.

◆ purple_buddy_icons_find_custom_icon()

PurpleStoredImage * purple_buddy_icons_find_custom_icon ( PurpleContact * contact )

PurpleContact version of purple_buddy_icons_node_find_custom_icon.

Returns the custom buddy icon image for a blist node.

The caller owns a reference to the image in the store, and must dereference the image with purple_imgstore_unref() for it to be freed.

This function deals with loading the icon from the cache, if needed, so it should be called in any case where you want the appropriate icon.

Parameters

node The node.

Returns: The custom buddy icon.

Since: 2.5.0

Deprecated:: Use purple_buddy_icons_node_find_custom_icon instead.

◆ purple_buddy_icons_get_account_icon_timestamp()

time_t purple_buddy_icons_get_account_icon_timestamp ( PurpleAccount * account )

Returns the timestamp of when the icon was set.

This is intended for use in protocols that require a timestamp for buddy icon update reasons.

Parameters

account The account

Returns: The time the icon was set, or 0 if an error occurred.

◆ purple_buddy_icons_get_cache_dir()

const char * purple_buddy_icons_get_cache_dir ( void )

Returns the directory used to store buddy icon cache files.

The default directory is PURPLEDIR/icons, unless otherwise specified by purple_buddy_icons_set_cache_dir().

Returns: The directory to store buddy icon cache files to.

◆ purple_buddy_icons_get_checksum_for_user()

const char * purple_buddy_icons_get_checksum_for_user ( PurpleBuddy * buddy )

Returns the checksum for the buddy icon of a specified buddy.

This avoids loading the icon image data from the cache if it's not already loaded for some other reason.

Parameters

buddy The buddy

Returns: The checksum.

◆ purple_buddy_icons_get_handle()

void * purple_buddy_icons_get_handle ( void )

Returns the buddy icon subsystem handle.

Returns: The subsystem handle.

◆ purple_buddy_icons_has_custom_icon()

gboolean purple_buddy_icons_has_custom_icon ( PurpleContact * contact )

PurpleContact version of purple_buddy_icons_node_has_custom_icon.

Returns a boolean indicating if a given blist node has a custom buddy icon.

Parameters

node	The blist node.

Returns: A boolean indicating if node has a custom buddy icon.

Since: 2.5.0

Deprecated:: Use purple_buddy_icons_node_has_custom_icon instead.

◆ purple_buddy_icons_is_caching()

gboolean purple_buddy_icons_is_caching ( void )

Returns whether or not buddy icon caching should be enabled.

The default is TRUE, unless otherwise specified by purple_buddy_icons_set_caching().

Returns: TRUE if buddy icon caching is enabled, or FALSE otherwise.

◆ purple_buddy_icons_node_find_custom_icon()

PurpleStoredImage * purple_buddy_icons_node_find_custom_icon ( PurpleBlistNode * node )

Returns the custom buddy icon image for a blist node.

The caller owns a reference to the image in the store, and must dereference the image with purple_imgstore_unref() for it to be freed.

This function deals with loading the icon from the cache, if needed, so it should be called in any case where you want the appropriate icon.

Parameters

node The node.

Returns: The custom buddy icon.

Since: 2.5.0

◆ purple_buddy_icons_node_has_custom_icon()

gboolean purple_buddy_icons_node_has_custom_icon ( PurpleBlistNode * node )

Returns a boolean indicating if a given blist node has a custom buddy icon.

Parameters

node	The blist node.

Returns: A boolean indicating if node has a custom buddy icon.

Since: 2.5.0

◆ purple_buddy_icons_node_set_custom_icon()

PurpleStoredImage * purple_buddy_icons_node_set_custom_icon	(	PurpleBlistNode *	node,
		guchar *	icon_data,
		size_t	icon_len
	)

Sets a custom buddy icon for a blist node.

This function will deal with saving a record of the icon, caching the data, etc.

Parameters

node	The blist node for which to set a custom icon.
icon_data	The image data of the icon, which the buddy icon code will free. Use NULL to unset the icon.
icon_len	The length of the data in icon_data.

Returns: The icon that was set. The caller does NOT own a reference to this, and must call purple_imgstore_ref() if it wants one.

Since: 2.5.0

◆ purple_buddy_icons_node_set_custom_icon_from_file()

PurpleStoredImage * purple_buddy_icons_node_set_custom_icon_from_file	(	PurpleBlistNode *	node,
		const gchar *	filename
	)

Sets a custom buddy icon for a blist node.

Convenience wrapper around purple_buddy_icons_node_set_custom_icon.

See also: purple_buddy_icons_node_set_custom_icon()

Parameters

node	The blist node for which to set a custom icon.
filename	The path to the icon to set for the blist node. Use NULL to unset the custom icon.

Returns: The icon that was set. The caller does NOT own a reference to this, and must call purple_imgstore_ref() if it wants one.

Since: 2.5.0

◆ purple_buddy_icons_set_account_icon()

PurpleStoredImage * purple_buddy_icons_set_account_icon	(	PurpleAccount *	account,
		guchar *	icon_data,
		size_t	icon_len
	)

Sets a buddy icon for an account.

This function will deal with saving a record of the icon, caching the data, etc.

Parameters

account	The account for which to set a custom icon.
icon_data	The image data of the icon, which the buddy icon code will free.
icon_len	The length of the data in icon_data.

Returns: The icon that was set. The caller does NOT own a reference to this, and must call purple_imgstore_ref() if it wants one.

◆ purple_buddy_icons_set_cache_dir()

void purple_buddy_icons_set_cache_dir ( const char * cache_dir )

Sets the directory used to store buddy icon cache files.

Parameters

cache_dir The directory to store buddy icon cache files to.

◆ purple_buddy_icons_set_caching()

void purple_buddy_icons_set_caching ( gboolean caching )

Sets whether or not buddy icon caching is enabled.

Parameters

caching TRUE of buddy icon caching should be enabled, or FALSE otherwise.

◆ purple_buddy_icons_set_custom_icon()

PurpleStoredImage * purple_buddy_icons_set_custom_icon	(	PurpleContact *	contact,
		guchar *	icon_data,
		size_t	icon_len
	)

PurpleContact version of purple_buddy_icons_node_set_custom_icon.

Sets a custom buddy icon for a blist node.

This function will deal with saving a record of the icon, caching the data, etc.

Parameters

node	The blist node for which to set a custom icon.
icon_data	The image data of the icon, which the buddy icon code will free. Use NULL to unset the icon.
icon_len	The length of the data in icon_data.

Returns: The icon that was set. The caller does NOT own a reference to this, and must call purple_imgstore_ref() if it wants one.

Since: 2.5.0

Deprecated:: Use purple_buddy_icons_node_set_custom_icon instead.

◆ purple_buddy_icons_set_for_user()

void purple_buddy_icons_set_for_user	(	PurpleAccount *	account,
		const char *	username,
		void *	icon_data,
		size_t	icon_len,
		const char *	checksum
	)

Sets a buddy icon for a user.

Parameters

account	The account the user is on.
username	The username of the user.
icon_data	The buddy icon data, which the buddy icon code takes ownership of and will free.
icon_len	The length of the icon data.
checksum	A protocol checksum from the prpl or `NULL`.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ PurpleBuddyIcon

Function Documentation

◆ purple_buddy_icon_get_account()

◆ purple_buddy_icon_get_checksum()

◆ purple_buddy_icon_get_data()

◆ purple_buddy_icon_get_extension()

◆ purple_buddy_icon_get_full_path()

◆ purple_buddy_icon_get_username()

◆ purple_buddy_icon_new()

◆ purple_buddy_icon_ref()

◆ purple_buddy_icon_set_data()

◆ purple_buddy_icon_unref()

◆ purple_buddy_icon_update()

◆ purple_buddy_icons_find()

◆ purple_buddy_icons_find_account_icon()

◆ purple_buddy_icons_find_custom_icon()

◆ purple_buddy_icons_get_account_icon_timestamp()

◆ purple_buddy_icons_get_cache_dir()

◆ purple_buddy_icons_get_checksum_for_user()

◆ purple_buddy_icons_get_handle()

◆ purple_buddy_icons_has_custom_icon()

◆ purple_buddy_icons_is_caching()

◆ purple_buddy_icons_node_find_custom_icon()

◆ purple_buddy_icons_node_has_custom_icon()

◆ purple_buddy_icons_node_set_custom_icon()

◆ purple_buddy_icons_node_set_custom_icon_from_file()

◆ purple_buddy_icons_set_account_icon()

◆ purple_buddy_icons_set_cache_dir()

◆ purple_buddy_icons_set_caching()

◆ purple_buddy_icons_set_custom_icon()

◆ purple_buddy_icons_set_for_user()