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 /* Protocol Roomlist Interface API                                        */
 311 /**************************************************************************/
 312
 313 #define PURPLE_TYPE_PROTOCOL_ROOMLIST \
 314         (purple_protocol_roomlist_iface_get_type())
 315
 316 typedef struct _PurpleProtocolRoomlistInterface PurpleProtocolRoomlistInterface;
 317
 318 /**
 319  * PurpleProtocolRoomlistInterface:
 320  *
 321  * The protocol roomlist interface.
 322  *
 323  * This interface provides callbacks for room listing.
 324  */
 325 struct _PurpleProtocolRoomlistInterface
 326 {
 327         /*< private >*/
 328         GTypeInterface parent_iface;
 329
 330         /*< public >*/
 331         PurpleRoomlist *(*get_list)(PurpleConnection *gc);
 332
 333         void (*cancel)(PurpleRoomlist *list);
 334
 335         void (*expand_category)(PurpleRoomlist *list,
 336                                                  PurpleRoomlistRoom *category);
 337
 338         /* room list serialize */
 339         char *(*room_serialize)(PurpleRoomlistRoom *room);
 340 };
 341
 342 #define PURPLE_IS_PROTOCOL_ROOMLIST(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_ROOMLIST))
 343 #define PURPLE_PROTOCOL_ROOMLIST_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_ROOMLIST, \
 344                                                  PurpleProtocolRoomlistInterface))
 345
 346 /**
 347  * purple_protocol_roomlist_iface_get_type:
 348  *
 349  * Returns: The #GType for the protocol roomlist interface.
 350  *
 351  * Since: 3.0.0
 352  */
 353 GType purple_protocol_roomlist_iface_get_type(void);
 354
 355 /**
 356  * purple_protocol_roomlist_iface_get_list:
 357  * @protocol: The #PurpleProtocol instance.
 358  * @gc: The #PurpleAccount to get the roomlist for.
 359  *
 360  * Gets the list of rooms for @gc.
 361  *
 362  * Returns: (transfer full): The roomlist for @gc.
 363  *
 364  * Since: 3.0.0
 365  */
 366 PurpleRoomlist *purple_protocol_roomlist_iface_get_list(PurpleProtocol *protocol,
 367                 PurpleConnection *gc);
 368
 369 /**
 370  * purple_protocol_roomlist_iface_cancel:
 371  * @protocol: The #PurpleProtocol instance.
 372  * @list: The #PurpleRoomlist instance.
 373  *
 374  * Requesting a roomlist can take a long time.  This function cancels a request
 375  * that's already in progress.
 376  *
 377  * Since: 3.0.0
 378  */
 379 void purple_protocol_roomlist_iface_cancel(PurpleProtocol *protocol,
 380                 PurpleRoomlist *list);
 381
 382 /**
 383  * purple_protocol_roomlist_iface_expand_category:
 384  * @protocol: The #PurpleProtocol instance.
 385  * @list: The #PurpleRoomlist instance.
 386  * @category: The category to expand.
 387  *
 388  * Expands the given @category for @list.
 389  *
 390  * Since: 3.0.0
 391  */
 392 void purple_protocol_roomlist_iface_expand_category(PurpleProtocol *protocol,
 393                 PurpleRoomlist *list, PurpleRoomlistRoom *category);
 394
 395 /**
 396  * purple_protocol_roomlist_iface_room_serialize:
 397  * @protocol: The #PurpleProtocol instance.
 398  * @room: The #PurpleRoomlistRoom instance.
 399  *
 400  * Serializes @room into a string that will be displayed in a user interface.
 401  *
 402  * Returns: (transfer full): The serialized form of @room.
 403  *
 404  * Since: 3.0.0
 405  */
 406 char *purple_protocol_roomlist_iface_room_serialize(PurpleProtocol *protocol,
 407                 PurpleRoomlistRoom *room);
 408
 409 /**************************************************************************/
 410 /* Room API                                                               */
 411 /**************************************************************************/
 412
 413 /**
 414  * purple_roomlist_room_get_type:
 415  *
 416  * Returns: The #GType for the #PurpleRoomlistRoom boxed structure.
 417  */
 418 GType purple_roomlist_room_get_type(void);
 419
 420 /**
 421  * purple_roomlist_room_new:
 422  * @type: The type of room.
 423  * @name: The name of the room.
 424  * @parent: The room's parent, if any.
 425  *
 426  * Creates a new room, to be added to the list.
 427  *
 428  * Returns: A new room.
 429  */
 430 PurpleRoomlistRoom *purple_roomlist_room_new(PurpleRoomlistRoomType type, const gchar *name,
 431                                          PurpleRoomlistRoom *parent);
 432
 433 /**
 434  * purple_roomlist_room_add_field:
 435  * @list: The room list the room belongs to.
 436  * @room: The room.
 437  * @field: The field to append. Strings get g_strdup'd internally.
 438  *
 439  * Adds a field to a room.
 440  */
 441 void purple_roomlist_room_add_field(PurpleRoomlist *list, PurpleRoomlistRoom *room, gconstpointer field);
 442
 443 /**
 444  * purple_roomlist_room_join:
 445  * @list: The room list the room belongs to.
 446  * @room: The room to join.
 447  *
 448  * Join a room, given a PurpleRoomlistRoom and it's associated PurpleRoomlist.
 449  */
 450 void purple_roomlist_room_join(PurpleRoomlist *list, PurpleRoomlistRoom *room);
 451
 452 /**
 453  * purple_roomlist_room_get_room_type:
 454  * @room:  The room, which must not be %NULL.
 455  *
 456  * Get the type of a room.
 457  *
 458  * Returns: The type of the room.
 459  */
 460 PurpleRoomlistRoomType purple_roomlist_room_get_room_type(PurpleRoomlistRoom *room);
 461
 462 /**
 463  * purple_roomlist_room_get_name:
 464  * @room:  The room, which must not be %NULL.
 465  *
 466  * Get the name of a room.
 467  *
 468  * Returns: The name of the room.
 469  */
 470 const char * purple_roomlist_room_get_name(PurpleRoomlistRoom *room);
 471
 472 /**
 473  * purple_roomlist_room_get_parent:
 474  * @room:  The room, which must not be %NULL.
 475  *
 476  * Get the parent of a room.
 477  *
 478  * Returns: The parent of the room, which can be %NULL.
 479  */
 480 PurpleRoomlistRoom * purple_roomlist_room_get_parent(PurpleRoomlistRoom *room);
 481
 482 /**
 483  * purple_roomlist_room_get_expanded_once:
 484  * @room:  The room, which must not be %NULL.
 485  *
 486  * Get the value of the expanded_once flag.
 487  *
 488  * Returns: The value of the expanded_once flag.
 489  */
 490 gboolean purple_roomlist_room_get_expanded_once(PurpleRoomlistRoom *room);
 491
 492 /**
 493  * purple_roomlist_room_set_expanded_once:
 494  * @room: The room, which must not be %NULL.
 495  * @expanded_once: The new value of the expanded_once flag.
 496  *
 497  * Set the expanded_once flag.
 498  */
 499 void purple_roomlist_room_set_expanded_once(PurpleRoomlistRoom *room, gboolean expanded_once);
 500
 501 /**
 502  * purple_roomlist_room_get_fields:
 503  * @room:  The room, which must not be %NULL.
 504  *
 505  * Get the list of fields for a room.
 506  *
 507  * Returns: (element-type PurpleRoomlistField) (transfer none): A list of fields
 508  */
 509 GList * purple_roomlist_room_get_fields(PurpleRoomlistRoom *room);
 510
 511 /**************************************************************************/
 512 /* Room Field API                                                         */
 513 /**************************************************************************/
 514
 515 /**
 516  * purple_roomlist_field_get_type:
 517  *
 518  * Returns: The #GType for the #PurpleRoomlistField boxed structure.
 519  */
 520 GType purple_roomlist_field_get_type(void);
 521
 522 /**
 523  * purple_roomlist_field_new:
 524  * @type:   The type of the field.
 525  * @label:  The i18n'ed, user displayable name.
 526  * @name:   The internal name of the field.
 527  * @hidden: Hide the field.
 528  *
 529  * Creates a new field.
 530  *
 531  * Returns: A new PurpleRoomlistField, ready to be added to a GList and passed to
 532  *         purple_roomlist_set_fields().
 533  */
 534 PurpleRoomlistField *purple_roomlist_field_new(PurpleRoomlistFieldType type,
 535                                            const gchar *label, const gchar *name,
 536                                            gboolean hidden);
 537
 538 /**
 539  * purple_roomlist_field_get_field_type:
 540  * @field:  A PurpleRoomlistField, which must not be %NULL.
 541  *
 542  * Get the type of a field.
 543  *
 544  * Returns:  The type of the field.
 545  */
 546 PurpleRoomlistFieldType purple_roomlist_field_get_field_type(PurpleRoomlistField *field);
 547
 548 /**
 549  * purple_roomlist_field_get_label:
 550  * @field:  A PurpleRoomlistField, which must not be %NULL.
 551  *
 552  * Get the label of a field.
 553  *
 554  * Returns:  The label of the field.
 555  */
 556 const char * purple_roomlist_field_get_label(PurpleRoomlistField *field);
 557
 558 /**
 559  * purple_roomlist_field_get_hidden:
 560  * @field:  A PurpleRoomlistField, which must not be %NULL.
 561  *
 562  * Check whether a roomlist-field is hidden.
 563  *
 564  * Returns:  %TRUE if the field is hidden, %FALSE otherwise.
 565  */
 566 gboolean purple_roomlist_field_get_hidden(PurpleRoomlistField *field);
 567
 568 /**************************************************************************/
 569 /* UI Registration Functions                                              */
 570 /**************************************************************************/
 571
 572 /**
 573  * purple_roomlist_ui_ops_get_type:
 574  *
 575  * Returns: The #GType for the #PurpleRoomlistUiOps boxed structure.
 576  */
 577 GType purple_roomlist_ui_ops_get_type(void);
 578
 579 /**
 580  * purple_roomlist_set_ui_ops:
 581  * @ops: The UI operations structure.
 582  *
 583  * Sets the UI operations structure to be used in all purple room lists.
 584  */
 585 void purple_roomlist_set_ui_ops(PurpleRoomlistUiOps *ops);
 586
 587 /**
 588  * purple_roomlist_get_ui_ops:
 589  *
 590  * Returns the purple window UI operations structure to be used in
 591  * new windows.
 592  *
 593  * Returns: A filled-out PurpleRoomlistUiOps structure.
 594  */
 595 PurpleRoomlistUiOps *purple_roomlist_get_ui_ops(void);
 596
 597 G_END_DECLS
 598
 599 #endif /* PURPLE_ROOMLIST_H */