libpurple/roomlist.h

   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_ */