Mercurial > pidgin
annotate src/roomlist.h @ 8849:50d0f76639e7
[gaim-migrate @ 9616]
Let there be SILC.
committer: Tailor Script <tailor@pidgin.im>
author | Ethan Blanton <elb@pidgin.im> |
---|---|
date | Sat, 01 May 2004 19:34:44 +0000 |
parents | 92cbf9713795 |
children | c2dff943e240 |
rev | line source |
---|---|
8113 | 1 /** |
2 * @file roomlist.h Room List API | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
8146 | 7 * Gaim is the legal property of its developers, whose names are too numerous |
8 * to list here. Please refer to the COPYRIGHT file distributed with this | |
9 * source distribution. | |
8113 | 10 * |
11 * This program is free software; you can redistribute it and/or modify | |
12 * it under the terms of the GNU General Public License as published by | |
13 * the Free Software Foundation; either version 2 of the License, or | |
14 * (at your option) any later version. | |
15 * | |
16 * This program is distributed in the hope that it will be useful, | |
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 * GNU General Public License for more details. | |
20 * | |
21 * You should have received a copy of the GNU General Public License | |
22 * along with this program; if not, write to the Free Software | |
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
24 */ | |
25 | |
26 #ifndef _GAIM_ROOMLIST_H_ | |
27 #define _GAIM_ROOMLIST_H_ | |
28 | |
29 /**************************************************************************/ | |
30 /** Data Structures */ | |
31 /**************************************************************************/ | |
32 | |
33 typedef struct _GaimRoomlist GaimRoomlist; | |
34 typedef struct _GaimRoomlistRoom GaimRoomlistRoom; | |
35 typedef enum _GaimRoomlistRoomType GaimRoomlistRoomType; | |
36 typedef struct _GaimRoomlistField GaimRoomlistField; | |
37 typedef enum _GaimRoomlistFieldType GaimRoomlistFieldType; | |
38 typedef struct _GaimRoomlistUiOps GaimRoomlistUiOps; | |
39 | |
40 /** | |
41 * Represents a list of rooms for a given connection on a given protocol. | |
42 */ | |
43 struct _GaimRoomlist { | |
44 GaimAccount *account; /**< The account this list belongs to. */ | |
45 GList *fields; /**< The fields. */ | |
46 GList *rooms; /**< The list of rooms. */ | |
8199 | 47 gboolean in_progress; /**< The listing is in progress. */ |
8113 | 48 gpointer ui_data; /**< UI private data. */ |
49 gpointer proto_data; /** Prpl private data. */ | |
50 guint ref; /**< The reference count. */ | |
51 }; | |
52 | |
53 /** | |
54 * The types of rooms. | |
55 * | |
56 * These are ORable flags. | |
57 */ | |
58 enum _GaimRoomlistRoomType { | |
8584 | 59 GAIM_ROOMLIST_ROOMTYPE_CATEGORY = 0x01, /**< It's a category, but not a room you can join. */ |
8113 | 60 GAIM_ROOMLIST_ROOMTYPE_ROOM = 0x02, /**< It's a room, like the kind you can join. */ |
61 }; | |
62 | |
63 /** | |
64 * Represents a room. | |
65 */ | |
66 struct _GaimRoomlistRoom { | |
67 GaimRoomlistRoomType type; /**< The type of room. */ | |
68 gchar *name; /**< The name of the room. */ | |
69 GList *fields; /**< Other fields. */ | |
70 GaimRoomlistRoom *parent; /**< The parent room, or NULL. */ | |
71 gboolean expanded_once; /**< A flag the UI uses to avoid multiple expand prpl cbs. */ | |
72 }; | |
73 | |
74 /** | |
75 * The types of fields. | |
76 */ | |
77 enum _GaimRoomlistFieldType { | |
78 GAIM_ROOMLIST_FIELD_BOOL, | |
79 GAIM_ROOMLIST_FIELD_INT, | |
80 GAIM_ROOMLIST_FIELD_STRING, /**< We do a g_strdup on the passed value if it's this type. */ | |
81 }; | |
82 | |
83 /** | |
84 * A field a room might have. | |
85 */ | |
86 struct _GaimRoomlistField { | |
87 GaimRoomlistFieldType type; /**< The type of field. */ | |
88 gchar *label; /**< The i18n user displayed name of the field. */ | |
89 gchar *name; /**< The internal name of the field. */ | |
90 gboolean hidden; /**< Hidden? */ | |
91 }; | |
92 | |
93 /** | |
94 * The room list ops to be filled out by the UI. | |
95 */ | |
96 struct _GaimRoomlistUiOps { | |
8352 | 97 void (*show_with_account)(GaimAccount *account); /**< Force the ui to pop up a dialog and get the list */ |
8113 | 98 void (*new)(GaimRoomlist *list); /**< A new list was created. */ |
99 void (*set_fields)(GaimRoomlist *list, GList *fields); /**< Sets the columns. */ | |
100 void (*add_room)(GaimRoomlist *list, GaimRoomlistRoom *room); /**< Add a room to the list. */ | |
101 void (*in_progress)(GaimRoomlist *list, gboolean flag); /**< Are we fetching stuff still? */ | |
102 void (*destroy)(GaimRoomlist *list); /**< We're destroying list. */ | |
103 }; | |
104 | |
105 | |
106 #ifdef __cplusplus | |
107 extern "C" { | |
108 #endif | |
109 | |
110 /**************************************************************************/ | |
111 /** @name Room List API */ | |
112 /**************************************************************************/ | |
113 /*@{*/ | |
114 | |
115 /** | |
8352 | 116 * This is used to get the room list on an account, asking the UI |
117 * to pop up a dialog with the specified account already selected, | |
118 * and pretend the user clicked the get list button. | |
119 * While we're pretending, predend I didn't say anything about dialogs | |
120 * or buttons, since this is the core. | |
121 * | |
122 * @param account The account to get the list on. | |
123 */ | |
124 void gaim_roomlist_show_with_account(GaimAccount *account); | |
125 | |
126 /** | |
8113 | 127 * Returns a newly created room list object. |
128 * | |
8735
92cbf9713795
[gaim-migrate @ 9490]
Christian Hammond <chipx86@chipx86.com>
parents:
8584
diff
changeset
|
129 * It has an initial reference count of 1. |
8113 | 130 * |
131 * @param account The account that's listing rooms. | |
132 * @return The new room list handle. | |
133 */ | |
134 GaimRoomlist *gaim_roomlist_new(GaimAccount *account); | |
135 | |
136 /** | |
137 * Increases the reference count on the room list. | |
138 * | |
139 * @param list The object to ref. | |
140 */ | |
141 void gaim_roomlist_ref(GaimRoomlist *list); | |
142 | |
143 /** | |
144 * Decreases the reference count on the room list. | |
145 * | |
146 * The room list will be destroyed when this reaches 0. | |
147 * | |
148 * @param list The room list object to unref and possibly | |
149 * destroy. | |
150 */ | |
151 void gaim_roomlist_unref(GaimRoomlist *list); | |
152 | |
153 /** | |
154 * Set the different field types and their names for this protocol. | |
155 * | |
156 * This must be called before gaim_roomlist_room_add(). | |
157 * | |
158 * @param list The room list. | |
8735
92cbf9713795
[gaim-migrate @ 9490]
Christian Hammond <chipx86@chipx86.com>
parents:
8584
diff
changeset
|
159 * @param fields A GList of GaimRoomlistField's. UI's are encouraged |
8113 | 160 * to default to displaying them in the order given. |
161 */ | |
162 void gaim_roomlist_set_fields(GaimRoomlist *list, GList *fields); | |
163 | |
164 /** | |
165 * Set the "in progress" state of the room list. | |
166 * | |
8735
92cbf9713795
[gaim-migrate @ 9490]
Christian Hammond <chipx86@chipx86.com>
parents:
8584
diff
changeset
|
167 * The UI is encouraged to somehow hint to the user |
8113 | 168 * whether or not we're busy downloading a room list or not. |
169 * | |
170 * @param list The room list. | |
171 * @param in_progress We're downloading it, or we're not. | |
172 */ | |
173 void gaim_roomlist_set_in_progress(GaimRoomlist *list, gboolean in_progress); | |
174 | |
175 /** | |
8199 | 176 * Gets the "in progress" state of the room list. |
177 * | |
8735
92cbf9713795
[gaim-migrate @ 9490]
Christian Hammond <chipx86@chipx86.com>
parents:
8584
diff
changeset
|
178 * The UI is encouraged to somehow hint to the user |
8199 | 179 * whether or not we're busy downloading a room list or not. |
180 * | |
181 * @param list The room list. | |
182 * @returns True if we're downloading it, or false if we're not. | |
183 */ | |
184 gboolean gaim_roomlist_get_in_progress(GaimRoomlist *list); | |
185 | |
186 /** | |
8113 | 187 * Adds a room to the list of them. |
188 * | |
189 * @param list The room list. | |
190 * @param room The room to add to the list. The GList of fields must be in the same | |
191 order as was given in gaim_roomlist_set_fields(). | |
192 */ | |
193 void gaim_roomlist_room_add(GaimRoomlist *list, GaimRoomlistRoom *room); | |
194 | |
195 /** | |
196 * Do we support room listing? | |
197 * | |
198 * @param gc The GaimConnection we're asking. | |
199 * @return @c TRUE if it's possible to get a room list. | |
200 */ | |
201 gboolean gaim_roomlist_is_possible(GaimConnection *gc); | |
202 | |
203 /** | |
204 * Returns a GaimRoomlist structure from the prpl, and | |
205 * instructs the prpl to start fetching the list. | |
206 * | |
207 * @param gc The GaimConnection to have get a list. | |
208 * | |
209 * @return A GaimRoomlist* or @c NULL if the protocol | |
210 * doesn't support that. | |
211 */ | |
212 GaimRoomlist *gaim_roomlist_get_list(GaimConnection *gc); | |
213 | |
214 /** | |
215 * Tells the prpl to stop fetching the list. | |
216 * If this is possible and done, the prpl will | |
217 * call set_in_progress with @c FALSE and possibly | |
218 * unref the list if it took a reference. | |
219 * | |
220 * @param list The room list to cancel a get_list on. | |
221 */ | |
222 void gaim_roomlist_cancel_get_list(GaimRoomlist *list); | |
223 | |
224 /** | |
8584 | 225 * Tells the prpl that a category was expanded. |
8113 | 226 * |
8584 | 227 * On some protocols, the rooms in the category |
8113 | 228 * won't be fetched until this is called. |
229 * | |
230 * @param list The room list. | |
8584 | 231 * @param room The category that was expanded. The expression |
232 * (category->type & GAIM_ROOMLIST_ROOMTYPE_CATEGORY) | |
8113 | 233 * must be true. |
234 */ | |
8584 | 235 void gaim_roomlist_expand_category(GaimRoomlist *list, GaimRoomlistRoom *category); |
8113 | 236 |
237 /*@}*/ | |
238 | |
239 /**************************************************************************/ | |
240 /** @name Room API */ | |
241 /**************************************************************************/ | |
242 /*@{*/ | |
243 | |
244 /** | |
245 * Creates a new room, to be added to the list. | |
246 * | |
247 * @param type The type of room. | |
248 * @param name The name of the room. | |
249 * @param parent The room's parent, if any. | |
250 * | |
251 * @return A new room. | |
252 */ | |
253 GaimRoomlistRoom *gaim_roomlist_room_new(GaimRoomlistRoomType type, const gchar *name, | |
254 GaimRoomlistRoom *parent); | |
255 | |
256 /** | |
257 * Adds a field to a room. | |
258 * | |
259 * @param list The room list the room belongs to. | |
260 * @param room The room. | |
261 * @param field The field to append. Strings get g_strdup'd internally. | |
262 */ | |
263 void gaim_roomlist_room_add_field(GaimRoomlist *list, GaimRoomlistRoom *room, gconstpointer field); | |
264 | |
8199 | 265 /** |
266 * Join a room, given a GaimRoomlistRoom and it's associated GaimRoomlist. | |
267 * | |
268 * @param list The room list the room belongs to. | |
269 * @param room The room to join. | |
270 */ | |
271 void gaim_roomlist_room_join(GaimRoomlist *list, GaimRoomlistRoom *room); | |
272 | |
8113 | 273 /*@}*/ |
274 | |
275 /**************************************************************************/ | |
276 /** @name Room Field API */ | |
277 /**************************************************************************/ | |
278 /*@{*/ | |
279 | |
280 /** | |
281 * Creates a new field. | |
282 * | |
283 * @param type The type of the field. | |
284 * @param label The i18n'ed, user displayable name. | |
285 * @param name The internal name of the field. | |
286 * | |
287 * @return A new GaimRoomlistField, ready to be added to a GList and passed to | |
288 * gaim_roomlist_set_fields(). | |
289 */ | |
290 GaimRoomlistField *gaim_roomlist_field_new(GaimRoomlistFieldType type, | |
291 const gchar *label, const gchar *name, | |
292 gboolean hidden); | |
293 /*@}*/ | |
294 | |
295 /**************************************************************************/ | |
296 /** @name UI Registration Functions */ | |
297 /**************************************************************************/ | |
298 /*@{*/ | |
299 | |
300 /** | |
301 * Sets the UI operations structure to be used in all gaim room lists. | |
302 * | |
303 * @param ops The UI operations structure. | |
304 */ | |
305 void gaim_roomlist_set_ui_ops(GaimRoomlistUiOps *ops); | |
306 | |
307 /** | |
308 * Returns the gaim window UI operations structure to be used in | |
309 * new windows. | |
310 * | |
311 * @return A filled-out GaimRoomlistUiOps structure. | |
312 */ | |
313 GaimRoomlistUiOps *gaim_roomlist_get_ui_ops(void); | |
314 | |
315 /*@}*/ | |
316 | |
317 #ifdef __cplusplus | |
318 } | |
319 #endif | |
320 | |
321 #endif /* _GAIM_ROOMLIST_H_ */ |