roomlist.h File Reference
libpurple

Room List API. More...

`#include "account.h"`
`#include <glib.h>`

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

## 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. More...
PurpleRoomlist * | purple_roomlist_new (PurpleAccount *account)
| Returns a newly created room list object. More...
void | purple_roomlist_ref (PurpleRoomlist *list)
| Increases the reference count on the room list. More...
void | purple_roomlist_unref (PurpleRoomlist *list)
| Decreases the reference count on the room list. More...
void | purple_roomlist_set_fields (PurpleRoomlist *list, GList *fields)
| Set the different field types and their names for this protocol. More...
void | purple_roomlist_set_in_progress (PurpleRoomlist *list, gboolean in_progress)
| Set the "in progress" state of the room list. More...
gboolean | purple_roomlist_get_in_progress (PurpleRoomlist *list)
| Gets the "in progress" state of the room list. More...
void | purple_roomlist_room_add (PurpleRoomlist *list, PurpleRoomlistRoom *room)
| Adds a room to the list of them. More...
PurpleRoomlist * | purple_roomlist_get_list (PurpleConnection *gc)
| Returns a PurpleRoomlist structure from the prpl, and instructs the prpl to start fetching the list. More...
void | purple_roomlist_cancel_get_list (PurpleRoomlist *list)
| Tells the prpl to stop fetching the list. More...
void | purple_roomlist_expand_category (PurpleRoomlist *list, PurpleRoomlistRoom *category)
| Tells the prpl that a category was expanded. More...
GList * | purple_roomlist_get_fields (PurpleRoomlist *roomlist)
| Get the list of fields for a roomlist. More...
Room API
PurpleRoomlistRoom * | purple_roomlist_room_new (PurpleRoomlistRoomType type, const gchar *name, PurpleRoomlistRoom *parent)
| Creates a new room, to be added to the list. More...
void | purple_roomlist_room_add_field (PurpleRoomlist *list, PurpleRoomlistRoom *room, gconstpointer field)
| Adds a field to a room. More...
void | purple_roomlist_room_join (PurpleRoomlist *list, PurpleRoomlistRoom *room)
| Join a room, given a PurpleRoomlistRoom and it's associated PurpleRoomlist. More...
PurpleRoomlistRoomType | purple_roomlist_room_get_type (PurpleRoomlistRoom *room)
| Get the type of a room. More...
const char * | purple_roomlist_room_get_name (PurpleRoomlistRoom *room)
| Get the name of a room. More...
PurpleRoomlistRoom * | purple_roomlist_room_get_parent (PurpleRoomlistRoom *room)
| Get the parent of a room. More...
GList * | purple_roomlist_room_get_fields (PurpleRoomlistRoom *room)
| Get the list of fields for a room. More...
Room Field API
PurpleRoomlistField * | purple_roomlist_field_new (PurpleRoomlistFieldType type, const gchar *label, const gchar *name, gboolean hidden)
| Creates a new field. More...
PurpleRoomlistFieldType | purple_roomlist_field_get_type (PurpleRoomlistField *field)
| Get the type of a field. More...
const char * | purple_roomlist_field_get_label (PurpleRoomlistField *field)
| Get the label of a field. More...
gboolean | purple_roomlist_field_get_hidden (PurpleRoomlistField *field)
| Check whether a roomlist-field is hidden. More...
UI Registration Functions
void | purple_roomlist_set_ui_ops (PurpleRoomlistUiOps *ops)
| Sets the UI operations structure to be used in all purple room lists. More...
PurpleRoomlistUiOps * | purple_roomlist_get_ui_ops (void)
| Returns the purple window UI operations structure to be used in new windows. More...

## Detailed Description

Room List API.

Definition in file roomlist.h.

## Typedef Documentation

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