## Room List channels

Room List channels — client-side wrappers for the Room List channel type

## Synopsis

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

    TpProxyPendingCall * tp_cli_channel_type_room_list_call_get_listing_rooms
                                                            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_channel_type_room_list_callback_for_get_listing_rooms callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    TpProxyPendingCall * tp_cli_channel_type_room_list_call_list_rooms
                                                            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_channel_type_room_list_callback_for_list_rooms callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    TpProxyPendingCall * tp_cli_channel_type_room_list_call_stop_listing
                                                            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_channel_type_room_list_callback_for_stop_listing callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    void                (*tp_cli_channel_type_room_list_callback_for_get_listing_rooms)
                                                            (TpChannel *proxy,
                                                             gboolean out_In_Progress,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    void                (*tp_cli_channel_type_room_list_callback_for_list_rooms)
                                                            (TpChannel *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    void                (*tp_cli_channel_type_room_list_callback_for_stop_listing)
                                                            (TpChannel *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    gboolean            tp_cli_channel_type_room_list_run_get_listing_rooms
                                                            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             gboolean *out_In_Progress,
                                                             GError **error,
                                                             GMainLoop **loop);
    gboolean            tp_cli_channel_type_room_list_run_list_rooms
                                                            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             GError **error,
                                                             GMainLoop **loop);
    gboolean            tp_cli_channel_type_room_list_run_stop_listing
                                                            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             GError **error,
                                                             GMainLoop **loop);
    TpProxySignalConnection * tp_cli_channel_type_room_list_connect_to_got_rooms
                                                            (TpChannel *proxy,
                                                             tp_cli_channel_type_room_list_signal_callback_got_rooms callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object,
                                                             GError **error);
    TpProxySignalConnection * tp_cli_channel_type_room_list_connect_to_listing_rooms
                                                            (TpChannel *proxy,
                                                             tp_cli_channel_type_room_list_signal_callback_listing_rooms callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object,
                                                             GError **error);
    void                (*tp_cli_channel_type_room_list_signal_callback_got_rooms)
                                                            (TpChannel *proxy,
                                                             const GPtrArray *arg_Rooms,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    void                (*tp_cli_channel_type_room_list_signal_callback_listing_rooms)
                                                            (TpChannel *proxy,
                                                             gboolean arg_Listing,
                                                             gpointer user_data,
                                                             GObject *weak_object);

## Description

Many instant messaging protocols allow named chatrooms to be listed. This section documents the auto-generated C wrappers for the Room List channel type.

## Details

### tp_cli_channel_type_room_list_call_get_listing_rooms ()

    TpProxyPendingCall * tp_cli_channel_type_room_list_call_get_listing_rooms
                                                            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_channel_type_room_list_callback_for_get_listing_rooms callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a GetListingRooms method call.

Check to see if there is already a room list request in progress on this channel.

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`callback` : | called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_channel_type_room_list_call_list_rooms ()

    TpProxyPendingCall * tp_cli_channel_type_room_list_call_list_rooms
                                                            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_channel_type_room_list_callback_for_list_rooms callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a ListRooms method call.

Request the list of rooms from the server. The <tp:member-ref>ListingRooms</tp:member-ref> (True) signal should be emitted when this request is being processed, <tp:member-ref>GotRooms</tp:member-ref> when any room information is received, and <tp:member-ref>ListingRooms</tp:member-ref> (False) when the request is complete.

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`callback` : | called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_channel_type_room_list_call_stop_listing ()

    TpProxyPendingCall * tp_cli_channel_type_room_list_call_stop_listing
                                                            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_channel_type_room_list_callback_for_stop_listing callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a StopListing method call.

Stop the room listing if it's in progress, but don't close the channel. The <tp:member-ref>ListingRooms</tp:member-ref> (False) signal should be emitted when the listing stops.

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`callback` : | called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_channel_type_room_list_callback_for_get_listing_rooms ()

    void                (*tp_cli_channel_type_room_list_callback_for_get_listing_rooms)
                                                            (TpChannel *proxy,
                                                             gboolean out_In_Progress,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Signature of the callback called when a GetListingRooms method call succeeds or fails.

`proxy` : | the proxy on which the call was made
`out_In_Progress` : | Used to return an 'out' argument if `error` is `NULL`: A boolean indicating if room listing is in progress
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_channel_type_room_list_callback_for_list_rooms ()

    void                (*tp_cli_channel_type_room_list_callback_for_list_rooms)
                                                            (TpChannel *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Signature of the callback called when a ListRooms method call succeeds or fails.

`proxy` : | the proxy on which the call was made
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_channel_type_room_list_callback_for_stop_listing ()

    void                (*tp_cli_channel_type_room_list_callback_for_stop_listing)
                                                            (TpChannel *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Signature of the callback called when a StopListing method call succeeds or fails.

`proxy` : | the proxy on which the call was made
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_channel_type_room_list_run_get_listing_rooms ()

    gboolean            tp_cli_channel_type_room_list_run_get_listing_rooms
                                                            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             gboolean *out_In_Progress,
                                                             GError **error,
                                                             GMainLoop **loop);

### Warning

`tp_cli_channel_type_room_list_run_get_listing_rooms` is deprecated and should not be used in newly-written code.

Call the method GetListingRooms and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Check to see if there is already a room list request in progress on this channel.

`proxy` : | A TpChannel or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`out_In_Progress` : | Used to return an 'out' argument if `TRUE` is returned: A boolean indicating if room listing is in progress
`error` : | If not `NULL`, used to return errors if `FALSE` is returned
`loop` : | If not `NULL`, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with `g_main_loop_quit()`, causing a return of `FALSE` with `error` set to `TP_DBUS_ERROR_CANCELLED`
Returns : | TRUE on success, FALSE and sets `error` on error

### tp_cli_channel_type_room_list_run_list_rooms ()

    gboolean            tp_cli_channel_type_room_list_run_list_rooms
                                                            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             GError **error,
                                                             GMainLoop **loop);

### Warning

`tp_cli_channel_type_room_list_run_list_rooms` is deprecated and should not be used in newly-written code.

Call the method ListRooms and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Request the list of rooms from the server. The <tp:member-ref>ListingRooms</tp:member-ref> (True) signal should be emitted when this request is being processed, <tp:member-ref>GotRooms</tp:member-ref> when any room information is received, and <tp:member-ref>ListingRooms</tp:member-ref> (False) when the request is complete.

`proxy` : | A TpChannel or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`error` : | If not `NULL`, used to return errors if `FALSE` is returned
`loop` : | If not `NULL`, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with `g_main_loop_quit()`, causing a return of `FALSE` with `error` set to `TP_DBUS_ERROR_CANCELLED`
Returns : | TRUE on success, FALSE and sets `error` on error

### tp_cli_channel_type_room_list_run_stop_listing ()

    gboolean            tp_cli_channel_type_room_list_run_stop_listing
                                                            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             GError **error,
                                                             GMainLoop **loop);

### Warning

`tp_cli_channel_type_room_list_run_stop_listing` is deprecated and should not be used in newly-written code.

Call the method StopListing and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Stop the room listing if it's in progress, but don't close the channel. The <tp:member-ref>ListingRooms</tp:member-ref> (False) signal should be emitted when the listing stops.

`proxy` : | A TpChannel or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`error` : | If not `NULL`, used to return errors if `FALSE` is returned
`loop` : | If not `NULL`, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with `g_main_loop_quit()`, causing a return of `FALSE` with `error` set to `TP_DBUS_ERROR_CANCELLED`
Returns : | TRUE on success, FALSE and sets `error` on error

### tp_cli_channel_type_room_list_connect_to_got_rooms ()

    TpProxySignalConnection * tp_cli_channel_type_room_list_connect_to_got_rooms
                                                            (TpChannel *proxy,
                                                             tp_cli_channel_type_room_list_signal_callback_got_rooms callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object,
                                                             GError **error);

Connect a handler to the signal GotRooms.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when information about rooms on the server becomes available. The array contains the room handle (as can be passed to the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref> method with HANDLE_TYPE_ROOM), the channel type, and a dictionary containing further information about the room as available. The following well-known keys and types are recommended for use where appropriate:</p> <dl> <dt>handle-name (s)</dt> <dd>The identifier of the room (as would be returned by <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>)</dd> <dt>name (s)</dt> <dd>The human-readable name of the room if different from the handle</dd> <dt>description (s)</dt> <dd>A description of the room's overall purpose</dd> <dt>subject (s)</dt> <dd>The current subject of conversation in the room (as would be returned by getting the string part of the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Subject2">Subject</tp:dbus-ref> property)</dd> <dt>members (u)</dt> <dd>The number of members in the room</dd> <dt>password (b)</dt> <dd>True if the room requires a password to enter</dd> <dt>invite-only (b)</dt> <dd>True if you cannot join the room, but must be invited</dd> <dt>room-id (s)</dt> <dd>The human-readable identifier of a chat room (as would be returned by getting the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room2">RoomName</tp:dbus-ref> property)</dd> <dt>server (s)</dt> <dd>The DNS name of the server hosting these channels (as would be returned by getting the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room2">Server</tp:dbus-ref> property)</dd> </dl>

`proxy` : | A TpChannel or subclass
`callback` : | Callback to be called when the signal is received
`user_data` : | User-supplied data for the callback
`destroy` : | Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns `NULL`
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
`error` : | If not `NULL`, used to raise an error if `NULL` is returned
Returns : | a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or `NULL` if the proxy does not have the desired interface or has become invalid.

### tp_cli_channel_type_room_list_connect_to_listing_rooms ()

    TpProxySignalConnection * tp_cli_channel_type_room_list_connect_to_listing_rooms
                                                            (TpChannel *proxy,
                                                             tp_cli_channel_type_room_list_signal_callback_listing_rooms callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object,
                                                             GError **error);

Connect a handler to the signal ListingRooms.

Emitted to indicate whether or not room listing request is currently in progress.

`proxy` : | A TpChannel or subclass
`callback` : | Callback to be called when the signal is received
`user_data` : | User-supplied data for the callback
`destroy` : | Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns `NULL`
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
`error` : | If not `NULL`, used to raise an error if `NULL` is returned
Returns : | a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or `NULL` if the proxy does not have the desired interface or has become invalid.

### tp_cli_channel_type_room_list_signal_callback_got_rooms ()

    void                (*tp_cli_channel_type_room_list_signal_callback_got_rooms)
                                                            (TpChannel *proxy,
                                                             const GPtrArray *arg_Rooms,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Represents the signature of a callback for the signal GotRooms.

`proxy` : | The proxy on which `tp_cli_channel_type_room_list_connect_to_got_rooms()` was called
`arg_Rooms` : | <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structs containing: <ul> <li>an integer room handle</li> <li>a string representing the D-Bus interface name of the channel type</li> <li>a dictionary mapping string keys to variant boxed information</li> </ul>
`user_data` : | User-supplied data
`weak_object` : | User-supplied weakly referenced object

### tp_cli_channel_type_room_list_signal_callback_listing_rooms ()

    void                (*tp_cli_channel_type_room_list_signal_callback_listing_rooms)
                                                            (TpChannel *proxy,
                                                             gboolean arg_Listing,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Represents the signature of a callback for the signal ListingRooms.

`proxy` : | The proxy on which `tp_cli_channel_type_room_list_connect_to_listing_rooms()` was called
`arg_Listing` : | A boolean indicating if room listing is in progress
`user_data` : | User-supplied data
`weak_object` : | User-supplied weakly referenced object

## See Also

TpChannel