Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/buddyicon.h
branchadium-1.5.11
changeset 6014 fcb71cb71a3d
parent 5941 307f53385811
parent 6013 f8d0dc659e3f
child 6016 325e2ab3406f
equal deleted inserted replaced
5941:307f53385811 6014:fcb71cb71a3d
     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_ */