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.
PurpleRoomlistpurple_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.
PurpleRoomlistpurple_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

PurpleRoomlistRoompurple_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.
PurpleRoomlistRoompurple_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

PurpleRoomlistFieldpurple_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.
PurpleRoomlistUiOpspurple_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.