Mercurial > pidgin.yaz
comparison libpurple/smiley.h @ 22874:02eda4bd2b22
Apply the custom smiley patches from #1187, from Jorge Villaseo (Masca) and
Mauro Srgio Ferreira Brasil.
I have not applied the bits on MSN yet. I will have to look at it later, but
I would rather someone else more familiar with the MSN code look at it first.
I changed some bits of the applied patch (whitespacing, camelcasing etc.), and
the bit that required a major version bump (in gtkthemes.h). There are a few
more things that need to be done for this to be merged back to i.p.p.
author | Sadrul Habib Chowdhury <imadil@gmail.com> |
---|---|
date | Tue, 19 Feb 2008 19:41:56 +0000 |
parents | |
children | 2ab289f312d0 |
comparison
equal
deleted
inserted
replaced
22310:f463d54e606b | 22874:02eda4bd2b22 |
---|---|
1 /** | |
2 * @file Smiley.h Smiley 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 */ | |
27 | |
28 #ifndef _PURPLE_SMILEY_H_ | |
29 #define _PURPLE_SMILEY_H_ | |
30 | |
31 #include "imgstore.h" | |
32 #include "util.h" | |
33 | |
34 /** | |
35 * A custom smiley. | |
36 * This contains everything Purple will ever need to know about a custom smiley. | |
37 * Everything. | |
38 */ | |
39 typedef struct _PurpleSmiley { | |
40 PurpleStoredImage *img; /**< The id of the stored image with the | |
41 the smiley data. */ | |
42 char *shortcut; /**< Shortcut associated with the custom | |
43 smiley. This field will work as a | |
44 unique key by this API. */ | |
45 char *checksum; /**< The smiley checksum. */ | |
46 } PurpleSmiley; | |
47 | |
48 #ifdef __cplusplus | |
49 extern "C" { | |
50 #endif | |
51 | |
52 /**************************************************************************/ | |
53 /** @name Custom Smiley API */ | |
54 /**************************************************************************/ | |
55 /*@{*/ | |
56 | |
57 /** | |
58 * Creates a new custom smiley structure and populates it. | |
59 * | |
60 * If a custom smiley with the informed shortcut already exist, it | |
61 * will be automaticaly returned. | |
62 * | |
63 * @param img The image associated with the smiley. | |
64 * @param shortcut The custom smiley associated shortcut. | |
65 * | |
66 * @return The custom smiley structure filled up. | |
67 */ | |
68 PurpleSmiley * | |
69 purple_smiley_new(PurpleStoredImage *img, const char *shortcut); | |
70 | |
71 /** | |
72 * Creates a new custom smiley structure and populates it. | |
73 * | |
74 * If a custom smiley with the informed shortcut already exist, it | |
75 * will be automaticaly returned. | |
76 * | |
77 * @param shortcut The custom smiley associated shortcut. | |
78 * @param smiley_data The custom smiley data. | |
79 * @param smiley_data_len The custom smiley data length. | |
80 * | |
81 * @return The custom smiley structure filled up. | |
82 */ | |
83 PurpleSmiley * | |
84 purple_smiley_new_from_stream(const char *shortcut, guchar *smiley_data, | |
85 size_t smiley_data_len, const char *filename); | |
86 | |
87 /** | |
88 * Creates a new custom smiley structure and populates it. | |
89 * | |
90 * The data is retrieved from an already existent file. | |
91 * | |
92 * If a custom smiley with the informed shortcut already exist, it | |
93 * will be automaticaly returned. | |
94 * | |
95 * @param shortcut The custom smiley associated shortcut. | |
96 * @param filepath The image file to be imported to a | |
97 * new custom smiley. | |
98 * | |
99 * @return The custom smiley structure filled up. | |
100 */ | |
101 PurpleSmiley * | |
102 purple_smiley_new_from_file(const char *shortcut, const char *filepath, | |
103 const char *filename); | |
104 | |
105 /** | |
106 * Destroy the custom smiley and release the associated resources. | |
107 * | |
108 * @param smiley The custom smiley. | |
109 */ | |
110 void | |
111 purple_smiley_delete(PurpleSmiley *smiley); | |
112 | |
113 /** | |
114 * Changes the custom smiley's shortcut. | |
115 * | |
116 * @param smiley The custom smiley. | |
117 * @param shortcut The custom smiley associated shortcut. | |
118 * | |
119 * @return TRUE whether the shortcut is not associated with another | |
120 * custom smiley and the parameters are valid. FALSE otherwise. | |
121 */ | |
122 gboolean | |
123 purple_smiley_set_shortcut(PurpleSmiley *smiley, const char *shortcut); | |
124 | |
125 /** | |
126 * Changes the custom smiley's data. | |
127 * | |
128 * When the filename controling is made outside this API, the param | |
129 * @keepfilename must be TRUE. | |
130 * Otherwise, the file and filename will be regenerated, and the | |
131 * old one will be removed. | |
132 * | |
133 * @param smiley The custom smiley. | |
134 * @param smiley_data The custom smiley data. | |
135 * @param smiley_data_len The custom smiley data length. | |
136 * @param keepfilename The current custom smiley's filename must be | |
137 * kept. | |
138 */ | |
139 void | |
140 purple_smiley_set_data(PurpleSmiley *smiley, guchar *smiley_data, | |
141 size_t smiley_data_len, gboolean keepfilename); | |
142 | |
143 /** | |
144 * Returns the custom smiley's associated shortcut. | |
145 * | |
146 * @param smiley The custom smiley. | |
147 * | |
148 * @return The shortcut. | |
149 */ | |
150 const char *purple_smiley_get_shortcut(const PurpleSmiley *smiley); | |
151 | |
152 /** | |
153 * Returns the custom smiley data's checksum. | |
154 * | |
155 * @param smiley The custom smiley. | |
156 * | |
157 * @return The checksum. | |
158 */ | |
159 const char *purple_smiley_get_checksum(const PurpleSmiley *smiley); | |
160 | |
161 /** | |
162 * Returns the PurpleStoredImage with the reference counter incremented. | |
163 * | |
164 * The returned PurpleStoredImage reference counter must be decremented | |
165 * after use. | |
166 * | |
167 * @param smiley The custom smiley. | |
168 * | |
169 * @return A PurpleStoredImage reference. | |
170 */ | |
171 PurpleStoredImage *purple_smiley_get_stored_image(const PurpleSmiley *smiley); | |
172 | |
173 /** | |
174 * Returns the custom smiley's data. | |
175 * | |
176 * @param smiley The custom smiley. | |
177 * @param len If not @c NULL, the length of the icon data returned | |
178 * will be set in the location pointed to by this. | |
179 * | |
180 * @return A pointer to the custom smiley data. | |
181 */ | |
182 gconstpointer purple_smiley_get_data(const PurpleSmiley *smiley, size_t *len); | |
183 | |
184 /** | |
185 * Returns an extension corresponding to the custom smiley's file type. | |
186 * | |
187 * @param smiley The custom smiley. | |
188 * | |
189 * @return The custom smiley's extension, "icon" if unknown, or @c NULL if | |
190 * the image data has disappeared. | |
191 */ | |
192 const char *purple_smiley_get_extension(const PurpleSmiley *smiley); | |
193 | |
194 /** | |
195 * Returns a full path to an custom smiley. | |
196 * | |
197 * If the custom smiley has data and the file exists in the cache, this | |
198 * will return a full path to the cached file. | |
199 * | |
200 * In general, it is not appropriate to be poking in the file cached | |
201 * directly. If you find yourself wanting to use this function, think | |
202 * very long and hard about it, and then don't. | |
203 * | |
204 * @param smiley The custom smiley. | |
205 * | |
206 * @return A full path to the file, or @c NULL under various conditions. | |
207 * The caller should use #g_free to free the returned string. | |
208 */ | |
209 char *purple_smiley_get_full_path(PurpleSmiley *smiley); | |
210 | |
211 /*@}*/ | |
212 | |
213 | |
214 /**************************************************************************/ | |
215 /** @name Custom Smiley Subsistem API */ | |
216 /**************************************************************************/ | |
217 /*@{*/ | |
218 | |
219 /** | |
220 * Returns a list of all custom smileys. | |
221 * | |
222 * @constreturn A list of all custom smileys. | |
223 */ | |
224 GList * | |
225 purple_smileys_get_all(void); | |
226 | |
227 /** | |
228 * Adds the custom smiley to the library persistence. | |
229 * | |
230 * @param smiley The custom smiley. | |
231 * | |
232 */ | |
233 void | |
234 purple_smileys_add(PurpleSmiley *smiley); | |
235 | |
236 /** | |
237 * Remove the custom smiley from persistence. | |
238 * | |
239 * @param smiley The custom smiley. | |
240 * | |
241 */ | |
242 void | |
243 purple_smileys_remove(PurpleSmiley *smiley); | |
244 | |
245 /** | |
246 * Returns the custom smiley given it's shortcut. | |
247 * | |
248 * @param shortcut The custom smiley's shortcut. | |
249 * | |
250 * @return The custom smiley (with a reference for the caller) if found, | |
251 * or @c NULL if not found. | |
252 */ | |
253 PurpleSmiley * | |
254 purple_smileys_find_by_shortcut(const char *shortcut); | |
255 | |
256 /** | |
257 * Returns the custom smiley given it's checksum. | |
258 * | |
259 * @param checksum The custom smiley's checksum. | |
260 * | |
261 * @return The custom smiley (with a reference for the caller) if found, | |
262 * or @c NULL if not found. | |
263 */ | |
264 PurpleSmiley * | |
265 purple_smileys_find_by_checksum(const char *checksum); | |
266 | |
267 /** | |
268 * Returns the directory used to store custom smiley cached files. | |
269 * | |
270 * The default directory is PURPLEDIR/smileys, unless otherwise specified | |
271 * by purple_buddy_icons_set_cache_dir(). | |
272 * | |
273 * @return The directory to store custom smyles cached files to. | |
274 */ | |
275 const char *purple_smileys_get_storing_dir(void); | |
276 | |
277 /** | |
278 * Initializes the custom smiley subsystem. | |
279 */ | |
280 void purple_smileys_init(void); | |
281 | |
282 /** | |
283 * Uninitializes the custom smiley subsystem. | |
284 */ | |
285 void purple_smileys_uninit(void); | |
286 | |
287 /*@}*/ | |
288 | |
289 #ifdef __cplusplus | |
290 } | |
291 #endif | |
292 | |
293 #endif /* _PURPLE_SMILEY_H_ */ | |
294 |