Room-related interfaces on Channels: telepathy-glib API Reference Manual

## Room-related interfaces on Channels Room-related interfaces on Channels — client-side wrappers for Room, RoomConfig and Subject |

## Functions

TpProxyPendingCall * | tp_cli_channel_interface_room_config_call_update_configuration ()
void | (*tp_cli_channel_interface_room_config_callback_for_update_configuration) ()
TpProxyPendingCall * | tp_cli_channel_interface_subject_call_set_subject ()
void | (*tp_cli_channel_interface_subject_callback_for_set_subject) ()

## Includes

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

## Description

This family of interfaces exposes aspects of chat rooms' configuration, and provides API to modify it (where permitted). Most of the API is in terms of D-Bus properties; they may be retrieved using `tp_cli_dbus_properties_call_get_all()`, and changes monitored using `tp_cli_dbus_properties_connect_to_properties_changed()`.

TP_IFACE_CHANNEL_INTERFACE_ROOM consists only of a pair of requestable, immutable properties: TP_PROP_CHANNEL_INTERFACE_ROOM_ROOM_NAME and TP_PROP_CHANNEL_INTERFACE_ROOM_SERVER.

In addition to TP_IFACE_CHANNEL_INTERFACE_SUBJECT's single method, it defines a set of read-only properties: `"Subject"`,

`"Actor"`, `"ActorHandle"`, `"Timestamp"`,

and `"CanSet"`.

TP_IFACE_CHANNEL_INTERFACE_ROOM_CONFIG provides a vast array of properties for other aspects of a chat room's configuration (such as the maximum number of participants, and whether the room is password-protected).

## Functions

### tp_cli_channel_interface_room_config_call_update_configuration ()

    TpProxyPendingCall *
    tp_cli_channel_interface_room_config_call_update_configuration
                                   (TpChannel *proxy,
                                    gint timeout_ms,
                                    GHashTable *in_Properties,
                                    tp_cli_channel_interface_room_config_callback_for_update_configuration callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy,
                                    GObject *weak_object);

Start a UpdateConfiguration method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If <tp:member-ref>CanUpdateConfiguration</tp:member-ref> is <code>True</code>, modifies the current values of one or more room properties. This method SHOULD NOT return until the change has been accepted or declined by the server.</p> <p>Note that the server may ostensibly accept the changes (thus allowing this method to return success) but signal different values; for example, the server might truncate <tp:member-ref>Title</tp:member-ref> to some maximum length. Callers SHOULD continue to listen for the <code>PropertiesChanged</code> signal, and trust the values it signals over those provided to this method.</p>

#### Parameters

proxy | the TpProxy |
timeout_ms | the timeout in milliseconds, or -1 to use the default |
in_Properties | Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p> The new values of one or more properties on this interface, which must be listed in <tp:member-ref>MutableProperties</tp:member-ref>. For instance, to set up a channel for discussing top-secret corporate merge plans, this parameter might be: </p> <blockquote> <pre>{ 'Private': True, 'InviteOnly': True, 'Description': "The first rule of inteltakeover is: do not talk about inteltakeover", }</pre></blockquote> |
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_interface_room_config_callback_for_update_configuration ()

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

Signature of the callback called when a UpdateConfiguration 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_interface_subject_call_set_subject ()

    TpProxyPendingCall *
    tp_cli_channel_interface_subject_call_set_subject
                                   (TpChannel *proxy,
                                    gint timeout_ms,
                                    const gchar *in_Subject,
                                    tp_cli_channel_interface_subject_callback_for_set_subject callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy,
                                    GObject *weak_object);

Start a SetSubject method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Set the room's subject. Clients SHOULD look at the subject flags before calling this method as the user might not have permission to set the subject.</p> <p>A successful return of this method indicates a successful change in subject, but clients should still listen for changes to the <tp:member-ref>Subject</tp:member-ref> property for further changes by other users or the server.</p>

#### Parameters

proxy | the TpProxy |
timeout_ms | the timeout in milliseconds, or -1 to use the default |
in_Subject | Used to pass an 'in' argument: The new subject. |
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_interface_subject_callback_for_set_subject ()

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

Signature of the callback called when a SetSubject 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 |