Mercurial > pidgin.yaz
comparison libpurple/buddyicon.h @ 16373:c9b4ff420140
The buddy icon code as it stands, with lots of bugs and design flaws.
author | Richard Laager <rlaager@wiktel.com> |
---|---|
date | Mon, 23 Apr 2007 17:39:58 +0000 |
parents | b449dc6b8a20 |
children | 391a79778f89 |
comparison
equal
deleted
inserted
replaced
16372:bb08332c7456 | 16373:c9b4ff420140 |
---|---|
29 | 29 |
30 #include "account.h" | 30 #include "account.h" |
31 #include "blist.h" | 31 #include "blist.h" |
32 #include "prpl.h" | 32 #include "prpl.h" |
33 | 33 |
34 struct _PurpleBuddyIcon | |
35 { | |
36 PurpleAccount *account; /**< The account the user is on. */ | |
37 char *username; /**< The username the icon belongs to. */ | |
38 | |
39 void *data; /**< The buddy icon data. */ | |
40 size_t len; /**< The length of the buddy icon data. */ | |
41 char *path; /**< The buddy icon's non-cached path. */ | |
42 | |
43 int ref_count; /**< The buddy icon reference count. */ | |
44 }; | |
45 | |
46 #ifdef __cplusplus | 34 #ifdef __cplusplus |
47 extern "C" { | 35 extern "C" { |
48 #endif | 36 #endif |
49 | 37 |
38 // TODO: Deal with this. | |
39 char *purple_buddy_icons_get_full_path(const char *icon); | |
40 | |
50 /**************************************************************************/ | 41 /**************************************************************************/ |
51 /** @name Buddy Icon API */ | 42 /** @name Buddy Icon API */ |
52 /**************************************************************************/ | 43 /**************************************************************************/ |
53 /*@{*/ | 44 /*@{*/ |
54 | 45 |
55 /** | 46 /** |
56 * Creates a new buddy icon structure. | 47 * Create a buddy icon structure and populate it. |
48 * | |
49 * If the buddy icon already exists, you'll get a reference to that structure, | |
50 * which will have been updated with the data supplied. | |
57 * | 51 * |
58 * @param account The account the user is on. | 52 * @param account The account the user is on. |
59 * @param username The username the icon belongs to. | 53 * @param username The username the icon belongs to. |
60 * @param icon_data The buddy icon data. | 54 * @param protocol_icon_data The buddy icon data received over the wire. |
61 * @param icon_len The buddy icon length. | 55 * @param protocol_icon_len The length of the data in @a protocol_icon_data. |
62 * | 56 * @param custom_icon_data The data for a custom buddy icon set by the user. |
63 * @return The buddy icon structure. | 57 * @param custom_icon_len The length of the data in @a custom_icon-data. |
64 */ | 58 * @return The buddy icon structure, referenced for you. If you don't |
65 PurpleBuddyIcon *purple_buddy_icon_new(PurpleAccount *account, const char *username, | 59 * want the reference, then call purple_buddy_icon_unref(). However, |
66 void *icon_data, size_t icon_len); | 60 * you may want to use purple_buddy_icon_set_for_user() instead. |
67 | 61 */ |
68 /** | 62 PurpleBuddyIcon * |
69 * Destroys a buddy icon structure. | 63 purple_buddy_icon_new(PurpleAccount *account, const char *username, |
70 * | 64 void *protocol_icon_data, size_t protocol_icon_len, |
71 * If the buddy icon's reference count is greater than 1, this will | 65 void *custom_icon_data, size_t custom_icon_len); |
72 * just decrease the reference count and return. | |
73 * | |
74 * @param icon The buddy icon structure to destroy. | |
75 */ | |
76 void purple_buddy_icon_destroy(PurpleBuddyIcon *icon); | |
77 | 66 |
78 /** | 67 /** |
79 * Increments the reference count on a buddy icon. | 68 * Increments the reference count on a buddy icon. |
80 * | 69 * |
81 * @param icon The buddy icon. | 70 * @param icon The buddy icon. |
101 * @param icon The buddy icon. | 90 * @param icon The buddy icon. |
102 */ | 91 */ |
103 void purple_buddy_icon_update(PurpleBuddyIcon *icon); | 92 void purple_buddy_icon_update(PurpleBuddyIcon *icon); |
104 | 93 |
105 /** | 94 /** |
106 * Caches a buddy icon associated with a specific buddy to disk. | 95 * Sets the buddy icon's data for a custom icon set by the user. |
107 * | 96 * |
108 * @param icon The buddy icon. | 97 * @param icon The buddy icon. |
109 * @param buddy The buddy that this icon belongs to. | 98 * @param data The buddy icon data for the custom icon set by the user. |
110 */ | 99 * @param len The length of the data in @a data. |
111 void purple_buddy_icon_cache(PurpleBuddyIcon *icon, PurpleBuddy *buddy); | 100 */ |
112 | 101 void purple_buddy_icon_set_custom_data(PurpleBuddyIcon *icon, guchar *data, size_t len); |
113 /** | 102 |
114 * Removes cached buddy icon for a specific buddy. | 103 /** |
115 * | 104 * Sets the buddy icon's data that was received over the wire. |
116 * @param buddy The buddy for which to remove the cached icon. | 105 * |
117 */ | 106 * @param icon The buddy icon. |
118 void purple_buddy_icon_uncache(PurpleBuddy *buddy); | 107 * @param data The buddy icon data received over the wire. |
119 | 108 * @param len The length of the data in @a data. |
120 /** | 109 */ |
121 * Sets the buddy icon's account. | 110 void purple_buddy_icon_set_protocol_data(PurpleBuddyIcon *icon, guchar *data, size_t len); |
122 * | |
123 * @param icon The buddy icon. | |
124 * @param account The account. | |
125 */ | |
126 void purple_buddy_icon_set_account(PurpleBuddyIcon *icon, PurpleAccount *account); | |
127 | |
128 /** | |
129 * Sets the buddy icon's username. | |
130 * | |
131 * @param icon The buddy icon. | |
132 * @param username The username. | |
133 */ | |
134 void purple_buddy_icon_set_username(PurpleBuddyIcon *icon, const char *username); | |
135 | |
136 /** | |
137 * Sets the buddy icon's icon data. | |
138 * | |
139 * @param icon The buddy icon. | |
140 * @param data The buddy icon data. | |
141 * @param len The length of the icon data. | |
142 */ | |
143 void purple_buddy_icon_set_data(PurpleBuddyIcon *icon, void *data, size_t len); | |
144 | |
145 /** | |
146 * Sets the buddy icon's path. | |
147 * | |
148 * @param icon The buddy icon. | |
149 * @param path The buddy icon's non-cached path. | |
150 */ | |
151 void purple_buddy_icon_set_path(PurpleBuddyIcon *icon, const gchar *path); | |
152 | 111 |
153 /** | 112 /** |
154 * Returns the buddy icon's account. | 113 * Returns the buddy icon's account. |
155 * | 114 * |
156 * @param icon The buddy icon. | 115 * @param icon The buddy icon. |
169 const char *purple_buddy_icon_get_username(const PurpleBuddyIcon *icon); | 128 const char *purple_buddy_icon_get_username(const PurpleBuddyIcon *icon); |
170 | 129 |
171 /** | 130 /** |
172 * Returns the buddy icon's data. | 131 * Returns the buddy icon's data. |
173 * | 132 * |
174 * @param icon The buddy icon. | 133 * This will return the data for a custom icon, if one has been set by the |
175 * @param len The returned icon length. | 134 * user. Otherwise, it will return the protocol data, if available. If |
135 * no data is available (which can happen if you're holding on to a | |
136 * reference to an icon and the protocol and/or custom icon(s) are deleted | |
137 * under you), it will return @c NULL. | |
138 * | |
139 * @param icon The buddy icon. | |
140 * @param len If not @c NULL, the length of the icon data returned will be | |
141 * set in the location pointed to by this. | |
176 * | 142 * |
177 * @return The icon data. | 143 * @return The icon data. |
178 */ | 144 */ |
179 const guchar *purple_buddy_icon_get_data(const PurpleBuddyIcon *icon, size_t *len); | 145 const guchar *purple_buddy_icon_get_data(const PurpleBuddyIcon *icon, size_t *len); |
180 | 146 |
181 /** | 147 /** |
182 * Returns the buddy icon's path. | |
183 * | |
184 * @param icon The buddy icon. | |
185 * | |
186 * @return The buddy icon's non-cached path. | |
187 */ | |
188 const gchar *purple_buddy_icon_get_path(PurpleBuddyIcon *icon); | |
189 | |
190 /** | |
191 * Returns an extension corresponding to the buddy icon's file type. | 148 * Returns an extension corresponding to the buddy icon's file type. |
192 * | 149 * |
193 * @param icon The buddy icon. | 150 * This will return the type of a custom icon, if one has been set by the |
194 * | 151 * user. Otherwise, it will return the type of the protocol icon, if |
195 * @return The icon's extension. | 152 * available. If no data is available (which can happen if you're holding on |
153 * to a reference to an icon and the protocol and/or custom icon(s) are deleted | |
154 * under you), it will return @c NULL. | |
155 * | |
156 * @param icon The buddy icon. | |
157 * | |
158 * @return The icon's extension, or "icon" if unknown. | |
196 */ | 159 */ |
197 const char *purple_buddy_icon_get_type(const PurpleBuddyIcon *icon); | 160 const char *purple_buddy_icon_get_type(const PurpleBuddyIcon *icon); |
198 | 161 |
199 /*@}*/ | 162 /*@}*/ |
200 | 163 |
211 * @param icon_data The icon data. | 174 * @param icon_data The icon data. |
212 * @param icon_len The length of the icon data. | 175 * @param icon_len The length of the icon data. |
213 * | 176 * |
214 * @return The buddy icon set, or NULL if no icon was set. | 177 * @return The buddy icon set, or NULL if no icon was set. |
215 */ | 178 */ |
216 void purple_buddy_icons_set_for_user(PurpleAccount *account, const char *username, | 179 void |
217 void *icon_data, size_t icon_len); | 180 purple_buddy_icons_set_for_user(PurpleAccount *account, const char *username, |
181 void *icon_data, size_t icon_len); | |
218 | 182 |
219 /** | 183 /** |
220 * Returns the buddy icon information for a user. | 184 * Returns the buddy icon information for a user. |
221 * | 185 * |
222 * @param account The account the user is on. | 186 * @param account The account the user is on. |
223 * @param username The username of the user. | 187 * @param username The username of the user. |
224 * | 188 * |
225 * @return The icon data if found, or @c NULL if not found. | 189 * @return The icon data if found, or @c NULL if not found. |
226 */ | 190 */ |
227 PurpleBuddyIcon *purple_buddy_icons_find(PurpleAccount *account, | 191 PurpleBuddyIcon * |
228 const char *username); | 192 purple_buddy_icons_find(PurpleAccount *account, const char *username); |
229 | 193 |
230 /** | 194 /** |
231 * Sets whether or not buddy icon caching is enabled. | 195 * Sets whether or not buddy icon caching is enabled. |
232 * | 196 * |
233 * @param caching TRUE of buddy icon caching should be enabled, or | 197 * @param caching TRUE of buddy icon caching should be enabled, or |
259 * by purple_buddy_icons_set_cache_dir(). | 223 * by purple_buddy_icons_set_cache_dir(). |
260 * | 224 * |
261 * @return The directory to store buddy icon cache files to. | 225 * @return The directory to store buddy icon cache files to. |
262 */ | 226 */ |
263 const char *purple_buddy_icons_get_cache_dir(void); | 227 const char *purple_buddy_icons_get_cache_dir(void); |
264 | |
265 /** | |
266 * Takes a buddy icon and returns a full path. | |
267 * | |
268 * If @a icon is a full path to an existing file, a copy of | |
269 * @a icon is returned. Otherwise, a newly allocated string | |
270 * consiting of purple_buddy_icons_get_cache_dir() + @a icon is | |
271 * returned. | |
272 * | |
273 * @return The full path for an icon. | |
274 */ | |
275 char *purple_buddy_icons_get_full_path(const char *icon); | |
276 | 228 |
277 /** | 229 /** |
278 * Returns the buddy icon subsystem handle. | 230 * Returns the buddy icon subsystem handle. |
279 * | 231 * |
280 * @return The subsystem handle. | 232 * @return The subsystem handle. |