buddyicon.h File Reference

Buddy Icon API. More...

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

Include dependency graph for buddyicon.h:

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

Go to the source code of this file.

Typedefs

typedef _PurpleBuddyIcon PurpleBuddyIcon

Functions

Buddy Icon API
PurpleAccountpurple_buddy_icon_get_account (const PurpleBuddyIcon *icon)
 Returns the buddy icon's account.
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.
const char * purple_buddy_icon_get_username (const PurpleBuddyIcon *icon)
 Returns the buddy icon's username.
PurpleBuddyIconpurple_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 populate it.
PurpleBuddyIconpurple_buddy_icon_ref (PurpleBuddyIcon *icon)
 Increments the reference count on a buddy icon.
void purple_buddy_icon_set_data (PurpleBuddyIcon *icon, guchar *data, size_t len, const char *checksum)
 Sets the buddy icon's data.
PurpleBuddyIconpurple_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.
Buddy Icon Helper API
void purple_buddy_icon_get_scale_size (PurpleBuddyIconSpec *spec, int *width, int *height)
 Gets display size for a buddy icon.
Buddy Icon Subsystem API
PurpleBuddyIconpurple_buddy_icons_find (PurpleAccount *account, const char *username)
 Returns the buddy icon information for a user.
PurpleStoredImagepurple_buddy_icons_find_account_icon (PurpleAccount *account)
 Returns the buddy icon image for an account.
PurpleStoredImagepurple_buddy_icons_find_custom_icon (PurpleContact *contact)
 Returns the custom buddy icon image for a contact.
time_t purple_buddy_icons_get_account_icon_timestamp (PurpleAccount *account)
 Returns the timestamp of when the icon was set.
const char * purple_buddy_icons_get_cache_dir (void)
 Returns the directory used to store buddy icon cache files.
const char * purple_buddy_icons_get_checksum_for_user (PurpleBuddy *buddy)
 Returns the checksum for the buddy icon of a specified buddy.
void * purple_buddy_icons_get_handle (void)
 Returns the buddy icon subsystem handle.
gboolean purple_buddy_icons_has_custom_icon (PurpleContact *contact)
 Returns a boolean indicating if a given contact has a custom buddy icon.
void purple_buddy_icons_init (void)
 Initializes the buddy icon subsystem.
gboolean purple_buddy_icons_is_caching (void)
 Returns whether or not buddy icon caching should be enabled.
PurpleStoredImagepurple_buddy_icons_set_account_icon (PurpleAccount *account, guchar *icon_data, size_t icon_len)
 Sets a buddy icon for an account.
void purple_buddy_icons_set_cache_dir (const char *cache_dir)
 Sets the directory used to store buddy icon cache files.
void purple_buddy_icons_set_caching (gboolean caching)
 Sets whether or not buddy icon caching is enabled.
PurpleStoredImagepurple_buddy_icons_set_custom_icon (PurpleContact *contact, guchar *icon_data, size_t icon_len)
 Sets a custom buddy icon for a 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.
void purple_buddy_icons_uninit (void)
 Uninitializes the buddy icon subsystem.


Detailed Description

Buddy Icon API.

purple

Purple is the legal property of its developers, whose names are too numerous to list here. Please refer to the COPYRIGHT file distributed with this source distribution.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Definition in file buddyicon.h.


Function Documentation

PurpleAccount* purple_buddy_icon_get_account ( const PurpleBuddyIcon icon  ) 

Returns the buddy icon's account.

Parameters:
icon The buddy icon.
Returns:
The account.

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.

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.

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.

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.

const char* purple_buddy_icon_get_username ( const PurpleBuddyIcon icon  ) 

Returns the buddy icon's username.

Parameters:
icon The buddy icon.
Returns:
The username.

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 populate 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.

PurpleBuddyIcon* purple_buddy_icon_ref ( PurpleBuddyIcon icon  ) 

Increments the reference count on a buddy icon.

Parameters:
icon The buddy icon.
Returns:
icon.

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.

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.

void purple_buddy_icon_update ( PurpleBuddyIcon icon  ) 

Updates every instance of this icon.

Parameters:
icon The buddy icon.

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.

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.

PurpleStoredImage* purple_buddy_icons_find_custom_icon ( PurpleContact contact  ) 

Returns the custom buddy icon image for a contact.

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:
contact The contact
Returns:
The custom buddy icon image.

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.

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.

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.

void* purple_buddy_icons_get_handle ( void   ) 

Returns the buddy icon subsystem handle.

Returns:
The subsystem handle.

gboolean purple_buddy_icons_has_custom_icon ( PurpleContact contact  ) 

Returns a boolean indicating if a given contact has a custom buddy icon.

Parameters:
contact The contact
Returns:
A boolean indicating if contact has a custom buddy icon.

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.

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.

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.

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.

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

Sets a custom buddy icon for a user.

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

Parameters:
contact The contact 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.

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.
Returns:
The buddy icon set, or NULL if no icon was set.