libpurple/buddyicon.h

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