roomlist.h File Reference

Room List API. More...

#include "account.h"
#include "glib.h"

Include dependency graph for roomlist.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	_PurpleRoomlist
	Represents a list of rooms for a given connection on a given protocol. More...
struct	_PurpleRoomlistRoom
	Represents a room. More...
struct	_PurpleRoomlistField
	A field a room might have. More...
struct	_PurpleRoomlistUiOps
	The room list ops to be filled out by the UI. More...
Room List API
void	purple_roomlist_show_with_account (PurpleAccount *account)
	This is used to get the room list on an account, asking the UI to pop up a dialog with the specified account already selected, and pretend the user clicked the get list button.
PurpleRoomlist *	purple_roomlist_new (PurpleAccount *account)
	Returns a newly created room list object.
void	purple_roomlist_ref (PurpleRoomlist *list)
	Increases the reference count on the room list.
void	purple_roomlist_unref (PurpleRoomlist *list)
	Decreases the reference count on the room list.
void	purple_roomlist_set_fields (PurpleRoomlist *list, GList *fields)
	Set the different field types and their names for this protocol.
void	purple_roomlist_set_in_progress (PurpleRoomlist *list, gboolean in_progress)
	Set the "in progress" state of the room list.
gboolean	purple_roomlist_get_in_progress (PurpleRoomlist *list)
	Gets the "in progress" state of the room list.
void	purple_roomlist_room_add (PurpleRoomlist *list, PurpleRoomlistRoom *room)
	Adds a room to the list of them.
PurpleRoomlist *	purple_roomlist_get_list (PurpleConnection *gc)
	Returns a PurpleRoomlist structure from the prpl, and instructs the prpl to start fetching the list.
void	purple_roomlist_cancel_get_list (PurpleRoomlist *list)
	Tells the prpl to stop fetching the list.
void	purple_roomlist_expand_category (PurpleRoomlist *list, PurpleRoomlistRoom *category)
	Tells the prpl that a category was expanded.
GList *	purple_roomlist_get_fields (PurpleRoomlist *roomlist)
	Get the list of fields for a roomlist.
Room API
PurpleRoomlistRoom *	purple_roomlist_room_new (PurpleRoomlistRoomType type, const gchar *name, PurpleRoomlistRoom *parent)
	Creates a new room, to be added to the list.
void	purple_roomlist_room_add_field (PurpleRoomlist *list, PurpleRoomlistRoom *room, gconstpointer field)
	Adds a field to a room.
void	purple_roomlist_room_join (PurpleRoomlist *list, PurpleRoomlistRoom *room)
	Join a room, given a PurpleRoomlistRoom and it's associated PurpleRoomlist.
PurpleRoomlistRoomType	purple_roomlist_room_get_type (PurpleRoomlistRoom *room)
	Get the type of a room.
const char *	purple_roomlist_room_get_name (PurpleRoomlistRoom *room)
	Get the name of a room.
PurpleRoomlistRoom *	purple_roomlist_room_get_parent (PurpleRoomlistRoom *room)
	Get the parent of a room.
GList *	purple_roomlist_room_get_fields (PurpleRoomlistRoom *room)
	Get the list of fields for a room.
Room Field API
PurpleRoomlistField *	purple_roomlist_field_new (PurpleRoomlistFieldType type, const gchar *label, const gchar *name, gboolean hidden)
	Creates a new field.
PurpleRoomlistFieldType	purple_roomlist_field_get_type (PurpleRoomlistField *field)
	Get the type of a field.
const char *	purple_roomlist_field_get_label (PurpleRoomlistField *field)
	Get the label of a field.
gboolean	purple_roomlist_field_get_hidden (PurpleRoomlistField *field)
	Check whether a roomlist-field is hidden.
UI Registration Functions
void	purple_roomlist_set_ui_ops (PurpleRoomlistUiOps *ops)
	Sets the UI operations structure to be used in all purple room lists.
PurpleRoomlistUiOps *	purple_roomlist_get_ui_ops (void)
	Returns the purple window UI operations structure to be used in new windows.
Typedefs
typedef _PurpleRoomlist	PurpleRoomlist
typedef _PurpleRoomlistRoom	PurpleRoomlistRoom
typedef _PurpleRoomlistField	PurpleRoomlistField
typedef _PurpleRoomlistUiOps	PurpleRoomlistUiOps
Enumerations
enum	PurpleRoomlistRoomType { PURPLE_ROOMLIST_ROOMTYPE_CATEGORY = 0x01, PURPLE_ROOMLIST_ROOMTYPE_ROOM = 0x02 }
	The types of rooms. More...
enum	PurpleRoomlistFieldType { PURPLE_ROOMLIST_FIELD_BOOL, PURPLE_ROOMLIST_FIELD_INT, PURPLE_ROOMLIST_FIELD_STRING }
	The types of fields. More...

---

Detailed Description

Room List API.

Definition in file roomlist.h.

---

Enumeration Type Documentation

enum PurpleRoomlistFieldType

The types of fields. Enumerator: PURPLE_ROOMLIST_FIELD_STRING  We do a g_strdup on the passed value if it's this type. Definition at line 51 of file roomlist.h.

enum PurpleRoomlistRoomType

The types of rooms. These are ORable flags. Enumerator: PURPLE_ROOMLIST_ROOMTYPE_CATEGORY  It's a category, but not a room you can join. PURPLE_ROOMLIST_ROOMTYPE_ROOM  It's a room, like the kind you can join. Definition at line 41 of file roomlist.h.

---

Function Documentation

void purple_roomlist_cancel_get_list (  PurpleRoomlist *  list  )

Tells the prpl to stop fetching the list. If this is possible and done, the prpl will call set_in_progress with FALSE and possibly unref the list if it took a reference. Parameters: list  The room list to cancel a get_list on.

void purple_roomlist_expand_category (  PurpleRoomlist *  list, PurpleRoomlistRoom *  category )

Tells the prpl that a category was expanded. On some protocols, the rooms in the category won't be fetched until this is called. Parameters: list  The room list. category  The category that was expanded. The expression (category->type & PURPLE_ROOMLIST_ROOMTYPE_CATEGORY) must be true.

gboolean purple_roomlist_field_get_hidden (  PurpleRoomlistField *  field  )

Check whether a roomlist-field is hidden. Parameters: field  A PurpleRoomlistField, which must not be NULL. Returns: TRUE if the field is hidden, FALSE otherwise. Since: 2.4.0

const char* purple_roomlist_field_get_label (  PurpleRoomlistField *  field  )

Get the label of a field. Parameters: field  A PurpleRoomlistField, which must not be NULL. Returns: The label of the field. Since: 2.4.0

PurpleRoomlistFieldType purple_roomlist_field_get_type (  PurpleRoomlistField *  field  )

Get the type of a field. Parameters: field  A PurpleRoomlistField, which must not be NULL. Returns: The type of the field. Since: 2.4.0

PurpleRoomlistField* purple_roomlist_field_new (  PurpleRoomlistFieldType  type, const gchar *  label, const gchar *  name, gboolean  hidden )

Creates a new field. Parameters: type  The type of the field. label  The i18n'ed, user displayable name. name  The internal name of the field. hidden  Hide the field. Returns: A new PurpleRoomlistField, ready to be added to a GList and passed to purple_roomlist_set_fields().

GList* purple_roomlist_get_fields (  PurpleRoomlist *  roomlist  )

Get the list of fields for a roomlist. Parameters: roomlist  The roomlist, which must not be NULL. Note: The return value of this function must not be modified or freed. Returns: A list of fields Since: 2.4.0

gboolean purple_roomlist_get_in_progress (  PurpleRoomlist *  list  )

Gets the "in progress" state of the room list. The UI is encouraged to somehow hint to the user whether or not we're busy downloading a room list or not. Parameters: list  The room list. Returns: True if we're downloading it, or false if we're not.

PurpleRoomlist* purple_roomlist_get_list (  PurpleConnection *  gc  )

Returns a PurpleRoomlist structure from the prpl, and instructs the prpl to start fetching the list. Parameters: gc  The PurpleConnection to have get a list. Returns: A PurpleRoomlist* or NULL if the protocol doesn't support that.

PurpleRoomlistUiOps* purple_roomlist_get_ui_ops (  void   )

Returns the purple window UI operations structure to be used in new windows. Returns: A filled-out PurpleRoomlistUiOps structure.

PurpleRoomlist* purple_roomlist_new (  PurpleAccount *  account  )

Returns a newly created room list object. It has an initial reference count of 1. Parameters: account  The account that's listing rooms. Returns: The new room list handle.

void purple_roomlist_ref (  PurpleRoomlist *  list  )

Increases the reference count on the room list. Parameters: list  The object to ref.

void purple_roomlist_room_add (  PurpleRoomlist *  list, PurpleRoomlistRoom *  room )

Adds a room to the list of them. Parameters: list  The room list. room  The room to add to the list. The GList of fields must be in the same order as was given in purple_roomlist_set_fields().

void purple_roomlist_room_add_field (  PurpleRoomlist *  list, PurpleRoomlistRoom *  room, gconstpointer  field )

Adds a field to a room. Parameters: list  The room list the room belongs to. room  The room. field  The field to append. Strings get g_strdup'd internally.

GList* purple_roomlist_room_get_fields (  PurpleRoomlistRoom *  room  )

Get the list of fields for a room. Parameters: room  The room, which must not be NULL. Note: The return value of this function must not be modified or freed. Returns: A list of fields Since: 2.4.0

const char* purple_roomlist_room_get_name (  PurpleRoomlistRoom *  room  )

Get the name of a room. Parameters: room  The room, which must not be NULL. Returns: The name of the room. Since: 2.4.0

PurpleRoomlistRoom* purple_roomlist_room_get_parent (  PurpleRoomlistRoom *  room  )

Get the parent of a room. Parameters: room  The room, which must not be NULL. Returns: The parent of the room, which can be NULL. Since: 2.4.0

PurpleRoomlistRoomType purple_roomlist_room_get_type (  PurpleRoomlistRoom *  room  )

Get the type of a room. Parameters: room  The room, which must not be NULL. Returns: The type of the room. Since: 2.4.0

void purple_roomlist_room_join (  PurpleRoomlist *  list, PurpleRoomlistRoom *  room )

Join a room, given a PurpleRoomlistRoom and it's associated PurpleRoomlist. Parameters: list  The room list the room belongs to. room  The room to join.

PurpleRoomlistRoom* purple_roomlist_room_new (  PurpleRoomlistRoomType  type, const gchar *  name, PurpleRoomlistRoom *  parent )

Creates a new room, to be added to the list. Parameters: type  The type of room. name  The name of the room. parent  The room's parent, if any. Returns: A new room.

void purple_roomlist_set_fields (  PurpleRoomlist *  list, GList *  fields )

Set the different field types and their names for this protocol. This must be called before purple_roomlist_room_add(). Parameters: list  The room list. fields  A GList of PurpleRoomlistField's. UI's are encouraged to default to displaying them in the order given.

void purple_roomlist_set_in_progress (  PurpleRoomlist *  list, gboolean  in_progress )

Set the "in progress" state of the room list. The UI is encouraged to somehow hint to the user whether or not we're busy downloading a room list or not. Parameters: list  The room list. in_progress  We're downloading it, or we're not.

void purple_roomlist_set_ui_ops (  PurpleRoomlistUiOps *  ops  )

Sets the UI operations structure to be used in all purple room lists. Parameters: ops  The UI operations structure.

void purple_roomlist_show_with_account (  PurpleAccount *  account  )

This is used to get the room list on an account, asking the UI to pop up a dialog with the specified account already selected, and pretend the user clicked the get list button. While we're pretending, predend I didn't say anything about dialogs or buttons, since this is the core. Parameters: account  The account to get the list on.

void purple_roomlist_unref (  PurpleRoomlist *  list  )

Decreases the reference count on the room list. The room list will be destroyed when this reaches 0. Parameters: list  The room list object to unref and possibly destroy.