libpurple/imgstore.h

   1 /**
   2  * @file imgstore.h IM Image Store API
   3  * @ingroup core
   4  * @see @ref imgstore-signals
   5  */
   6
   7 /* purple
   8  *
   9  * Purple is the legal property of its developers, whose names are too numerous
  10  * to list here.  Please refer to the COPYRIGHT file distributed with this
  11  * source distribution.
  12  *
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with this program; if not, write to the Free Software
  25  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  26  */
  27 #ifndef _PURPLE_IMGSTORE_H_
  28 #define _PURPLE_IMGSTORE_H_
  29
  30 #include <glib.h>
  31
  32 /** A reference-counted immutable wrapper around an image's data and its
  33  *  filename.
  34  */
  35 typedef struct _PurpleStoredImage PurpleStoredImage;
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /**
  42  * Add an image to the store.
  43  *
  44  * The caller owns a reference to the image in the store, and must dereference
  45  * the image with purple_imgstore_unref() for it to be freed.
  46  *
  47  * No ID is allocated when using this function.  If you need to reference the
  48  * image by an ID, use purple_imgstore_add_with_id() instead.
  49  *
  50  * @param data          Pointer to the image data, which the imgstore will take
  51  *                      ownership of and free as appropriate.  If you want a
  52  *                      copy of the data, make it before calling this function.
  53  * @param size          Image data's size.
  54  * @param filename      Filename associated with image.  This is for your
  55  *                  convenience.  It could be the full path to the
  56  *                  image or, more commonly, the filename of the image
  57  *                  without any directory information.  It can also be
  58  *                  NULL, if you don't need to keep track of a filename.
  59  *
  60  * @return The stored image.
  61  */
  62 PurpleStoredImage *
  63 purple_imgstore_add(gpointer data, size_t size, const char *filename);
  64
  65 /**
  66  * Create an image and add it to the store.
  67  *
  68  * @param path  The path to the image.
  69  *
  70  * @return  The stored image.
  71  * @since 2.X.X
  72  */
  73 PurpleStoredImage *
  74 purple_imgstore_new_from_file(const char *path);
  75
  76 /**
  77  * Add an image to the store, allocating an ID.
  78  *
  79  * The caller owns a reference to the image in the store, and must dereference
  80  * the image with purple_imgstore_unref_by_id() or purple_imgstore_unref()
  81  * for it to be freed.
  82  *
  83  * @param data          Pointer to the image data, which the imgstore will take
  84  *                      ownership of and free as appropriate.  If you want a
  85  *                      copy of the data, make it before calling this function.
  86  * @param size          Image data's size.
  87  * @param filename      Filename associated with image.  This is for your
  88  *                  convenience.  It could be the full path to the
  89  *                  image or, more commonly, the filename of the image
  90  *                  without any directory information.  It can also be
  91  *                  NULL, if you don't need to keep track of a filename.
  92
  93  * @return ID for the image.  This is a unique number that can be used
  94  *         within libpurple to reference the image.
  95  */
  96 int purple_imgstore_add_with_id(gpointer data, size_t size, const char *filename);
  97
  98 /**
  99  * Retrieve an image from the store. The caller does not own a
 100  * reference to the image.
 101  *
 102  * @param id            The ID for the image.
 103  *
 104  * @return A pointer to the requested image, or NULL if it was not found.
 105  */
 106 PurpleStoredImage *purple_imgstore_find_by_id(int id);
 107
 108 /**
 109  * Retrieves a pointer to the image's data.
 110  *
 111  * @param img   The Image
 112  *
 113  * @return A pointer to the data, which must not
 114  *         be freed or modified.
 115  */
 116 gconstpointer purple_imgstore_get_data(PurpleStoredImage *img);
 117
 118 /**
 119  * Retrieves the length of the image's data.
 120  *
 121  * @param img   The Image
 122  *
 123  * @return The size of the data that the pointer returned by
 124  *         purple_imgstore_get_data points to.
 125  */
 126 size_t purple_imgstore_get_size(PurpleStoredImage *img);
 127
 128 /**
 129  * Retrieves a pointer to the image's filename.
 130  *
 131  * @param img   The image
 132  *
 133  * @return A pointer to the filename, which must not
 134  *         be freed or modified.
 135  */
 136 const char *purple_imgstore_get_filename(const PurpleStoredImage *img);
 137
 138 /**
 139  * Looks at the magic numbers of the image data (the first few bytes)
 140  * and returns an extension corresponding to the image's file type.
 141  *
 142  * @param img  The image.
 143  *
 144  * @return The image's extension (for example "png") or "icon"
 145  *         if unknown.
 146  */
 147 const char *purple_imgstore_get_extension(PurpleStoredImage *img);
 148
 149 /**
 150  * Increment the reference count.
 151  *
 152  * @param img The image.
 153  *
 154  * @return @a img
 155  */
 156 PurpleStoredImage *
 157 purple_imgstore_ref(PurpleStoredImage *img);
 158
 159 /**
 160  * Decrement the reference count.
 161  *
 162  * If the reference count reaches zero, the image will be freed.
 163  *
 164  * @param img The image.
 165  *
 166  * @return @a img or @c NULL if the reference count reached zero.
 167  */
 168 PurpleStoredImage *
 169 purple_imgstore_unref(PurpleStoredImage *img);
 170
 171 /**
 172  * Increment the reference count using an ID.
 173  *
 174  * This is a convience wrapper for purple_imgstore_find_by_id() and
 175  * purple_imgstore_ref(), so if you have a PurpleStoredImage, it'll
 176  * be more efficient to call purple_imgstore_ref() directly.
 177  *
 178  * @param id            The ID for the image.
 179  */
 180 void purple_imgstore_ref_by_id(int id);
 181
 182 /**
 183  * Decrement the reference count using an ID.
 184  *
 185  * This is a convience wrapper for purple_imgstore_find_by_id() and
 186  * purple_imgstore_unref(), so if you have a PurpleStoredImage, it'll
 187  * be more efficient to call purple_imgstore_unref() directly.
 188  *
 189  * @param id            The ID for the image.
 190  */
 191 void purple_imgstore_unref_by_id(int id);
 192
 193 /**
 194  * Returns the image store subsystem handle.
 195  *
 196  * @return The subsystem handle.
 197  */
 198 void *purple_imgstore_get_handle(void);
 199
 200 /**
 201  * Initializes the image store subsystem.
 202  */
 203 void purple_imgstore_init(void);
 204
 205 /**
 206  * Uninitializes the image store subsystem.
 207  */
 208 void purple_imgstore_uninit(void);
 209
 210 #ifdef __cplusplus
 211 }
 212 #endif
 213
 214 #endif /* _PURPLE_IMGSTORE_H_ */