## TpRoomList

TpRoomList — proxy object for a room list channel

## Synopsis

    #include <telepathy-glib/telepathy-glib.h>

    struct              TpRoomList;
    struct              TpRoomListClass;
    void                tp_room_list_new_async              (TpAccount *account,
                                                             const gchar *server,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    TpRoomList *        tp_room_list_new_finish             (GAsyncResult *result,
                                                             GError **error);
    gboolean            tp_room_list_is_listing             (TpRoomList *self);
    const gchar *       tp_room_list_get_server             (TpRoomList *self);
    TpAccount *         tp_room_list_get_account            (TpRoomList *self);
    void                tp_room_list_start                  (TpRoomList *self);

## Object Hierarchy

      GObject
       +----TpRoomList

## Implemented Interfaces

TpRoomList implements GAsyncInitable.

## Properties

      "account"                  TpAccount*            : Read / Write / Construct Only
      "listing"                  gboolean              : Read
      "server"                   gchar*                : Read / Write / Construct Only

## Signals

      "failed"                                         : Run Last
      "got-room"                                       : Run Last

## Description

TpRoomList provides convenient API to list rooms.

## Details

### struct TpRoomList

    struct TpRoomList;

Data structure representing a TpRoomList.

Since 0.19.0

### struct TpRoomListClass

    struct TpRoomListClass {
    };

The class of a TpRoomList.

Since 0.19.0

### tp_room_list_new_async ()

    void                tp_room_list_new_async              (TpAccount *account,
                                                             const gchar *server,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

`account` : | a TpAccount for the room listing
`server` : | the DNS name of the server whose rooms should listed
`callback` : | a GAsyncReadyCallback to call when the initialization is finished
`user_data` : | data to pass to the callback function

Since 0.19.0

### tp_room_list_new_finish ()

    TpRoomList *        tp_room_list_new_finish             (GAsyncResult *result,
                                                             GError **error);

`result` : | the GAsyncResult from the callback
`error` : | a GError location to store an error, or `NULL`
Returns : | a new TpRoomList object, or `NULL` in case of error. [transfer full]

Since 0.19.0

### tp_room_list_is_listing ()

    gboolean            tp_room_list_is_listing             (TpRoomList *self);

Return the "listing" property

`self` : | a TpRoomList
Returns : | the value of "listing" property

Since 0.19.0

### tp_room_list_get_server ()

    const gchar *       tp_room_list_get_server             (TpRoomList *self);

Return the "server" property

`self` : | a TpRoomList
Returns : | the value of "server" property

Since 0.19.0

### tp_room_list_get_account ()

    TpAccount *         tp_room_list_get_account            (TpRoomList *self);

Return the "account" property

`self` : | a TpRoomList
Returns : | the value of "account" property. [transfer none]

Since 0.19.0

### tp_room_list_start ()

    void                tp_room_list_start                  (TpRoomList *self);

Start listing rooms using `self`. Use the TpRoomList::got-rooms signal to get the rooms found. Errors will be reported using the TpRoomList::failed signal.

`self` : | a TpRoomList

Since 0.19.0

## Property Details

### The `"account"` property

      "account"                  TpAccount*            : Read / Write / Construct Only

The TpAccount to use for the room listing.

Since 0.19.0

### The `"listing"` property

      "listing"                  gboolean              : Read

`TRUE` if the channel is currently listing rooms.

This property is meaningless until the `TP_ROOM_LIST_FEATURE_LISTING` feature has been prepared.

Default value: FALSE

Since 0.19.0

### The `"server"` property

      "server"                   gchar*                : Read / Write / Construct Only

The DNS name of the server whose rooms are listed by this channel, or `NULL`.

Default value: NULL

Since 0.19.0

## Signal Details

### The `"failed"` signal

    void                user_function                      (TpRoomList *self,
                                                            GError     *error,
                                                            gpointer    user_data)      : Run Last

Fired when something goes wrong while listing the channels; see `error` for details.

`self` : | a TpRoomList
`error` : | a GError indicating the reason of the error
`user_data` : | user data set when the signal handler was connected.

Since 0.19.0

### The `"got-room"` signal

    void                user_function                      (TpRoomList *self,
                                                            TpRoomInfo *room,
                                                            gpointer    user_data)      : Run Last

Fired each time a room is found during the listing process. User should take his own reference on `room` if he plans to continue using it once the signal callback has returned.

`self` : | a TpRoomList
`room` : | a TpRoomInfo
`user_data` : | user data set when the signal handler was connected.

Since 0.19.0