Mercurial > pidgin.yaz
comparison libpurple/imgstore.h @ 16375:391a79778f89
Rework the buddy icon subsystem to use the imgstore subsystem, and modify the
imgstore subsystem to not require IDs for everything.
author | Richard Laager <rlaager@wiktel.com> |
---|---|
date | Tue, 24 Apr 2007 03:57:07 +0000 |
parents | 32c366eeeb99 |
children | 4fc51a87ce42 |
comparison
equal
deleted
inserted
replaced
16374:2a19bbc743ed | 16375:391a79778f89 |
---|---|
32 #ifdef __cplusplus | 32 #ifdef __cplusplus |
33 extern "C" { | 33 extern "C" { |
34 #endif | 34 #endif |
35 | 35 |
36 /** | 36 /** |
37 * Add an image to the store. The caller owns a reference | 37 * Add an image to the store. |
38 * to the image in the store, and must dereference the image | 38 * |
39 * with purple_imgstore_unref for it to be freed. | 39 * The caller owns a reference to the image in the store, and must dereference |
40 * the image with purple_imgstore_unref() for it to be freed. | |
41 * | |
42 * No ID is allocated when using this function. If you need to reference the | |
43 * image by an ID, use purple_imgstore_add_with_id() instead. | |
44 * | |
45 * @param data Pointer to the image data. | |
46 * @param size Image data's size. | |
47 * @param filename Filename associated with image. | |
48 * | |
49 * @return The stored image. | |
50 */ | |
51 PurpleStoredImage * | |
52 purple_imgstore_add(gconstpointer data, size_t size, const char *filename); | |
53 | |
54 /** | |
55 * Add an image to the store, allocating an ID. | |
56 * | |
57 * The caller owns a reference to the image in the store, and must dereference | |
58 * the image with purple_imgstore_unref_by_id() or purple_imgstore_unref() | |
59 * for it to be freed. | |
40 * | 60 * |
41 * @param data Pointer to the image data. | 61 * @param data Pointer to the image data. |
42 * @param size Image data's size. | 62 * @param size Image data's size. |
43 * @param filename Filename associated with image. | 63 * @param filename Filename associated with image. |
44 | 64 |
45 * @return ID for the image. | 65 * @return ID for the image. |
46 */ | 66 */ |
47 int purple_imgstore_add(const void *data, size_t size, const char *filename); | 67 int purple_imgstore_add_with_id(gconstpointer data, size_t size, const char *filename); |
48 | 68 |
49 /** | 69 /** |
50 * Retrieve an image from the store. The caller does not own a | 70 * Retrieve an image from the store. The caller does not own a |
51 * reference to the image. | 71 * reference to the image. |
52 * | 72 * |
53 * @param id The ID for the image. | 73 * @param id The ID for the image. |
54 * | 74 * |
55 * @return A pointer to the requested image, or NULL if it was not found. | 75 * @return A pointer to the requested image, or NULL if it was not found. |
56 */ | 76 */ |
57 PurpleStoredImage *purple_imgstore_get(int id); | 77 PurpleStoredImage *purple_imgstore_find_by_id(int id); |
58 | 78 |
59 /** | 79 /** |
60 * Retrieves a pointer to the image's data. | 80 * Retrieves a pointer to the image's data. |
61 * | 81 * |
62 * @param i The Image | 82 * @param img The Image |
63 * | 83 * |
64 * @return A pointer to the data, which must not | 84 * @return A pointer to the data, which must not |
65 * be freed or modified. | 85 * be freed or modified. |
66 */ | 86 */ |
67 gpointer purple_imgstore_get_data(PurpleStoredImage *i); | 87 gconstpointer purple_imgstore_get_data(PurpleStoredImage *img); |
68 | 88 |
69 /** | 89 /** |
70 * Retrieves the length of the image's data. | 90 * Retrieves the length of the image's data. |
71 * | 91 * |
72 * @param i The Image | 92 * @param img The Image |
73 * | 93 * |
74 * @return The size of the data that the pointer returned by | 94 * @return The size of the data that the pointer returned by |
75 * purple_imgstore_get_data points to. | 95 * purple_imgstore_get_data points to. |
76 */ | 96 */ |
77 size_t purple_imgstore_get_size(PurpleStoredImage *i); | 97 size_t purple_imgstore_get_size(PurpleStoredImage *i); |
78 | 98 |
79 /** | 99 /** |
80 * Retrieves a pointer to the image's filename. | 100 * Retrieves a pointer to the image's filename. |
81 * | 101 * |
82 * @param i The Image | 102 * @param img The image |
83 * | 103 * |
84 * @return A pointer to the filename, which must not | 104 * @return A pointer to the filename, which must not |
85 * be freed or modified. | 105 * be freed or modified. |
86 */ | 106 */ |
87 const char *purple_imgstore_get_filename(PurpleStoredImage *i); | 107 const char *purple_imgstore_get_filename(PurpleStoredImage *img); |
88 | 108 |
89 /** | 109 /** |
90 * Increment the reference count for an image in the store. The | 110 * Returns an extension corresponding to the image's file type. |
91 * image will be removed from the store when the reference count | 111 * |
92 * is zero. | 112 * @param img The image. |
113 * | |
114 * @return The icon's extension or "icon" if unknown. | |
115 */ | |
116 const char *purple_imgstore_get_extension(PurpleStoredImage *img); | |
117 | |
118 /** | |
119 * Increment the reference count. | |
120 * | |
121 * @param img The image. | |
122 * | |
123 * @return @a img | |
124 */ | |
125 PurpleStoredImage * | |
126 purple_imgstore_ref(PurpleStoredImage *img); | |
127 | |
128 /** | |
129 * Decrement the reference count. | |
130 * | |
131 * If the reference count reaches zero, the image will be freed. | |
132 * | |
133 * @param img The image. | |
134 * | |
135 * @return @a img or @c NULL if the reference count reached zero. | |
136 */ | |
137 PurpleStoredImage * | |
138 purple_imgstore_unref(PurpleStoredImage *img); | |
139 | |
140 /** | |
141 * Increment the reference count using an ID. | |
142 * | |
143 * This is a convience wrapper for purple_imgstore_find_by_id() and | |
144 * purple_imgstore_ref(), so if you have a PurpleStoredImage, it'll | |
145 * be more efficient to call purple_imgstore_ref() directly. | |
93 * | 146 * |
94 * @param id The ID for the image. | 147 * @param id The ID for the image. |
95 */ | 148 */ |
96 void purple_imgstore_ref(int id); | 149 void purple_imgstore_ref_by_id(int id); |
97 | 150 |
98 /** | 151 /** |
99 * Decrement the reference count for an image in the store. The | 152 * Decrement the reference count using an ID. |
100 * image will be removed from the store when the reference count | 153 * |
101 * is zero. | 154 * This is a convience wrapper for purple_imgstore_find_by_id() and |
155 * purple_imgstore_unref(), so if you have a PurpleStoredImage, it'll | |
156 * be more efficient to call purple_imgstore_unref() directly. | |
102 * | 157 * |
103 * @param id The ID for the image. | 158 * @param id The ID for the image. |
104 */ | 159 */ |
105 void purple_imgstore_unref(int id); | 160 void purple_imgstore_unref_by_id(int id); |
161 | |
162 /** | |
163 * Returns the image store subsystem handle. | |
164 * | |
165 * @return The subsystem handle. | |
166 */ | |
167 void *purple_imgstore_get_handle(void); | |
168 | |
169 /** | |
170 * Initializes the image store subsystem. | |
171 */ | |
172 void purple_imgstore_init(void); | |
173 | |
174 /** | |
175 * Uninitializes the image store subsystem. | |
176 */ | |
177 void purple_imgstore_uninit(void); | |
106 | 178 |
107 #ifdef __cplusplus | 179 #ifdef __cplusplus |
108 } | 180 } |
109 #endif | 181 #endif |
110 | 182 |