Contact Groups

The Group interface is implemented by several channel types including contact list channels and multi-user chat channels.

For any given group there may be current members, local pending members and remote pending members. These are respectively accessed via the Members, LocalPendingMembers and RemotePendingMembers D-Bus properties.

Members is a list of handles of members who are currently part of this channel. This might be contacts in a contact list or participants in a multi-user chat. The AddMembers and RemoveMembers (or RemoveMembersWithReason) may be used to manipulate this list. Note that AddMembers may move a member onto the RemotePendingMembers list.

LocalPendingMembers is a list of members who are pending the user's approval (e.g. to subscribe to your presence, join a chatroom, etc.). Members are approved using the AddMembers method, and declined using the RemoveMembers method. As well as handles, the LocalPendingMembers provides a handle to the actor that made the request and a reason for the change (which may be empty).

RemotePendingMembers is a list of contacts who are pending another approval to be added to the channel (e.g. a remote user allowing subscription to their presence).

If a person has multiple instant message accounts, for instance via different protocols, Telepathy has no way of knowing that these are actually the same person, and no way for your application to tell Telepathy this. Therefore, client applications should track this information if necessary.

Information about a list of contacts can be looked up using the connection's Contacts interface. This is documented in Section 7.1 ― Contacts.

Example 6-10 shows how to retrieve a list of handles for current members of a group (in this case a contact list).

Example 6-10 Retrieving the Members of a Group

    # request the list of members
    channel[DBUS_PROPERTIES].Get(CHANNEL_INTERFACE_GROUP,
                             'Members',
                             reply_handler = self.members_cb,
                             error_handler = self.parent.error_cb)

def members_cb (self, handles):
    # request information for this list of handles using the
    # Contacts interface
    conn[CONNECTION_INTERFACE_CONTACTS].GetContactAttributes(
        handles, [
            CONNECTION,
            CONNECTION_INTERFACE_ALIASING,
            CONNECTION_INTERFACE_SIMPLE_PRESENCE,
        ],
        False,
        reply_handler = self.get_contact_attributes_cb,
        error_handler = self.parent.error_cb)

Complete Source Code

6.4.1. telepathy-glib

telepathy-glib's TpChannel proxy provides a number of functions to access the group's members (if available). These can be made once the channel proxy has entered the ready state (see Section 6.1.3 ― telepathy-glib).

The function tp_channel_group_get_members returns the set of contact handles stored in the Members property as a set of integer handles (TpIntSet). Similarly, the tp_channel_group_get_local_pending and tp_channel_group_get_remote_pending functions return the contact handles for LocalPendingMembers and RemotePendingMembers respectively. If the channel is not a Group these functions return NULL.

See Section 7.1.2 ― telepathy-glib — TpContact for how to set up TpContact objects for each handle in a Group.

The function tp_channel_group_get_local_pending_info is used to retrieve the additional information about a specific local pending contact: the actor handle, the reason and the message (the other entries of Local_Pending_Info).

Rather than having to connect to the D-Bus signal, changes to the membership of the channel are signalled with the group-members-changed signal. This provides lists of members that have been added and removed along with a reason and an actor.

Telepathy Developer's Manual

Contact Groups

6.4.1. telepathy-glib