Group and Conference interfaces on Channels

Group and Conference interfaces on Channels — client-side wrappers for Group and Conference

Functions

Object Hierarchy


Includes

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

Description

Many Telepathy Channel objects can be seen as representing groups or sets of contacts. The Telepathy specification represents this by a common interface, Group. This section documents the auto-generated C wrappers for the Group interface.

Contacts can be in four states:

  • in the group (the "members" set)

  • "local pending" (waiting to be added to the group by the local client calling AddMembers())

  • "remote pending" (waiting to be added to the group by some other action, probably by someone else)

  • no relationship with the group at all

For instance, chatrooms implement the Group interface. Contacts in the chatroom are members, and contacts who we've invited to the group, or contacts who've requested permission to join, are remote pending. If the local user has been invited by another contact, they will appear in the local-pending set until they accept or decline the invitation.

Some Group channels also have the Conference interface, representing a group which can be initiated by upgrading or merging one or more 1-1 channels.

Functions

tp_cli_channel_interface_group1_call_add_members ()

TpProxyPendingCall *
tp_cli_channel_interface_group1_call_add_members
                               (TpChannel *proxy,
                                gint timeout_ms,
                                const GArray *in_Contacts,
                                const gchar *in_Message,
                                tp_cli_channel_interface_group1_callback_for_add_members callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a AddMembers method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Invite all the given contacts into the channel, or accept requests for channel membership for contacts on the pending local list.</p> <p>A message may be provided along with the request, which will be sent to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this message should be provided.</p> <p>Attempting to add contacts who are already members is allowed; connection managers must silently accept this, without error.</p>

Parameters

proxy

the TpProxy

 

timeout_ms

the timeout in milliseconds, or -1 to use the default

 

in_Contacts

Used to pass an 'in' argument: An array of contact handles to invite to the channel

 

in_Message

Used to pass an 'in' argument: A string message, which can be blank if desired

 

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_group1_call_remove_members ()

TpProxyPendingCall *
tp_cli_channel_interface_group1_call_remove_members
                               (TpChannel *proxy,
                                gint timeout_ms,
                                const GArray *in_Contacts,
                                const gchar *in_Message,
                                guint in_Reason,
                                tp_cli_channel_interface_group1_callback_for_remove_members callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a RemoveMembers method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Requests the removal of contacts from a channel, reject their request for channel membership on the pending local list, or rescind their invitation on the pending remote list.</p> <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is in a Group, it can be removed via this method, in order to leave the group gracefully. This is the recommended way to leave a chatroom.</p> <p>Accordingly, connection managers SHOULD support doing this, regardless of the value of <tp:member-ref>GroupFlags</tp:member-ref>. If doing so fails with PermissionDenied, this is considered to a bug in the connection manager, but clients MUST recover by falling back to closing the channel with the <tp:dbus-ref namespace="im.telepathy.v1.Channel">Close</tp:dbus-ref> method.</p> <p>Removing any contact from the local pending list is always allowed. Removing contacts other than the <tp:member-ref>SelfHandle</tp:member-ref> from the channel's members is allowed if and only if Channel_Group_Flag_Can_Remove is in the <tp:member-ref>GroupFlags</tp:member-ref>, while removing contacts other than the <tp:member-ref>SelfHandle</tp:member-ref> from the remote pending list is allowed if and only if Channel_Group_Flag_Can_Rescind is in the <tp:member-ref>GroupFlags</tp:member-ref>.</p> <p>A message may be provided along with the request, which will be sent to the server if supported. See the Channel_Group_Flag_Message_Remove, Channel_Group_Flag_Message_Depart, Channel_Group_Flag_Message_Reject and Channel_Group_Flag_Message_Rescind <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this message should be provided.</p> <p>The reason code may be ignored if the underlying protocol is unable to represent the given reason.</p>

Parameters

proxy

the TpProxy

 

timeout_ms

the timeout in milliseconds, or -1 to use the default

 

in_Contacts

Used to pass an 'in' argument: An array of contact handles to remove from the channel

 

in_Message

Used to pass an 'in' argument: A string message, which can be blank if desired

 

in_Reason

Used to pass an 'in' argument: A reason for the change (TpChannelGroupChangeReason)

 

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_group1_callback_for_add_members ()

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

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

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

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

TpProxySignalConnection *
tp_cli_channel_interface_group1_connect_to_group_flags_changed
                               (TpChannel *proxy,
                                tp_cli_channel_interface_group1_signal_callback_group_flags_changed callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object,
                                GError **error);

Connect a handler to the signal GroupFlagsChanged.

Emitted when the flags as retrieved by the <tp:member-ref>GroupFlags</tp:member-ref> property are changed. The user interface should be updated as appropriate.

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_interface_group1_connect_to_members_changed ()

TpProxySignalConnection *
tp_cli_channel_interface_group1_connect_to_members_changed
                               (TpChannel *proxy,
                                tp_cli_channel_interface_group1_signal_callback_members_changed callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object,
                                GError **error);

Connect a handler to the signal MembersChanged.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when contacts join any of the three lists (members, local pending or remote pending) or when they leave any of the three lists.</p> <p>All channel-specific handles that are mentioned in this signal MUST be represented in the value of the <tp:member-ref>HandleOwners</tp:member-ref> property.</p>

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_interface_group1_signal_callback_group_flags_changed ()

void
(*tp_cli_channel_interface_group1_signal_callback_group_flags_changed)
                               (TpChannel *proxy,
                                guint arg_Added,
                                guint arg_Removed,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal GroupFlagsChanged.

Parameters

proxy

The proxy on which tp_cli_channel_interface_group1_connect_to_group_flags_changed() was called

 

arg_Added

A bitwise OR of the flags which have been set (TpChannelGroupFlags)

 

arg_Removed

A bitwise OR of the flags which have been cleared (TpChannelGroupFlags)

 

user_data

User-supplied data

 

weak_object

User-supplied weakly referenced object

 

tp_cli_channel_interface_group1_signal_callback_members_changed ()

void
(*tp_cli_channel_interface_group1_signal_callback_members_changed)
                               (TpChannel *proxy,
                                const GArray *arg_Added,
                                const GArray *arg_Removed,
                                const GArray *arg_Local_Pending,
                                const GArray *arg_Remote_Pending,
                                GHashTable *arg_Details,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal MembersChanged.

Parameters

proxy

The proxy on which tp_cli_channel_interface_group1_connect_to_members_changed() was called

 

arg_Added

A list of members added to the channel

 

arg_Removed

A list of members removed from the channel

 

arg_Local_Pending

A list of members who are pending local approval

 

arg_Remote_Pending

A list of members who are pending remote approval

 

arg_Details

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Information about the change, which may include the following well-known keys:</p> <dl> <dt>actor (u — <tp:type>Contact_Handle</tp:type>)</dt> <dd>The contact handle of the person who made the change; 0 or omitted if unknown or not applicable.</dd> <dt>change-reason (u — <tp:type>Channel_Group_Change_Reason</tp:type>)</dt> <dd>A reason for the change.</dd> <dt>contact-ids (a{us} — <tp:type>Handle_Identifier_Map</tp:type>)</dt> <dd> <p>The string identifiers for handles mentioned in this signal, to give clients the minimal information necessary to react to the event without waiting for round-trips. Connection managers SHOULD include the identifiers for members added to the group and for the actor (if any); they MAY omit the identifiers for handles which have been removed from the group.</p> <tp:rationale> <p>On IRC, an event such as a netsplit could cause the vast majority of a channel to leave. Given that clients should already know the identifiers of a channel's members, including potentially hundreds of strings in the netsplit signal is unnecessary.</p> </tp:rationale> <p>Clients MUST NOT assume that the presence or absence of a handle in this mapping is meaningful. This mapping is merely an optimization for round-trip reduction, and connection managers MAY add additional handles, omit some handles, or omit the mapping completely.</p> </dd> <dt>message (s)</dt> <dd>A string message from the server regarding the change</dd> <dt>error (s — <tp:type>DBus_Error_Name</tp:type>)</dt> <dd>A (possibly implementation-specific) DBus error describing the change, providing more specific information than the <tp:type>Channel_Group_Change_Reason</tp:type> enum allows. This MUST only be present if it is strictly more informative than 'change-reason'; if present, 'change-reason' MUST be set to the closest available reason. <tp:rationale> A SIP connection manager might want to signal &quot;402 Payment required&quot; as something more specific than Error or Permission_Denied so that a SIP-aware UI could handle it specially; including a namespaced error permits this to be done without <tp:type>Channel_Group_Change_Reason</tp:type> being extended to encompass every error any CM ever wants to report. </tp:rationale> </dd> <dt>debug-message (s)</dt> <dd>Debugging information on the change. SHOULD NOT be shown to users in normal circumstances.</dd> </dl>

 

user_data

User-supplied data

 

weak_object

User-supplied weakly referenced object

 

tp_cli_channel_interface_group1_connect_to_handle_owners_changed ()

TpProxySignalConnection *
tp_cli_channel_interface_group1_connect_to_handle_owners_changed
                               (TpChannel *proxy,
                                tp_cli_channel_interface_group1_signal_callback_handle_owners_changed callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object,
                                GError **error);

Connect a handler to the signal HandleOwnersChanged.

<p>Emitted whenever the <tp:member-ref>HandleOwners</tp:member-ref> property changes.</p>

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_interface_group1_signal_callback_handle_owners_changed ()

void
(*tp_cli_channel_interface_group1_signal_callback_handle_owners_changed)
                               (TpChannel *proxy,
                                GHashTable *arg_Added,
                                const GArray *arg_Removed,
                                GHashTable *arg_Identifiers,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal HandleOwnersChanged.

Parameters

proxy

The proxy on which tp_cli_channel_interface_group1_connect_to_handle_owners_changed() was called

 

arg_Added

A map from channel-specific handles to their owners, in which the keys include all the handles that were added to the keys of the HandleOwners property, and all the handles in that property whose owner has changed

 

arg_Removed

The channel-specific handles that were removed from the keys of the HandleOwners property, as a result of the contact leaving this group in a previous <tp:member-ref>MembersChanged</tp:member-ref> signal

 

arg_Identifiers

The string identifiers for handles mentioned in this signal, to give clients the minimal information necessary to create contacts without waiting for round-trips. Connection managers MUST include at least the identifiers for all handles in the Added map, and MAY include those from Removed array.

 

user_data

User-supplied data

 

weak_object

User-supplied weakly referenced object

 

tp_cli_channel_interface_group1_connect_to_self_contact_changed ()

TpProxySignalConnection *
tp_cli_channel_interface_group1_connect_to_self_contact_changed
                               (TpChannel *proxy,
                                tp_cli_channel_interface_group1_signal_callback_self_contact_changed callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object,
                                GError **error);

Connect a handler to the signal SelfContactChanged.

<p>Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> property changes.</p> <p>Clients can assume this signal is emitted by the Connection Manager if the <tp:member-ref>MemberIdentifiers</tp:member-ref> property exists. </p>

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_interface_group1_signal_callback_self_contact_changed ()

void
(*tp_cli_channel_interface_group1_signal_callback_self_contact_changed)
                               (TpChannel *proxy,
                                guint arg_Self_Handle,
                                const gchar *arg_Self_ID,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal SelfContactChanged.

Parameters

proxy

The proxy on which tp_cli_channel_interface_group1_connect_to_self_contact_changed() was called

 

arg_Self_Handle

The new value of the SelfHandle property. (TpContactHandle)

 

arg_Self_ID

The new value of the SelfHandle property's identifier.

 

user_data

User-supplied data

 

weak_object

User-supplied weakly referenced object

 

tp_svc_channel_interface_group1_emit_self_contact_changed ()

void
tp_svc_channel_interface_group1_emit_self_contact_changed
                               (gpointer instance,
                                guint arg_Self_Handle,
                                const gchar *arg_Self_ID);

Type-safe wrapper around g_signal_emit to emit the SelfContactChanged signal on interface im.telepathy.v1.Channel.Interface.Group1.

Parameters

instance

The object implementing this interface

 

arg_Self_Handle

guint (FIXME, generate documentation)

 

arg_Self_ID

const gchar * (FIXME, generate documentation)

 

tp_cli_channel_interface_conference1_connect_to_channel_merged ()

TpProxySignalConnection *
tp_cli_channel_interface_conference1_connect_to_channel_merged
                               (TpChannel *proxy,
                                tp_cli_channel_interface_conference1_signal_callback_channel_merged callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object,
                                GError **error);

Connect a handler to the signal ChannelMerged.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when a new channel is added to the value of <tp:member-ref>Channels</tp:member-ref>.</p>

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_interface_conference1_connect_to_channel_removed ()

TpProxySignalConnection *
tp_cli_channel_interface_conference1_connect_to_channel_removed
                               (TpChannel *proxy,
                                tp_cli_channel_interface_conference1_signal_callback_channel_removed callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object,
                                GError **error);

Connect a handler to the signal ChannelRemoved.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when a channel is removed from the value of <tp:member-ref>Channels</tp:member-ref>, either because it closed or because it was split using the <tp:dbus-ref namespace="im.telepathy.v1.Channel.Interface">Splittable1.Split</tp:dbus-ref> method.</p> <p>If a channel is removed because it was closed, <tp:dbus-ref namespace="imt1.Channel">Closed</tp:dbus-ref> should be emitted before this signal.</p>

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_interface_conference1_signal_callback_channel_merged ()

void
(*tp_cli_channel_interface_conference1_signal_callback_channel_merged)
                               (TpChannel *proxy,
                                const gchar *arg_Channel,
                                guint arg_Channel_Specific_Handle,
                                GHashTable *arg_Properties,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal ChannelMerged.

Parameters

proxy

The proxy on which tp_cli_channel_interface_conference1_connect_to_channel_merged() was called

 

arg_Channel

The channel that was added to <tp:member-ref>Channels</tp:member-ref>.

 

arg_Channel_Specific_Handle

A new channel-specific handle for the <tp:dbus-ref namespace="imt1.Channel">TargetHandle</tp:dbus-ref> of <var>Channel</var>, as will appear in <tp:member-ref>OriginalChannels</tp:member-ref>, or <tt>0</tt> if a global handle is used for <var>Channel</var>'s TargetHandle on the <tp:dbus-ref namespace="imt1.Channel.Interface">Group1</tp:dbus-ref> interface of this channel. (TpContactHandle)

 

arg_Properties

<var>Channel</var>'s immutable properties.

 

user_data

User-supplied data

 

weak_object

User-supplied weakly referenced object

 

tp_cli_channel_interface_conference1_signal_callback_channel_removed ()

void
(*tp_cli_channel_interface_conference1_signal_callback_channel_removed)
                               (TpChannel *proxy,
                                const gchar *arg_Channel,
                                GHashTable *arg_Details,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal ChannelRemoved.

Parameters

proxy

The proxy on which tp_cli_channel_interface_conference1_connect_to_channel_removed() was called

 

arg_Channel

The channel that was removed from <tp:member-ref>Channels</tp:member-ref>.

 

arg_Details

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Additional information about the removal, which may include the same well-known keys as the Details argument of <tp:dbus-ref namespace="imt1.Channel.Interface.Group1">MembersChanged</tp:dbus-ref>, with the same semantics.

 

user_data

User-supplied data

 

weak_object

User-supplied weakly referenced object

 

Types and Values

See Also

TpChannel