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: (transfer none): 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  * This function deals with loading the icon from the cache, if
 294  * needed, so it should be called in any case where you want the
 295  * appropriate icon.
 296  *
 297  * Returns: (transfer full): The account's buddy icon image.
 298  */
 299 PurpleImage *
 300 purple_buddy_icons_find_account_icon(PurpleAccount *account);
 301
 302 /**
 303  * purple_buddy_icons_set_account_icon:
 304  * @account:   The account for which to set a custom icon.
 305  * @icon_data: The image data of the icon, which the
 306  *                  buddy icon code will free.
 307  * @icon_len:  The length of the data in @icon_data.
 308  *
 309  * Sets a buddy icon for an account.
 310  *
 311  * This function will deal with saving a record of the icon,
 312  * caching the data, etc.
 313  *
 314  * Returns: (transfer none): The icon that was set.
 315  */
 316 PurpleImage *
 317 purple_buddy_icons_set_account_icon(PurpleAccount *account,
 318                                     guchar *icon_data, size_t icon_len);
 319
 320 /**
 321  * purple_buddy_icons_get_account_icon_timestamp:
 322  * @account: The account
 323  *
 324  * Returns the timestamp of when the icon was set.
 325  *
 326  * This is intended for use in protocols that require a timestamp for
 327  * buddy icon update reasons.
 328  *
 329  * Returns: The time the icon was set, or 0 if an error occurred.
 330  */
 331 time_t
 332 purple_buddy_icons_get_account_icon_timestamp(PurpleAccount *account);
 333
 334 /**
 335  * purple_buddy_icons_node_has_custom_icon:
 336  * @node: The blist node.
 337  *
 338  * Returns a boolean indicating if a given blist node has a custom buddy icon.
 339  *
 340  * Returns: A boolean indicating if @node has a custom buddy icon.
 341  */
 342 gboolean
 343 purple_buddy_icons_node_has_custom_icon(PurpleBlistNode *node);
 344
 345 /**
 346  * purple_buddy_icons_node_find_custom_icon:
 347  * @node: The node.
 348  *
 349  * Returns the custom buddy icon image for a blist node.
 350  *
 351  * This function deals with loading the icon from the cache, if
 352  * needed, so it should be called in any case where you want the
 353  * appropriate icon.
 354  *
 355  * Returns: (transfer full): The custom buddy icon.
 356  */
 357 PurpleImage *
 358 purple_buddy_icons_node_find_custom_icon(PurpleBlistNode *node);
 359
 360 /**
 361  * purple_buddy_icons_node_set_custom_icon:
 362  * @node:      The blist node for which to set a custom icon.
 363  * @icon_data: The image data of the icon, which the buddy icon code will
 364  *                  free. Use NULL to unset the icon.
 365  * @icon_len:  The length of the data in @icon_data.
 366  *
 367  * Sets a custom buddy icon for a blist node.
 368  *
 369  * This function will deal with saving a record of the icon, caching the data,
 370  * etc.
 371  *
 372  * Returns: (transfer none): The icon that was set.
 373  */
 374 PurpleImage *
 375 purple_buddy_icons_node_set_custom_icon(PurpleBlistNode *node,
 376                                         guchar *icon_data, size_t icon_len);
 377
 378 /**
 379  * purple_buddy_icons_node_set_custom_icon_from_file:
 380  * @node:      The blist node for which to set a custom icon.
 381  * @filename:  The path to the icon to set for the blist node. Use NULL
 382  *                  to unset the custom icon.
 383  *
 384  * Sets a custom buddy icon for a blist node.
 385  *
 386  * Convenience wrapper around purple_buddy_icons_node_set_custom_icon.
 387  * See purple_buddy_icons_node_set_custom_icon().
 388  *
 389  * Returns: (transfer none): The icon that was set.
 390  */
 391 PurpleImage *
 392 purple_buddy_icons_node_set_custom_icon_from_file(PurpleBlistNode *node,
 393                                                   const gchar *filename);
 394
 395 /**
 396  * purple_buddy_icons_set_caching:
 397  * @caching: TRUE if buddy icon caching should be enabled, or
 398  *                FALSE otherwise.
 399  *
 400  * Sets whether or not buddy icon caching is enabled.
 401  */
 402 void purple_buddy_icons_set_caching(gboolean caching);
 403
 404 /**
 405  * purple_buddy_icons_is_caching:
 406  *
 407  * Returns whether or not buddy icon caching should be enabled.
 408  *
 409  * The default is TRUE, unless otherwise specified by
 410  * purple_buddy_icons_set_caching().
 411  *
 412  * Returns: TRUE if buddy icon caching is enabled, or FALSE otherwise.
 413  */
 414 gboolean purple_buddy_icons_is_caching(void);
 415
 416 /**
 417  * purple_buddy_icons_set_cache_dir:
 418  * @cache_dir: The directory to store buddy icon cache files to.
 419  *
 420  * Sets the directory used to store buddy icon cache files.
 421  */
 422 void purple_buddy_icons_set_cache_dir(const char *cache_dir);
 423
 424 /**
 425  * purple_buddy_icons_get_cache_dir:
 426  *
 427  * Returns the directory used to store buddy icon cache files.
 428  *
 429  * The default directory is PURPLEDIR/icons, unless otherwise specified
 430  * by purple_buddy_icons_set_cache_dir().
 431  *
 432  * Returns: The directory to store buddy icon cache files to.
 433  */
 434 const char *purple_buddy_icons_get_cache_dir(void);
 435
 436 /**
 437  * purple_buddy_icons_get_handle:
 438  *
 439  * Returns the buddy icon subsystem handle.
 440  *
 441  * Returns: The subsystem handle.
 442  */
 443 void *purple_buddy_icons_get_handle(void);
 444
 445 /**
 446  * purple_buddy_icons_init:
 447  *
 448  * Initializes the buddy icon subsystem.
 449  */
 450 void purple_buddy_icons_init(void);
 451
 452 /**
 453  * purple_buddy_icons_uninit:
 454  *
 455  * Uninitializes the buddy icon subsystem.
 456  */
 457 void purple_buddy_icons_uninit(void);
 458
 459 /**************************************************************************/
 460 /* Buddy Icon Spec API                                                    */
 461 /**************************************************************************/
 462
 463 /**
 464  * purple_buddy_icon_spec_get_type:
 465  *
 466  * Returns: The #GType for the #PurpleBuddyIconSpec boxed structure.
 467  */
 468 GType purple_buddy_icon_spec_get_type(void);
 469
 470 /**
 471  * purple_buddy_icon_spec_new:
 472  * @format:        A comma-delimited list of image formats or %NULL if
 473  *                 icons are not supported
 474  * @min_width:     Minimum width of an icon
 475  * @min_height:    Minimum height of an icon
 476  * @max_width:     Maximum width of an icon
 477  * @max_height:    Maximum height of an icon
 478  * @max_filesize:  Maximum file size in bytes
 479  * @scale_rules:   How to stretch this icon
 480  *
 481  * Creates a new #PurpleBuddyIconSpec instance.
 482  *
 483  * Returns:  A new buddy icon spec.
 484  */
 485 PurpleBuddyIconSpec *purple_buddy_icon_spec_new(char *format, int min_width,
 486                 int min_height, int max_width, int max_height, size_t max_filesize,
 487                 PurpleBuddyIconScaleFlags scale_rules);
 488
 489 /**
 490  * purple_buddy_icon_spec_get_scaled_size:
 491  *
 492  * Gets display size for a buddy icon
 493  */
 494 void purple_buddy_icon_spec_get_scaled_size(PurpleBuddyIconSpec *spec,
 495                 int *width, int *height);
 496
 497 G_END_DECLS
 498
 499 #endif /* PURPLE_BUDDYICON_H */