home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / buddyicon.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  11.0 KB  |  384 lines
  1. /**
  2.  * @file buddyicon.h Buddy Icon API
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _PURPLE_BUDDYICON_H_
  26. #define _PURPLE_BUDDYICON_H_
  27.  
  28. typedef struct _PurpleBuddyIcon PurpleBuddyIcon;
  29.  
  30. #include "account.h"
  31. #include "blist.h"
  32. #include "imgstore.h"
  33. #include "prpl.h"
  34.  
  35. #ifdef __cplusplus
  36. extern "C" {
  37. #endif
  38.  
  39.  
  40. /**************************************************************************/
  41. /** @name Buddy Icon API                                                  */
  42. /**************************************************************************/
  43. /*@{*/
  44.  
  45. /**
  46.  * Creates a new buddy icon structure and populate it.
  47.  *
  48.  * If the buddy icon already exists, you'll get a reference to that structure,
  49.  * which will have been updated with the data supplied.
  50.  *
  51.  * @param account   The account the user is on.
  52.  * @param username  The username the icon belongs to.
  53.  * @param icon_data The buddy icon data.
  54.  * @param icon_len  The buddy icon length.
  55.  * @param checksum  A protocol checksum from the prpl or @c NULL.
  56.  *
  57.  * @return The buddy icon structure, with a reference for the caller.
  58.  */
  59. PurpleBuddyIcon *purple_buddy_icon_new(PurpleAccount *account, const char *username,
  60.                                        void *icon_data, size_t icon_len,
  61.                                        const char *checksum);
  62.  
  63. /**
  64.  * Increments the reference count on a buddy icon.
  65.  *
  66.  * @param icon The buddy icon.
  67.  *
  68.  * @return @a icon.
  69.  */
  70. PurpleBuddyIcon *purple_buddy_icon_ref(PurpleBuddyIcon *icon);
  71.  
  72. /**
  73.  * Decrements the reference count on a buddy icon.
  74.  *
  75.  * If the reference count reaches 0, the icon will be destroyed.
  76.  *
  77.  * @param icon The buddy icon.
  78.  *
  79.  * @return @a icon, or @c NULL if the reference count reached 0.
  80.  */
  81. PurpleBuddyIcon *purple_buddy_icon_unref(PurpleBuddyIcon *icon);
  82.  
  83. /**
  84.  * Updates every instance of this icon.
  85.  *
  86.  * @param icon The buddy icon.
  87.  */
  88. void purple_buddy_icon_update(PurpleBuddyIcon *icon);
  89.  
  90. /**
  91.  * Sets the buddy icon's data.
  92.  *
  93.  * @param icon The buddy icon.
  94.  * @param data The buddy icon data, which the buddy icon code
  95.  *             takes ownership of and will free.
  96.  * @param len  The length of the data in @a data.
  97.  * @param checksum  A protocol checksum from the prpl or @c NULL.
  98.  */
  99. void
  100. purple_buddy_icon_set_data(PurpleBuddyIcon *icon, guchar *data,
  101.                            size_t len, const char *checksum);
  102.  
  103. /**
  104.  * Returns the buddy icon's account.
  105.  *
  106.  * @param icon The buddy icon.
  107.  *
  108.  * @return The account.
  109.  */
  110. PurpleAccount *purple_buddy_icon_get_account(const PurpleBuddyIcon *icon);
  111.  
  112. /**
  113.  * Returns the buddy icon's username.
  114.  *
  115.  * @param icon The buddy icon.
  116.  *
  117.  * @return The username.
  118.  */
  119. const char *purple_buddy_icon_get_username(const PurpleBuddyIcon *icon);
  120.  
  121. /**
  122.  * Returns the buddy icon's checksum.
  123.  *
  124.  * This function is really only for prpl use.
  125.  *
  126.  * @param icon The buddy icon.
  127.  *
  128.  * @return The checksum.
  129.  */
  130. const char *purple_buddy_icon_get_checksum(const PurpleBuddyIcon *icon);
  131.  
  132. /**
  133.  * Returns the buddy icon's data.
  134.  *
  135.  * @param icon The buddy icon.
  136.  * @param len  If not @c NULL, the length of the icon data returned will be
  137.  *             set in the location pointed to by this.
  138.  *
  139.  * @return A pointer to the icon data.
  140.  */
  141. gconstpointer purple_buddy_icon_get_data(const PurpleBuddyIcon *icon, size_t *len);
  142.  
  143. /**
  144.  * Returns an extension corresponding to the buddy icon's file type.
  145.  *
  146.  * @param icon The buddy icon.
  147.  *
  148.  * @return The icon's extension, "icon" if unknown, or @c NULL if
  149.  *         the image data has disappeared.
  150.  */
  151. const char *purple_buddy_icon_get_extension(const PurpleBuddyIcon *icon);
  152.  
  153. /**
  154.  * Returns a full path to an icon.
  155.  *
  156.  * If the icon has data and the file exists in the cache, this will return
  157.  * a full path to the cache file.
  158.  *
  159.  * In general, it is not appropriate to be poking in the icon cache
  160.  * directly.  If you find yourself wanting to use this function, think
  161.  * very long and hard about it, and then don't.
  162.  *
  163.  * @param icon The buddy icon
  164.  *
  165.  * @return A full path to the file, or @c NULL under various conditions.
  166.  */
  167. char *purple_buddy_icon_get_full_path(PurpleBuddyIcon *icon);
  168.  
  169. /*@}*/
  170.  
  171. /**************************************************************************/
  172. /** @name Buddy Icon Subsystem API                                        */
  173. /**************************************************************************/
  174. /*@{*/
  175.  
  176. /**
  177.  * Sets a buddy icon for a user.
  178.  *
  179.  * @param account   The account the user is on.
  180.  * @param username  The username of the user.
  181.  * @param icon_data The buddy icon data, which the buddy icon code
  182.  *                  takes ownership of and will free.
  183.  * @param icon_len  The length of the icon data.
  184.  * @param checksum  A protocol checksum from the prpl or @c NULL.
  185.  *
  186.  * @return The buddy icon set, or NULL if no icon was set.
  187.  */
  188. void
  189. purple_buddy_icons_set_for_user(PurpleAccount *account, const char *username,
  190.                                 void *icon_data, size_t icon_len,
  191.                                 const char *checksum);
  192.  
  193. /**
  194.  * Returns the checksum for the buddy icon of a specified buddy.
  195.  *
  196.  * This avoids loading the icon image data from the cache if it's
  197.  * not already loaded for some other reason.
  198.  *
  199.  * @param buddy The buddy
  200.  *
  201.  * @return The checksum.
  202.  */
  203. const char *
  204. purple_buddy_icons_get_checksum_for_user(PurpleBuddy *buddy);
  205.  
  206. /**
  207.  * Returns the buddy icon information for a user.
  208.  *
  209.  * @param account  The account the user is on.
  210.  * @param username The username of the user.
  211.  *
  212.  * @return The icon (with a reference for the caller) if found, or @c NULL if
  213.  *         not found.
  214.  */
  215. PurpleBuddyIcon *
  216. purple_buddy_icons_find(PurpleAccount *account, const char *username);
  217.  
  218. /**
  219.  * Returns a boolean indicating if a given contact has a custom buddy icon.
  220.  *
  221.  * @param contact The contact
  222.  *
  223.  * @return A boolean indicating if @a contact has a custom buddy icon.
  224.  */
  225. gboolean
  226. purple_buddy_icons_has_custom_icon(PurpleContact *contact);
  227.  
  228. /**
  229.  * Returns the buddy icon image for an account.
  230.  *
  231.  * The caller owns a reference to the image in the store, and must dereference
  232.  * the image with purple_imgstore_unref() for it to be freed.
  233.  *
  234.  * This function deals with loading the icon from the cache, if
  235.  * needed, so it should be called in any case where you want the
  236.  * appropriate icon.
  237.  *
  238.  * @param account The account
  239.  *
  240.  * @return The account's buddy icon image.
  241.  */
  242. PurpleStoredImage *
  243. purple_buddy_icons_find_account_icon(PurpleAccount *account);
  244.  
  245. /**
  246.  * Sets a buddy icon for an account.
  247.  *
  248.  * This function will deal with saving a record of the icon,
  249.  * caching the data, etc.
  250.  *
  251.  * @param account   The account for which to set a custom icon.
  252.  * @param icon_data The image data of the icon, which the
  253.  *                  buddy icon code will free.
  254.  * @param icon_len  The length of the data in @a icon_data.
  255.  *
  256.  * @return The icon that was set.  The caller does NOT own
  257.  *         a reference to this, and must call purple_imgstore_ref()
  258.  *         if it wants one.
  259.  */
  260. PurpleStoredImage *
  261. purple_buddy_icons_set_account_icon(PurpleAccount *account,
  262.                                     guchar *icon_data, size_t icon_len);
  263.  
  264. /**
  265.  * Returns the timestamp of when the icon was set.
  266.  *
  267.  * This is intended for use in protocols that require a timestamp for
  268.  * buddy icon update reasons.
  269.  *
  270.  * @param account The account
  271.  *
  272.  * @return The time the icon was set, or 0 if an error occurred.
  273.  */
  274. time_t
  275. purple_buddy_icons_get_account_icon_timestamp(PurpleAccount *account);
  276.  
  277. /**
  278.  * Returns the custom buddy icon image for a contact.
  279.  *
  280.  * The caller owns a reference to the image in the store, and must dereference
  281.  * the image with purple_imgstore_unref() for it to be freed.
  282.  *
  283.  * This function deals with loading the icon from the cache, if
  284.  * needed, so it should be called in any case where you want the
  285.  * appropriate icon.
  286.  *
  287.  * @param contact The contact
  288.  *
  289.  * @return The custom buddy icon image.
  290.  */
  291. PurpleStoredImage *
  292. purple_buddy_icons_find_custom_icon(PurpleContact *contact);
  293.  
  294. /**
  295.  * Sets a custom buddy icon for a user.
  296.  *
  297.  * This function will deal with saving a record of the icon,
  298.  * caching the data, etc.
  299.  *
  300.  * @param contact   The contact for which to set a custom icon.
  301.  * @param icon_data The image data of the icon, which the
  302.  *                  buddy icon code will free.
  303.  * @param icon_len  The length of the data in @a icon_data.
  304.  *
  305.  * @return The icon that was set.  The caller does NOT own
  306.  *         a reference to this, and must call purple_imgstore_ref()
  307.  *         if it wants one.
  308.  */
  309. PurpleStoredImage *
  310. purple_buddy_icons_set_custom_icon(PurpleContact *contact,
  311.                                    guchar *icon_data, size_t icon_len);
  312.  
  313. /**
  314.  * Sets whether or not buddy icon caching is enabled.
  315.  *
  316.  * @param caching TRUE of buddy icon caching should be enabled, or
  317.  *                FALSE otherwise.
  318.  */
  319. void purple_buddy_icons_set_caching(gboolean caching);
  320.  
  321. /**
  322.  * Returns whether or not buddy icon caching should be enabled.
  323.  *
  324.  * The default is TRUE, unless otherwise specified by
  325.  * purple_buddy_icons_set_caching().
  326.  *
  327.  * @return TRUE if buddy icon caching is enabled, or FALSE otherwise.
  328.  */
  329. gboolean purple_buddy_icons_is_caching(void);
  330.  
  331. /**
  332.  * Sets the directory used to store buddy icon cache files.
  333.  *
  334.  * @param cache_dir The directory to store buddy icon cache files to.
  335.  */
  336. void purple_buddy_icons_set_cache_dir(const char *cache_dir);
  337.  
  338. /**
  339.  * Returns the directory used to store buddy icon cache files.
  340.  *
  341.  * The default directory is PURPLEDIR/icons, unless otherwise specified
  342.  * by purple_buddy_icons_set_cache_dir().
  343.  *
  344.  * @return The directory to store buddy icon cache files to.
  345.  */
  346. const char *purple_buddy_icons_get_cache_dir(void);
  347.  
  348. /**
  349.  * Returns the buddy icon subsystem handle.
  350.  *
  351.  * @return The subsystem handle.
  352.  */
  353. void *purple_buddy_icons_get_handle(void);
  354.  
  355. /**
  356.  * Initializes the buddy icon subsystem.
  357.  */
  358. void purple_buddy_icons_init(void);
  359.  
  360. /**
  361.  * Uninitializes the buddy icon subsystem.
  362.  */
  363. void purple_buddy_icons_uninit(void);
  364.  
  365. /*@}*/
  366.  
  367. /**************************************************************************/
  368. /** @name Buddy Icon Helper API                                           */
  369. /**************************************************************************/
  370. /*@{*/
  371.  
  372. /**
  373.  * Gets display size for a buddy icon
  374.  */
  375. void purple_buddy_icon_get_scale_size(PurpleBuddyIconSpec *spec, int *width, int *height);
  376.  
  377. /*@}*/
  378.  
  379. #ifdef __cplusplus
  380. }
  381. #endif
  382.  
  383. #endif /* _PURPLE_BUDDYICON_H_ */
  384.