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

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

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