6846
|
1 /**
|
6869
|
2 * @file buddyicon.h Buddy Icon API
|
6846
|
3 * @ingroup core
|
|
4 *
|
|
5 * gaim
|
|
6 *
|
|
7 * Copyright (C) 2003 Christian Hammond <chipx86@gnupdate.org>
|
|
8 *
|
|
9 * This program is free software; you can redistribute it and/or modify
|
|
10 * it under the terms of the GNU General Public License as published by
|
|
11 * the Free Software Foundation; either version 2 of the License, or
|
|
12 * (at your option) any later version.
|
|
13 *
|
|
14 * This program is distributed in the hope that it will be useful,
|
|
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
17 * GNU General Public License for more details.
|
|
18 *
|
|
19 * You should have received a copy of the GNU General Public License
|
|
20 * along with this program; if not, write to the Free Software
|
|
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
22 */
|
|
23 #ifndef _GAIM_ICON_H_
|
|
24 #define _GAIM_ICON_H_
|
|
25
|
|
26 typedef struct _GaimBuddyIcon GaimBuddyIcon;
|
|
27
|
|
28 #include "account.h"
|
|
29
|
|
30 struct _GaimBuddyIcon
|
|
31 {
|
|
32 GaimAccount *account; /**< The account the user is on. */
|
|
33 char *username; /**< The username the icon belongs to. */
|
|
34
|
|
35 void *data; /**< The buddy icon data. */
|
|
36 size_t len; /**< The length of the buddy icon data. */
|
|
37
|
|
38 int ref_count; /**< The buddy icon reference count. */
|
|
39 };
|
|
40
|
|
41 /**************************************************************************/
|
|
42 /** @name Buddy Icon API */
|
|
43 /**************************************************************************/
|
|
44 /*@{*/
|
|
45
|
|
46 /**
|
|
47 * Creates a new buddy icon structure.
|
|
48 *
|
|
49 * @param account The account the user is on.
|
|
50 * @param username The username the icon belongs to.
|
|
51 * @param icon_data The buddy icon data.
|
|
52 * @param icon_len The buddy icon length.
|
|
53 *
|
|
54 * @return The buddy icon structure.
|
|
55 */
|
|
56 GaimBuddyIcon *gaim_buddy_icon_new(GaimAccount *account, const char *username,
|
|
57 void *icon_data, size_t icon_len);
|
|
58
|
|
59 /**
|
|
60 * Destroys a buddy icon structure.
|
|
61 *
|
|
62 * If the buddy icon's reference count is greater than 1, this will
|
|
63 * just decrease the reference count and return.
|
|
64 *
|
|
65 * @param icon The buddy icon structure to destroy.
|
|
66 */
|
|
67 void gaim_buddy_icon_destroy(GaimBuddyIcon *icon);
|
|
68
|
|
69 /**
|
|
70 * Increments the reference count on a buddy icon.
|
|
71 *
|
|
72 * @param icon The buddy icon.
|
|
73 *
|
|
74 * @return @a icon.
|
|
75 */
|
|
76 GaimBuddyIcon *gaim_buddy_icon_ref(GaimBuddyIcon *icon);
|
|
77
|
|
78 /**
|
|
79 * Decrements the reference count on a buddy icon.
|
|
80 *
|
|
81 * If the reference count reaches 0, the icon will be destroyed.
|
|
82 *
|
|
83 * @param icon The buddy icon.
|
|
84 *
|
|
85 * @return @a icon, or @c NULL if the reference count reached 0.
|
|
86 */
|
|
87 GaimBuddyIcon *gaim_buddy_icon_unref(GaimBuddyIcon *icon);
|
|
88
|
|
89 /**
|
|
90 * Updates every instance of this icon.
|
|
91 *
|
|
92 * @param icon The buddy icon.
|
|
93 */
|
|
94 void gaim_buddy_icon_update(GaimBuddyIcon *icon);
|
|
95
|
|
96 /**
|
|
97 * Sets the buddy icon's account.
|
|
98 *
|
|
99 * @param icon The buddy icon.
|
|
100 * @param account The account.
|
|
101 */
|
|
102 void gaim_buddy_icon_set_account(GaimBuddyIcon *icon, GaimAccount *account);
|
|
103
|
|
104 /**
|
|
105 * Sets the buddy icon's username.
|
|
106 *
|
|
107 * @param icon The buddy icon.
|
|
108 * @param username The username.
|
|
109 */
|
|
110 void gaim_buddy_icon_set_username(GaimBuddyIcon *icon, const char *username);
|
|
111
|
|
112 /**
|
|
113 * Sets the buddy icon's icon data.
|
|
114 *
|
|
115 * @param icon The buddy icon.
|
|
116 * @param data The buddy icon data.
|
|
117 * @param len The length of the icon data.
|
|
118 */
|
|
119 void gaim_buddy_icon_set_data(GaimBuddyIcon *icon, void *data, size_t len);
|
|
120
|
|
121 /**
|
|
122 * Returns the buddy icon's account.
|
|
123 *
|
|
124 * @param icon The buddy icon.
|
|
125 *
|
|
126 * @return The account.
|
|
127 */
|
|
128 GaimAccount *gaim_buddy_icon_get_account(const GaimBuddyIcon *icon);
|
|
129
|
|
130 /**
|
|
131 * Returns the buddy icon's username.
|
|
132 *
|
|
133 * @param icon The buddy icon.
|
|
134 *
|
|
135 * @return The username.
|
|
136 */
|
|
137 const char *gaim_buddy_icon_get_username(const GaimBuddyIcon *icon);
|
|
138
|
|
139 /**
|
|
140 * Returns the buddy icon's data.
|
|
141 *
|
|
142 * @param icon The buddy icon.
|
|
143 * @param len The returned icon length.
|
|
144 *
|
|
145 * @return The icon data.
|
|
146 */
|
|
147 const void *gaim_buddy_icon_get_data(const GaimBuddyIcon *icon, size_t *len);
|
|
148
|
|
149 /*@}*/
|
|
150
|
|
151 /**************************************************************************/
|
|
152 /** @name Buddy Icon Subsystem API */
|
|
153 /**************************************************************************/
|
|
154 /*@{*/
|
|
155
|
|
156 /**
|
|
157 * Sets a buddy icon for a user.
|
|
158 *
|
|
159 * @param account The account the user is on.
|
|
160 * @param username The username of the user.
|
|
161 * @param icon_data The icon data.
|
|
162 * @param icon_len The length of the icon data.
|
|
163 */
|
|
164 void gaim_buddy_icons_set_for_user(GaimAccount *account, const char *username,
|
|
165 void *icon_data, size_t icon_len);
|
|
166
|
|
167 /**
|
|
168 * Returns the buddy icon information for a user.
|
|
169 *
|
|
170 * @param account The account the user is on.
|
|
171 * @param username The username of the user.
|
|
172 *
|
|
173 * @return The icon data if found, or @c NULL if not found.
|
|
174 */
|
|
175 GaimBuddyIcon *gaim_buddy_icons_find(const GaimAccount *account,
|
|
176 const char *username);
|
|
177
|
|
178 /**
|
|
179 * Returns the buddy icon subsystem handle.
|
|
180 *
|
|
181 * @return The subsystem handle.
|
|
182 */
|
|
183 void *gaim_buddy_icons_get_handle();
|
|
184
|
|
185 /**
|
|
186 * Initializes the buddy icon subsystem.
|
|
187 */
|
|
188 void gaim_buddy_icons_init();
|
|
189
|
|
190 /**
|
|
191 * Uninitializes the buddy icon subsystem.
|
|
192 */
|
|
193 void gaim_buddy_icons_uninit();
|
|
194
|
|
195 /*@}*/
|
|
196
|
|
197 #endif /* _GAIM_ICON_H_ */
|