Room List channels

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

## Synopsis

    #include <telepathy-glib/channel.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 out0,
                                                             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 *out0,
                                                             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
`user_data` : | user-supplied data passed to the callback
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
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 ListingRooms signal should be emitted when this request is being processed, GotRooms when any room information is received, and ListingRooms 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
`user_data` : | user-supplied data passed to the callback
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
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 ListingRooms 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
`user_data` : | user-supplied data passed to the callback
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
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 out0,
                                                             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
`out0` : | 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 *out0,
                                                             GError **error,
                                                             GMainLoop **loop);

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
`out0` : | 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);

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 ListingRooms signal should be emitted when this request is being processed, GotRooms when any room information is received, and ListingRooms 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);

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 ListingRooms 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 RequestChannel 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>s:handle-name</dt><dd>The string name of the room handle (as would be returned by InspectHandles)</dd> <dt>s:name</dt><dd>The human-readable name of the room if different from the handle</dd> <dt>s:description</dt><dd>A description of the room's overall purpose</dd> <dt>s:subject</dt><dd>The current subject of conversation in the room</dd> <dt>u:members</dt><dd>The number of members of the room</dd> <dt>b:password</dt><dd>True if the room requires a password to enter</dd> <dt>b:invite-only</dt><dd>True if you cannot join the room, but must be invited</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