libpurple/buddyicon.h

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