2 * @file roomlist.h Room List API
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.
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.
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.
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
27 #ifndef _PURPLE_ROOMLIST_H_
28 #define _PURPLE_ROOMLIST_H_
30 typedef struct _PurpleRoomlist PurpleRoomlist;
31 typedef struct _PurpleRoomlistRoom PurpleRoomlistRoom;
32 typedef struct _PurpleRoomlistField PurpleRoomlistField;
33 /** @copydoc _PurpleRoomlistUiOps */
34 typedef struct _PurpleRoomlistUiOps PurpleRoomlistUiOps;
39 * These are ORable flags.
43 PURPLE_ROOMLIST_ROOMTYPE_CATEGORY = 0x01, /**< It's a category, but not a room you can join. */
44 PURPLE_ROOMLIST_ROOMTYPE_ROOM = 0x02 /**< It's a room, like the kind you can join. */
46 } PurpleRoomlistRoomType;
49 * The types of fields.
53 PURPLE_ROOMLIST_FIELD_BOOL,
54 PURPLE_ROOMLIST_FIELD_INT,
55 PURPLE_ROOMLIST_FIELD_STRING /**< We do a g_strdup on the passed value if it's this type. */
57 } PurpleRoomlistFieldType;
62 /**************************************************************************/
63 /** Data Structures */
64 /**************************************************************************/
67 * Represents a list of rooms for a given connection on a given protocol.
69 struct _PurpleRoomlist {
70 PurpleAccount *account; /**< The account this list belongs to. */
71 GList *fields; /**< The fields. */
72 GList *rooms; /**< The list of rooms. */
73 gboolean in_progress; /**< The listing is in progress. */
74 gpointer ui_data; /**< UI private data. */
75 gpointer proto_data; /** Prpl private data. */
76 guint ref; /**< The reference count. */
82 struct _PurpleRoomlistRoom {
83 PurpleRoomlistRoomType type; /**< The type of room. */
84 gchar *name; /**< The name of the room. */
85 GList *fields; /**< Other fields. */
86 PurpleRoomlistRoom *parent; /**< The parent room, or NULL. */
87 gboolean expanded_once; /**< A flag the UI uses to avoid multiple expand prpl cbs. */
91 * A field a room might have.
93 struct _PurpleRoomlistField {
94 PurpleRoomlistFieldType type; /**< The type of field. */
95 gchar *label; /**< The i18n user displayed name of the field. */
96 gchar *name; /**< The internal name of the field. */
97 gboolean hidden; /**< Hidden? */
101 * The room list ops to be filled out by the UI.
103 struct _PurpleRoomlistUiOps {
104 void (*show_with_account)(PurpleAccount *account); /**< Force the ui to pop up a dialog and get the list */
105 void (*create)(PurpleRoomlist *list); /**< A new list was created. */
106 void (*set_fields)(PurpleRoomlist *list, GList *fields); /**< Sets the columns. */
107 void (*add_room)(PurpleRoomlist *list, PurpleRoomlistRoom *room); /**< Add a room to the list. */
108 void (*in_progress)(PurpleRoomlist *list, gboolean flag); /**< Are we fetching stuff still? */
109 void (*destroy)(PurpleRoomlist *list); /**< We're destroying list. */
111 void (*_purple_reserved1)(void);
112 void (*_purple_reserved2)(void);
113 void (*_purple_reserved3)(void);
114 void (*_purple_reserved4)(void);
122 /**************************************************************************/
123 /** @name Room List API */
124 /**************************************************************************/
128 * This is used to get the room list on an account, asking the UI
129 * to pop up a dialog with the specified account already selected,
130 * and pretend the user clicked the get list button.
131 * While we're pretending, predend I didn't say anything about dialogs
132 * or buttons, since this is the core.
134 * @param account The account to get the list on.
136 void purple_roomlist_show_with_account(PurpleAccount *account);
139 * Returns a newly created room list object.
141 * It has an initial reference count of 1.
143 * @param account The account that's listing rooms.
144 * @return The new room list handle.
146 PurpleRoomlist *purple_roomlist_new(PurpleAccount *account);
149 * Increases the reference count on the room list.
151 * @param list The object to ref.
153 void purple_roomlist_ref(PurpleRoomlist *list);
156 * Decreases the reference count on the room list.
158 * The room list will be destroyed when this reaches 0.
160 * @param list The room list object to unref and possibly
163 void purple_roomlist_unref(PurpleRoomlist *list);
166 * Set the different field types and their names for this protocol.
168 * This must be called before purple_roomlist_room_add().
170 * @param list The room list.
171 * @param fields A GList of PurpleRoomlistField's. UI's are encouraged
172 * to default to displaying them in the order given.
174 void purple_roomlist_set_fields(PurpleRoomlist *list, GList *fields);
177 * Set the "in progress" state of the room list.
179 * The UI is encouraged to somehow hint to the user
180 * whether or not we're busy downloading a room list or not.
182 * @param list The room list.
183 * @param in_progress We're downloading it, or we're not.
185 void purple_roomlist_set_in_progress(PurpleRoomlist *list, gboolean in_progress);
188 * Gets the "in progress" state of the room list.
190 * The UI is encouraged to somehow hint to the user
191 * whether or not we're busy downloading a room list or not.
193 * @param list The room list.
194 * @return True if we're downloading it, or false if we're not.
196 gboolean purple_roomlist_get_in_progress(PurpleRoomlist *list);
199 * Adds a room to the list of them.
201 * @param list The room list.
202 * @param room The room to add to the list. The GList of fields must be in the same
203 order as was given in purple_roomlist_set_fields().
205 void purple_roomlist_room_add(PurpleRoomlist *list, PurpleRoomlistRoom *room);
208 * Returns a PurpleRoomlist structure from the prpl, and
209 * instructs the prpl to start fetching the list.
211 * @param gc The PurpleConnection to have get a list.
213 * @return A PurpleRoomlist* or @c NULL if the protocol
214 * doesn't support that.
216 PurpleRoomlist *purple_roomlist_get_list(PurpleConnection *gc);
219 * Tells the prpl to stop fetching the list.
220 * If this is possible and done, the prpl will
221 * call set_in_progress with @c FALSE and possibly
222 * unref the list if it took a reference.
224 * @param list The room list to cancel a get_list on.
226 void purple_roomlist_cancel_get_list(PurpleRoomlist *list);
229 * Tells the prpl that a category was expanded.
231 * On some protocols, the rooms in the category
232 * won't be fetched until this is called.
234 * @param list The room list.
235 * @param category The category that was expanded. The expression
236 * (category->type & PURPLE_ROOMLIST_ROOMTYPE_CATEGORY)
239 void purple_roomlist_expand_category(PurpleRoomlist *list, PurpleRoomlistRoom *category);
242 * Get the list of fields for a roomlist.
244 * @param roomlist The roomlist, which must not be @c NULL.
245 * @constreturn A list of fields
248 GList * purple_roomlist_get_fields(PurpleRoomlist *roomlist);
252 /**************************************************************************/
253 /** @name Room API */
254 /**************************************************************************/
258 * Creates a new room, to be added to the list.
260 * @param type The type of room.
261 * @param name The name of the room.
262 * @param parent The room's parent, if any.
264 * @return A new room.
266 PurpleRoomlistRoom *purple_roomlist_room_new(PurpleRoomlistRoomType type, const gchar *name,
267 PurpleRoomlistRoom *parent);
270 * Adds a field to a room.
272 * @param list The room list the room belongs to.
273 * @param room The room.
274 * @param field The field to append. Strings get g_strdup'd internally.
276 void purple_roomlist_room_add_field(PurpleRoomlist *list, PurpleRoomlistRoom *room, gconstpointer field);
279 * Join a room, given a PurpleRoomlistRoom and it's associated PurpleRoomlist.
281 * @param list The room list the room belongs to.
282 * @param room The room to join.
284 void purple_roomlist_room_join(PurpleRoomlist *list, PurpleRoomlistRoom *room);
287 * Get the type of a room.
288 * @param room The room, which must not be @c NULL.
289 * @return The type of the room.
292 PurpleRoomlistRoomType purple_roomlist_room_get_type(PurpleRoomlistRoom *room);
295 * Get the name of a room.
296 * @param room The room, which must not be @c NULL.
297 * @return The name of the room.
300 const char * purple_roomlist_room_get_name(PurpleRoomlistRoom *room);
303 * Get the parent of a room.
304 * @param room The room, which must not be @c NULL.
305 * @return The parent of the room, which can be @c NULL.
308 PurpleRoomlistRoom * purple_roomlist_room_get_parent(PurpleRoomlistRoom *room);
311 * Get the list of fields for a room.
313 * @param room The room, which must not be @c NULL.
314 * @constreturn A list of fields
317 GList * purple_roomlist_room_get_fields(PurpleRoomlistRoom *room);
321 /**************************************************************************/
322 /** @name Room Field API */
323 /**************************************************************************/
327 * Creates a new field.
329 * @param type The type of the field.
330 * @param label The i18n'ed, user displayable name.
331 * @param name The internal name of the field.
332 * @param hidden Hide the field.
334 * @return A new PurpleRoomlistField, ready to be added to a GList and passed to
335 * purple_roomlist_set_fields().
337 PurpleRoomlistField *purple_roomlist_field_new(PurpleRoomlistFieldType type,
338 const gchar *label, const gchar *name,
342 * Get the type of a field.
344 * @param field A PurpleRoomlistField, which must not be @c NULL.
346 * @return The type of the field.
349 PurpleRoomlistFieldType purple_roomlist_field_get_type(PurpleRoomlistField *field);
352 * Get the label of a field.
354 * @param field A PurpleRoomlistField, which must not be @c NULL.
356 * @return The label of the field.
359 const char * purple_roomlist_field_get_label(PurpleRoomlistField *field);
362 * Check whether a roomlist-field is hidden.
363 * @param field A PurpleRoomlistField, which must not be @c NULL.
365 * @return @c TRUE if the field is hidden, @c FALSE otherwise.
368 gboolean purple_roomlist_field_get_hidden(PurpleRoomlistField *field);
372 /**************************************************************************/
373 /** @name UI Registration Functions */
374 /**************************************************************************/
378 * Sets the UI operations structure to be used in all purple room lists.
380 * @param ops The UI operations structure.
382 void purple_roomlist_set_ui_ops(PurpleRoomlistUiOps *ops);
385 * Returns the purple window UI operations structure to be used in
388 * @return A filled-out PurpleRoomlistUiOps structure.
390 PurpleRoomlistUiOps *purple_roomlist_get_ui_ops(void);
398 #endif /* _PURPLE_ROOMLIST_H_ */