1 /** 2 * @file roomlist.h Room List 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 #ifndef _PURPLE_ROOMLIST_H_ 28 #define _PURPLE_ROOMLIST_H_ 29 30 typedef struct _PurpleRoomlist PurpleRoomlist; 31 typedef struct _PurpleRoomlistRoom PurpleRoomlistRoom; 32 typedef struct _PurpleRoomlistField PurpleRoomlistField; 33 /** @copydoc _PurpleRoomlistUiOps */ 34 typedef struct _PurpleRoomlistUiOps PurpleRoomlistUiOps; 35 36 /** 37 * The types of rooms. 38 * 39 * These are ORable flags. 40 */ 41 typedef enum 42 { 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. */ 45 46 } PurpleRoomlistRoomType; 47 48 /** 49 * The types of fields. 50 */ 51 typedef enum 52 { 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. */ 56 57 } PurpleRoomlistFieldType; 58 59 #include "account.h" 60 #include <glib.h> 61 62 /**************************************************************************/ 63 /** Data Structures */ 64 /**************************************************************************/ 65 66 /** 67 * Represents a list of rooms for a given connection on a given protocol. 68 */ 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. */ 77 }; 78 79 /** 80 * Represents a room. 81 */ 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. */ 88 }; 89 90 /** 91 * A field a room might have. 92 */ 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? */ 98 }; 99 100 /** 101 * The room list ops to be filled out by the UI. 102 */ 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. */ 110 111 void (*_purple_reserved1)(void); 112 void (*_purple_reserved2)(void); 113 void (*_purple_reserved3)(void); 114 void (*_purple_reserved4)(void); 115 }; 116 117 118 #ifdef __cplusplus 119 extern "C" { 120 #endif 121 122 /**************************************************************************/ 123 /** @name Room List API */ 124 /**************************************************************************/ 125 /*@{*/ 126 127 /** 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. 133 * 134 * @param account The account to get the list on. 135 */ 136 void purple_roomlist_show_with_account(PurpleAccount *account); 137 138 /** 139 * Returns a newly created room list object. 140 * 141 * It has an initial reference count of 1. 142 * 143 * @param account The account that's listing rooms. 144 * @return The new room list handle. 145 */ 146 PurpleRoomlist *purple_roomlist_new(PurpleAccount *account); 147 148 /** 149 * Increases the reference count on the room list. 150 * 151 * @param list The object to ref. 152 */ 153 void purple_roomlist_ref(PurpleRoomlist *list); 154 155 /** 156 * Decreases the reference count on the room list. 157 * 158 * The room list will be destroyed when this reaches 0. 159 * 160 * @param list The room list object to unref and possibly 161 * destroy. 162 */ 163 void purple_roomlist_unref(PurpleRoomlist *list); 164 165 /** 166 * Set the different field types and their names for this protocol. 167 * 168 * This must be called before purple_roomlist_room_add(). 169 * 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. 173 */ 174 void purple_roomlist_set_fields(PurpleRoomlist *list, GList *fields); 175 176 /** 177 * Set the "in progress" state of the room list. 178 * 179 * The UI is encouraged to somehow hint to the user 180 * whether or not we're busy downloading a room list or not. 181 * 182 * @param list The room list. 183 * @param in_progress We're downloading it, or we're not. 184 */ 185 void purple_roomlist_set_in_progress(PurpleRoomlist *list, gboolean in_progress); 186 187 /** 188 * Gets the "in progress" state of the room list. 189 * 190 * The UI is encouraged to somehow hint to the user 191 * whether or not we're busy downloading a room list or not. 192 * 193 * @param list The room list. 194 * @return True if we're downloading it, or false if we're not. 195 */ 196 gboolean purple_roomlist_get_in_progress(PurpleRoomlist *list); 197 198 /** 199 * Adds a room to the list of them. 200 * 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(). 204 */ 205 void purple_roomlist_room_add(PurpleRoomlist *list, PurpleRoomlistRoom *room); 206 207 /** 208 * Returns a PurpleRoomlist structure from the prpl, and 209 * instructs the prpl to start fetching the list. 210 * 211 * @param gc The PurpleConnection to have get a list. 212 * 213 * @return A PurpleRoomlist* or @c NULL if the protocol 214 * doesn't support that. 215 */ 216 PurpleRoomlist *purple_roomlist_get_list(PurpleConnection *gc); 217 218 /** 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. 223 * 224 * @param list The room list to cancel a get_list on. 225 */ 226 void purple_roomlist_cancel_get_list(PurpleRoomlist *list); 227 228 /** 229 * Tells the prpl that a category was expanded. 230 * 231 * On some protocols, the rooms in the category 232 * won't be fetched until this is called. 233 * 234 * @param list The room list. 235 * @param category The category that was expanded. The expression 236 * (category->type & PURPLE_ROOMLIST_ROOMTYPE_CATEGORY) 237 * must be true. 238 */ 239 void purple_roomlist_expand_category(PurpleRoomlist *list, PurpleRoomlistRoom *category); 240 241 /** 242 * Get the list of fields for a roomlist. 243 * 244 * @param roomlist The roomlist, which must not be @c NULL. 245 * @constreturn A list of fields 246 * @since 2.4.0 247 */ 248 GList * purple_roomlist_get_fields(PurpleRoomlist *roomlist); 249 250 /*@}*/ 251 252 /**************************************************************************/ 253 /** @name Room API */ 254 /**************************************************************************/ 255 /*@{*/ 256 257 /** 258 * Creates a new room, to be added to the list. 259 * 260 * @param type The type of room. 261 * @param name The name of the room. 262 * @param parent The room's parent, if any. 263 * 264 * @return A new room. 265 */ 266 PurpleRoomlistRoom *purple_roomlist_room_new(PurpleRoomlistRoomType type, const gchar *name, 267 PurpleRoomlistRoom *parent); 268 269 /** 270 * Adds a field to a room. 271 * 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. 275 */ 276 void purple_roomlist_room_add_field(PurpleRoomlist *list, PurpleRoomlistRoom *room, gconstpointer field); 277 278 /** 279 * Join a room, given a PurpleRoomlistRoom and it's associated PurpleRoomlist. 280 * 281 * @param list The room list the room belongs to. 282 * @param room The room to join. 283 */ 284 void purple_roomlist_room_join(PurpleRoomlist *list, PurpleRoomlistRoom *room); 285 286 /** 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. 290 * @since 2.4.0 291 */ 292 PurpleRoomlistRoomType purple_roomlist_room_get_type(PurpleRoomlistRoom *room); 293 294 /** 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. 298 * @since 2.4.0 299 */ 300 const char * purple_roomlist_room_get_name(PurpleRoomlistRoom *room); 301 302 /** 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. 306 * @since 2.4.0 307 */ 308 PurpleRoomlistRoom * purple_roomlist_room_get_parent(PurpleRoomlistRoom *room); 309 310 /** 311 * Get the list of fields for a room. 312 * 313 * @param room The room, which must not be @c NULL. 314 * @constreturn A list of fields 315 * @since 2.4.0 316 */ 317 GList * purple_roomlist_room_get_fields(PurpleRoomlistRoom *room); 318 319 /*@}*/ 320 321 /**************************************************************************/ 322 /** @name Room Field API */ 323 /**************************************************************************/ 324 /*@{*/ 325 326 /** 327 * Creates a new field. 328 * 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. 333 * 334 * @return A new PurpleRoomlistField, ready to be added to a GList and passed to 335 * purple_roomlist_set_fields(). 336 */ 337 PurpleRoomlistField *purple_roomlist_field_new(PurpleRoomlistFieldType type, 338 const gchar *label, const gchar *name, 339 gboolean hidden); 340 341 /** 342 * Get the type of a field. 343 * 344 * @param field A PurpleRoomlistField, which must not be @c NULL. 345 * 346 * @return The type of the field. 347 * @since 2.4.0 348 */ 349 PurpleRoomlistFieldType purple_roomlist_field_get_type(PurpleRoomlistField *field); 350 351 /** 352 * Get the label of a field. 353 * 354 * @param field A PurpleRoomlistField, which must not be @c NULL. 355 * 356 * @return The label of the field. 357 * @since 2.4.0 358 */ 359 const char * purple_roomlist_field_get_label(PurpleRoomlistField *field); 360 361 /** 362 * Check whether a roomlist-field is hidden. 363 * @param field A PurpleRoomlistField, which must not be @c NULL. 364 * 365 * @return @c TRUE if the field is hidden, @c FALSE otherwise. 366 * @since 2.4.0 367 */ 368 gboolean purple_roomlist_field_get_hidden(PurpleRoomlistField *field); 369 370 /*@}*/ 371 372 /**************************************************************************/ 373 /** @name UI Registration Functions */ 374 /**************************************************************************/ 375 /*@{*/ 376 377 /** 378 * Sets the UI operations structure to be used in all purple room lists. 379 * 380 * @param ops The UI operations structure. 381 */ 382 void purple_roomlist_set_ui_ops(PurpleRoomlistUiOps *ops); 383 384 /** 385 * Returns the purple window UI operations structure to be used in 386 * new windows. 387 * 388 * @return A filled-out PurpleRoomlistUiOps structure. 389 */ 390 PurpleRoomlistUiOps *purple_roomlist_get_ui_ops(void); 391 392 /*@}*/ 393 394 #ifdef __cplusplus 395 } 396 #endif 397 398 #endif /* _PURPLE_ROOMLIST_H_ */ 399