Room List channels: telepathy-glib API Reference Manual

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

## Functions

TpProxyPendingCall * | tp_cli_channel_type_room_list_call_get_listing_rooms ()
TpProxyPendingCall * | tp_cli_channel_type_room_list_call_list_rooms ()
TpProxyPendingCall * | tp_cli_channel_type_room_list_call_stop_listing ()
void | (*tp_cli_channel_type_room_list_callback_for_get_listing_rooms) ()
void | (*tp_cli_channel_type_room_list_callback_for_list_rooms) ()
void | (*tp_cli_channel_type_room_list_callback_for_stop_listing) ()
gboolean | tp_cli_channel_type_room_list_run_get_listing_rooms ()
gboolean | tp_cli_channel_type_room_list_run_list_rooms ()
gboolean | tp_cli_channel_type_room_list_run_stop_listing ()
TpProxySignalConnection * | tp_cli_channel_type_room_list_connect_to_got_rooms ()
TpProxySignalConnection * | tp_cli_channel_type_room_list_connect_to_listing_rooms ()
void | (*tp_cli_channel_type_room_list_signal_callback_got_rooms) ()
void | (*tp_cli_channel_type_room_list_signal_callback_listing_rooms) ()

## Includes

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

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

## Functions

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

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>). This property is mandatory.</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>

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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