libpurple/roomlist.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef PURPLE_ROOMLIST_H
  23 #define PURPLE_ROOMLIST_H
  24 /**
  25  * SECTION:roomlist
  26  * @section_id: libpurple-roomlist
  27  * @short_description: <filename>roomlist.h</filename>
  28  * @title: Room List API
  29  */
  30
  31 #define PURPLE_TYPE_ROOMLIST (purple_roomlist_get_type())
  32 typedef struct _PurpleRoomlist PurpleRoomlist;
  33
  34 #define PURPLE_TYPE_ROOMLIST_ROOM        (purple_roomlist_room_get_type())
  35
  36 typedef struct _PurpleRoomlistRoom PurpleRoomlistRoom;
  37
  38 #define PURPLE_TYPE_ROOMLIST_FIELD       (purple_roomlist_field_get_type())
  39
  40 typedef struct _PurpleRoomlistField PurpleRoomlistField;
  41
  42 #define PURPLE_TYPE_ROOMLIST_UI_OPS      (purple_roomlist_ui_ops_get_type())
  43
  44 typedef struct _PurpleRoomlistUiOps PurpleRoomlistUiOps;
  45
  46 /**
  47  * PurpleRoomlistRoomType:
  48  * @PURPLE_ROOMLIST_ROOMTYPE_CATEGORY: It's a category, but not a room you can
  49  *                                     join.
  50  * @PURPLE_ROOMLIST_ROOMTYPE_ROOM:     It's a room, like the kind you can join.
  51  *
  52  * The types of rooms.
  53  *
  54  * These are ORable flags.
  55  */
  56 typedef enum
  57 {
  58         PURPLE_ROOMLIST_ROOMTYPE_CATEGORY = 0x01,
  59         PURPLE_ROOMLIST_ROOMTYPE_ROOM     = 0x02
  60
  61 } PurpleRoomlistRoomType;
  62
  63 /**
  64  * PurpleRoomlistFieldType:
  65  * @PURPLE_ROOMLIST_FIELD_BOOL: The field is a boolean.
  66  * @PURPLE_ROOMLIST_FIELD_INT: The field is an integer.
  67  * @PURPLE_ROOMLIST_FIELD_STRING: We do a g_strdup on the passed value if it's
  68  *                                this type.
  69  *
  70  * The types of fields.
  71  */
  72 typedef enum
  73 {
  74         PURPLE_ROOMLIST_FIELD_BOOL,
  75         PURPLE_ROOMLIST_FIELD_INT,
  76         PURPLE_ROOMLIST_FIELD_STRING
  77
  78 } PurpleRoomlistFieldType;
  79
  80 #include "account.h"
  81 #include <glib.h>
  82
  83 /**************************************************************************/
  84 /* Data Structures                                                        */
  85 /**************************************************************************/
  86
  87 /**
  88  * PurpleRoomlistUiOps:
  89  * @show_with_account: Force the ui to pop up a dialog and get the list.
  90  * @create:            A new list was created.
  91  * @set_fields:        Sets the columns.
  92  * @add_room:          Add a room to the list.
  93  * @in_progress:       Are we fetching stuff still?
  94  * @destroy:           We're destroying list.
  95  *
  96  * The room list ops to be filled out by the UI.
  97  */
  98 struct _PurpleRoomlistUiOps {
  99         void (*show_with_account)(PurpleAccount *account);
 100         void (*create)(PurpleRoomlist *list);
 101         void (*set_fields)(PurpleRoomlist *list, GList *fields);
 102         void (*add_room)(PurpleRoomlist *list, PurpleRoomlistRoom *room);
 103         void (*in_progress)(PurpleRoomlist *list, gboolean flag);
 104         void (*destroy)(PurpleRoomlist *list);
 105
 106         /*< private >*/
 107         void (*_purple_reserved1)(void);
 108         void (*_purple_reserved2)(void);
 109         void (*_purple_reserved3)(void);
 110         void (*_purple_reserved4)(void);
 111 };
 112
 113 /**
 114  * PurpleRoomlist:
 115  * @ui_data: The UI data associated with this room list. This is a convenience
 116  *           field provided to the UIs -- it is not used by the libpurple core.
 117  *
 118  * Represents a list of rooms for a given connection on a given protocol.
 119  */
 120 struct _PurpleRoomlist {
 121         GObject gparent;
 122
 123         /*< public >*/
 124         gpointer ui_data;
 125 };
 126
 127 G_BEGIN_DECLS
 128
 129 /**************************************************************************/
 130 /* Room List API                                                          */
 131 /**************************************************************************/
 132
 133 /**
 134  * purple_roomlist_get_type:
 135  *
 136  * Returns: The #GType for the Room List object.
 137  */
 138 G_DECLARE_FINAL_TYPE(PurpleRoomlist, purple_roomlist, PURPLE, ROOMLIST, GObject)
 139
 140 /**
 141  * purple_roomlist_show_with_account:
 142  * @account: The account to get the list on.
 143  *
 144  * This is used to get the room list on an account, asking the UI
 145  * to pop up a dialog with the specified account already selected,
 146  * and pretend the user clicked the get list button.
 147  * While we're pretending, predend I didn't say anything about dialogs
 148  * or buttons, since this is the core.
 149  */
 150 void purple_roomlist_show_with_account(PurpleAccount *account);
 151
 152 /**
 153  * purple_roomlist_new:
 154  * @account: The account that's listing rooms.
 155  *
 156  * Returns a newly created room list object.
 157  *
 158  * Returns: The new room list handle.
 159  */
 160 PurpleRoomlist *purple_roomlist_new(PurpleAccount *account);
 161
 162 /**
 163  * purple_roomlist_get_account:
 164  * @list: The room list.
 165  *
 166  * Retrieve the PurpleAccount that was given when the room list was
 167  * created.
 168  *
 169  * Returns: (transfer none): The PurpleAccount tied to this room list.
 170  */
 171 PurpleAccount *purple_roomlist_get_account(PurpleRoomlist *list);
 172
 173 /**
 174  * purple_roomlist_set_fields:
 175  * @list: The room list.
 176  * @fields: (element-type PurpleRoomlistField) (transfer full): UI's are
 177  *          encouraged to default to displaying these fields in the order given.
 178  *
 179  * Set the different field types and their names for this protocol.
 180  *
 181  * This must be called before purple_roomlist_room_add().
 182  */
 183 void purple_roomlist_set_fields(PurpleRoomlist *list, GList *fields);
 184
 185 /**
 186  * purple_roomlist_set_in_progress:
 187  * @list: The room list.
 188  * @in_progress: We're downloading it, or we're not.
 189  *
 190  * Set the "in progress" state of the room list.
 191  *
 192  * The UI is encouraged to somehow hint to the user
 193  * whether or not we're busy downloading a room list or not.
 194  */
 195 void purple_roomlist_set_in_progress(PurpleRoomlist *list, gboolean in_progress);
 196
 197 /**
 198  * purple_roomlist_get_in_progress:
 199  * @list: The room list.
 200  *
 201  * Gets the "in progress" state of the room list.
 202  *
 203  * The UI is encouraged to somehow hint to the user
 204  * whether or not we're busy downloading a room list or not.
 205  *
 206  * Returns: True if we're downloading it, or false if we're not.
 207  */
 208 gboolean purple_roomlist_get_in_progress(PurpleRoomlist *list);
 209
 210 /**
 211  * purple_roomlist_room_add:
 212  * @list: The room list.
 213  * @room: The room to add to the list. The GList of fields must be in the same
 214                order as was given in purple_roomlist_set_fields().
 215  *
 216  * Adds a room to the list of them.
 217 */
 218 void purple_roomlist_room_add(PurpleRoomlist *list, PurpleRoomlistRoom *room);
 219
 220 /**
 221  * purple_roomlist_get_list:
 222  * @gc: The PurpleConnection to have get a list.
 223  *
 224  * Returns a PurpleRoomlist structure from the protocol, and
 225  * instructs the protocol to start fetching the list.
 226  *
 227  * Returns: (transfer full): A PurpleRoomlist* or %NULL if the protocol doesn't
 228  *          support that.
 229  */
 230 PurpleRoomlist *purple_roomlist_get_list(PurpleConnection *gc);
 231
 232 /**
 233  * purple_roomlist_cancel_get_list:
 234  * @list: The room list to cancel a get_list on.
 235  *
 236  * Tells the protocol to stop fetching the list.
 237  * If this is possible and done, the protocol will
 238  * call set_in_progress with %FALSE and possibly
 239  * unref the list if it took a reference.
 240  */
 241 void purple_roomlist_cancel_get_list(PurpleRoomlist *list);
 242
 243 /**
 244  * purple_roomlist_expand_category:
 245  * @list:     The room list.
 246  * @category: The category that was expanded. The expression
 247  *                 (category->type & PURPLE_ROOMLIST_ROOMTYPE_CATEGORY)
 248  *                 must be true.
 249  *
 250  * Tells the protocol that a category was expanded.
 251  *
 252  * On some protocols, the rooms in the category
 253  * won't be fetched until this is called.
 254  */
 255 void purple_roomlist_expand_category(PurpleRoomlist *list, PurpleRoomlistRoom *category);
 256
 257 /**
 258  * purple_roomlist_get_fields:
 259  * @roomlist: The roomlist, which must not be %NULL.
 260  *
 261  * Get the list of fields for a roomlist.
 262  *
 263  * Returns: (element-type PurpleRoomlistField) (transfer none): A list of fields
 264  */
 265 GList *purple_roomlist_get_fields(PurpleRoomlist *roomlist);
 266
 267 /**
 268  * purple_roomlist_get_protocol_data:
 269  * @list: The roomlist, which must not be %NULL.
 270  *
 271  * Get the protocol data associated with this room list.
 272  *
 273  * Returns: The protocol data associated with this room list.  This is a
 274  *         convenience field provided to the protocol -- it is not
 275  *         used the libpurple core.
 276  */
 277 gpointer purple_roomlist_get_protocol_data(PurpleRoomlist *list);
 278
 279 /**
 280  * purple_roomlist_set_protocol_data:
 281  * @list: The roomlist, which must not be %NULL.
 282  * @proto_data: A pointer to associate with this room list.
 283  *
 284  * Set the protocol data associated with this room list.
 285  */
 286 void purple_roomlist_set_protocol_data(PurpleRoomlist *list, gpointer proto_data);
 287
 288 /**
 289  * purple_roomlist_get_ui_data:
 290  * @list: The roomlist, which must not be %NULL.
 291  *
 292  * Get the UI data associated with this room list.
 293  *
 294  * Returns: The UI data associated with this room list.  This is a
 295  *         convenience field provided to the UIs--it is not
 296  *         used by the libpurple core.
 297  */
 298 gpointer purple_roomlist_get_ui_data(PurpleRoomlist *list);
 299
 300 /**
 301  * purple_roomlist_set_ui_data:
 302  * @list: The roomlist, which must not be %NULL.
 303  * @ui_data: A pointer to associate with this room list.
 304  *
 305  * Set the UI data associated with this room list.
 306  */
 307 void purple_roomlist_set_ui_data(PurpleRoomlist *list, gpointer ui_data);
 308
 309 /**************************************************************************/
 310 /* Room API                                                               */
 311 /**************************************************************************/
 312
 313 /**
 314  * purple_roomlist_room_get_type:
 315  *
 316  * Returns: The #GType for the #PurpleRoomlistRoom boxed structure.
 317  */
 318 GType purple_roomlist_room_get_type(void);
 319
 320 /**
 321  * purple_roomlist_room_new:
 322  * @type: The type of room.
 323  * @name: The name of the room.
 324  * @parent: The room's parent, if any.
 325  *
 326  * Creates a new room, to be added to the list.
 327  *
 328  * Returns: A new room.
 329  */
 330 PurpleRoomlistRoom *purple_roomlist_room_new(PurpleRoomlistRoomType type, const gchar *name,
 331                                          PurpleRoomlistRoom *parent);
 332
 333 /**
 334  * purple_roomlist_room_add_field:
 335  * @list: The room list the room belongs to.
 336  * @room: The room.
 337  * @field: The field to append. Strings get g_strdup'd internally.
 338  *
 339  * Adds a field to a room.
 340  */
 341 void purple_roomlist_room_add_field(PurpleRoomlist *list, PurpleRoomlistRoom *room, gconstpointer field);
 342
 343 /**
 344  * purple_roomlist_room_join:
 345  * @list: The room list the room belongs to.
 346  * @room: The room to join.
 347  *
 348  * Join a room, given a PurpleRoomlistRoom and it's associated PurpleRoomlist.
 349  */
 350 void purple_roomlist_room_join(PurpleRoomlist *list, PurpleRoomlistRoom *room);
 351
 352 /**
 353  * purple_roomlist_room_get_room_type:
 354  * @room:  The room, which must not be %NULL.
 355  *
 356  * Get the type of a room.
 357  *
 358  * Returns: The type of the room.
 359  */
 360 PurpleRoomlistRoomType purple_roomlist_room_get_room_type(PurpleRoomlistRoom *room);
 361
 362 /**
 363  * purple_roomlist_room_get_name:
 364  * @room:  The room, which must not be %NULL.
 365  *
 366  * Get the name of a room.
 367  *
 368  * Returns: The name of the room.
 369  */
 370 const char * purple_roomlist_room_get_name(PurpleRoomlistRoom *room);
 371
 372 /**
 373  * purple_roomlist_room_get_parent:
 374  * @room:  The room, which must not be %NULL.
 375  *
 376  * Get the parent of a room.
 377  *
 378  * Returns: The parent of the room, which can be %NULL.
 379  */
 380 PurpleRoomlistRoom * purple_roomlist_room_get_parent(PurpleRoomlistRoom *room);
 381
 382 /**
 383  * purple_roomlist_room_get_expanded_once:
 384  * @room:  The room, which must not be %NULL.
 385  *
 386  * Get the value of the expanded_once flag.
 387  *
 388  * Returns: The value of the expanded_once flag.
 389  */
 390 gboolean purple_roomlist_room_get_expanded_once(PurpleRoomlistRoom *room);
 391
 392 /**
 393  * purple_roomlist_room_set_expanded_once:
 394  * @room: The room, which must not be %NULL.
 395  * @expanded_once: The new value of the expanded_once flag.
 396  *
 397  * Set the expanded_once flag.
 398  */
 399 void purple_roomlist_room_set_expanded_once(PurpleRoomlistRoom *room, gboolean expanded_once);
 400
 401 /**
 402  * purple_roomlist_room_get_fields:
 403  * @room:  The room, which must not be %NULL.
 404  *
 405  * Get the list of fields for a room.
 406  *
 407  * Returns: (element-type PurpleRoomlistField) (transfer none): A list of fields
 408  */
 409 GList * purple_roomlist_room_get_fields(PurpleRoomlistRoom *room);
 410
 411 /**************************************************************************/
 412 /* Room Field API                                                         */
 413 /**************************************************************************/
 414
 415 /**
 416  * purple_roomlist_field_get_type:
 417  *
 418  * Returns: The #GType for the #PurpleRoomlistField boxed structure.
 419  */
 420 GType purple_roomlist_field_get_type(void);
 421
 422 /**
 423  * purple_roomlist_field_new:
 424  * @type:   The type of the field.
 425  * @label:  The i18n'ed, user displayable name.
 426  * @name:   The internal name of the field.
 427  * @hidden: Hide the field.
 428  *
 429  * Creates a new field.
 430  *
 431  * Returns: A new PurpleRoomlistField, ready to be added to a GList and passed to
 432  *         purple_roomlist_set_fields().
 433  */
 434 PurpleRoomlistField *purple_roomlist_field_new(PurpleRoomlistFieldType type,
 435                                            const gchar *label, const gchar *name,
 436                                            gboolean hidden);
 437
 438 /**
 439  * purple_roomlist_field_get_field_type:
 440  * @field:  A PurpleRoomlistField, which must not be %NULL.
 441  *
 442  * Get the type of a field.
 443  *
 444  * Returns:  The type of the field.
 445  */
 446 PurpleRoomlistFieldType purple_roomlist_field_get_field_type(PurpleRoomlistField *field);
 447
 448 /**
 449  * purple_roomlist_field_get_label:
 450  * @field:  A PurpleRoomlistField, which must not be %NULL.
 451  *
 452  * Get the label of a field.
 453  *
 454  * Returns:  The label of the field.
 455  */
 456 const char * purple_roomlist_field_get_label(PurpleRoomlistField *field);
 457
 458 /**
 459  * purple_roomlist_field_get_hidden:
 460  * @field:  A PurpleRoomlistField, which must not be %NULL.
 461  *
 462  * Check whether a roomlist-field is hidden.
 463  *
 464  * Returns:  %TRUE if the field is hidden, %FALSE otherwise.
 465  */
 466 gboolean purple_roomlist_field_get_hidden(PurpleRoomlistField *field);
 467
 468 /**************************************************************************/
 469 /* UI Registration Functions                                              */
 470 /**************************************************************************/
 471
 472 /**
 473  * purple_roomlist_ui_ops_get_type:
 474  *
 475  * Returns: The #GType for the #PurpleRoomlistUiOps boxed structure.
 476  */
 477 GType purple_roomlist_ui_ops_get_type(void);
 478
 479 /**
 480  * purple_roomlist_set_ui_ops:
 481  * @ops: The UI operations structure.
 482  *
 483  * Sets the UI operations structure to be used in all purple room lists.
 484  */
 485 void purple_roomlist_set_ui_ops(PurpleRoomlistUiOps *ops);
 486
 487 /**
 488  * purple_roomlist_get_ui_ops:
 489  *
 490  * Returns the purple window UI operations structure to be used in
 491  * new windows.
 492  *
 493  * Returns: A filled-out PurpleRoomlistUiOps structure.
 494  */
 495 PurpleRoomlistUiOps *purple_roomlist_get_ui_ops(void);
 496
 497 G_END_DECLS
 498
 499 #endif /* PURPLE_ROOMLIST_H */