Room-related interfaces on Channels

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

## Synopsis

    #include <telepathy-glib/channel.h>

    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);
    void                (*tp_cli_channel_interface_room_config_callback_for_update_configuration)
                                                            (TpChannel *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

    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);
    void                (*tp_cli_channel_interface_subject_callback_for_set_subject)
                                                            (TpChannel *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

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

## Details

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

`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': &quot;The first rule of inteltakeover is: do not talk about inteltakeover&quot;, }</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.

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

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

`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