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
	The room list ops to be filled out by the UI.

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 <br>
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 <br>
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 <br>
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 <br>
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

◆ PurpleRoomlist

typedef struct _PurpleRoomlist PurpleRoomlist

Definition at line 30 of file roomlist.h.

◆ PurpleRoomlistField

typedef struct _PurpleRoomlistField PurpleRoomlistField

Definition at line 32 of file roomlist.h.

◆ PurpleRoomlistRoom

typedef struct _PurpleRoomlistRoom PurpleRoomlistRoom

Definition at line 31 of file roomlist.h.

◆ PurpleRoomlistUiOps

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

◆ PurpleRoomlistFieldType

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.

◆ PurpleRoomlistRoomType

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

◆ purple_roomlist_cancel_get_list()

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.

◆ purple_roomlist_expand_category()

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.

◆ purple_roomlist_field_get_hidden()

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

◆ purple_roomlist_field_get_label()

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

◆ purple_roomlist_field_get_type()

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

◆ purple_roomlist_field_new()

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().

◆ purple_roomlist_get_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

◆ purple_roomlist_get_in_progress()

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.

◆ purple_roomlist_get_list()

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.

◆ purple_roomlist_get_ui_ops()

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.

◆ purple_roomlist_new()

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.

◆ purple_roomlist_ref()

void purple_roomlist_ref ( PurpleRoomlist * list )

Increases the reference count on the room list.

Parameters

list	The object to ref.

◆ purple_roomlist_room_add()

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().

◆ purple_roomlist_room_add_field()

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.

◆ purple_roomlist_room_get_fields()

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

◆ purple_roomlist_room_get_name()

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

◆ purple_roomlist_room_get_parent()

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

◆ purple_roomlist_room_get_type()

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

◆ purple_roomlist_room_join()

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.

◆ purple_roomlist_room_new()

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.

◆ purple_roomlist_set_fields()

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.

◆ purple_roomlist_set_in_progress()

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.

◆ purple_roomlist_set_ui_ops()

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.

◆ purple_roomlist_show_with_account()

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.

◆ purple_roomlist_unref()

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.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ PurpleRoomlist

◆ PurpleRoomlistField

◆ PurpleRoomlistRoom

◆ PurpleRoomlistUiOps

Enumeration Type Documentation

◆ PurpleRoomlistFieldType

◆ PurpleRoomlistRoomType

Function Documentation

◆ purple_roomlist_cancel_get_list()

◆ purple_roomlist_expand_category()

◆ purple_roomlist_field_get_hidden()

◆ purple_roomlist_field_get_label()

◆ purple_roomlist_field_get_type()

◆ purple_roomlist_field_new()

◆ purple_roomlist_get_fields()

◆ purple_roomlist_get_in_progress()

◆ purple_roomlist_get_list()

◆ purple_roomlist_get_ui_ops()

◆ purple_roomlist_new()

◆ purple_roomlist_ref()

◆ purple_roomlist_room_add()

◆ purple_roomlist_room_add_field()

◆ purple_roomlist_room_get_fields()

◆ purple_roomlist_room_get_name()

◆ purple_roomlist_room_get_parent()

◆ purple_roomlist_room_get_type()

◆ purple_roomlist_room_join()

◆ purple_roomlist_room_new()

◆ purple_roomlist_set_fields()

◆ purple_roomlist_set_in_progress()

◆ purple_roomlist_set_ui_ops()

◆ purple_roomlist_show_with_account()

◆ purple_roomlist_unref()