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

Detailed Description

Room List API.

Definition in file roomlist.h.

Typedef Documentation

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

Definition at line 34 of file roomlist.h.

Enumeration Type Documentation

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.

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
listThe 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
listThe room list.
categoryThe 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
fieldA 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
fieldA 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
fieldA 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
typeThe type of the field.
labelThe i18n'ed, user displayable name.
nameThe internal name of the field.
hiddenHide 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
roomlistThe 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
listThe 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
gcThe 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
accountThe 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
listThe object to ref.
void purple_roomlist_room_add ( PurpleRoomlist list,
PurpleRoomlistRoom room 
)

Adds a room to the list of them.

Parameters
listThe room list.
roomThe 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
listThe room list the room belongs to.
roomThe room.
fieldThe 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
roomThe 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
roomThe 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
roomThe 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
roomThe 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
listThe room list the room belongs to.
roomThe 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
typeThe type of room.
nameThe name of the room.
parentThe 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
listThe room list.
fieldsA 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
listThe room list.
in_progressWe'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
opsThe 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
accountThe 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
listThe room list object to unref and possibly destroy.
All information, including names and email addresses, entered onto this website or sent to mailing lists affiliated with this website will be public. Do not post confidential information, especially passwords!