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:


Data Structures
struct	_PurpleRoomlist
	Data Structures. 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...
Typedefs
typedef struct _PurpleRoomlist	PurpleRoomlist
typedef struct _PurpleRoomlistRoom	PurpleRoomlistRoom
typedef struct _PurpleRoomlistField	PurpleRoomlistField
typedef struct _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...
Functions
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.

Detailed Description

Room List API.

Definition in file roomlist.h.

Typedef Documentation

typedef struct _PurpleRoomlistUiOps PurpleRoomlistUiOps

The room list ops to be filled out by the UI.

Definition at line 34 of 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.

Context Navigation

roomlist.h File Reference

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation