A particular messaging protocol will likely provide a number of contact lists to a client, e.g. the list of subscribed contacts. These are the server defined lists (Handle_Type_List).

Telepathy provides for several server-defined lists, but not all of them may be implemented by a given protocol, or even a given version of a protocol server. If you attempt to open a channel for a list that doesn't exists, an error will be returned. This error is not fatal, it simply means that list doesn't exist.

Telepathy knows about the following server-defined lists:

Subscription to and from another user's presence is handled via the the subscribe and publish contact lists.

The subscribe list is the list of contacts for whom you receive, or would like to receive, presence information. This list is split into two sub-lists: members, contacts who's presence you receive; and remote pending, contacts who's presence you've requested but is pending approval.

The publish list is the list of contacts for whom you make available, or are requesting, presence information. This list is also split into two sub-lists: members, contacts to whom you show your presence; and local pending, contacts who are requesting your presence, pending your approval.

Table 6-3 summarises these lists.

User-defined groups are the groups that a user places their contacts into. Not all protocols may support the concept of user-defined groups. In some protocols (e.g. XMPP) a contact may possibly be in more than one group.

Channels will be set up for user-defined groups as they are discovered by the connection. Thus the currently configured groups can be discovered at any time by checking the Channels property or connecting to the NewChannels signal on the Requests interface (see Section 6.2.2 ― The NewChannels Signal).

This returns a list of Channel_Details, which gives the channel object and a map of properties for the channel. This map always contains the properties Channel.ChannelType, Channel.TargetHandleType, Channel.TargetHandle, Channel.TargetID, and Channel.Requested. Filtering on Channel.ChannelType equals Channel.Type.ContactList and Channel.TargetHandleType equals Handle_Type_Group will yield the user-defined contact groups (demonstrated in Example 6-9).

static void
new_channels_cb (TpConnection *conn,
    const GPtrArray *channels,
    gpointer user_data,
    GObject *weak_obj)
{
  int i;
  GError *error = NULL;

  /* @channels has the D-Bus type a(oa{sv}), which decomposes to:
   *  - a GPtrArray containing a GValueArray for each channel
   *  - each GValueArray contains
   *     - an object path
   *     - an a{sv} map
   */
  for (i = 0; i < channels->len; i++)
    {
      GValueArray *channel = g_ptr_array_index (channels, i);
      char *object_path;
      GHashTable *map;

      const char *channel_type, *target_id;
      int handle_type;

      tp_value_array_unpack (channel, 2,
          &object_path,
          &map);

      channel_type = tp_asv_get_string (map, TP_PROP_CHANNEL_CHANNEL_TYPE);
      handle_type = tp_asv_get_uint32 (map, TP_PROP_CHANNEL_TARGET_HANDLE_TYPE,
          NULL);
      target_id = tp_asv_get_string (map, TP_PROP_CHANNEL_TARGET_ID);

      /* ensure this channel is a contact group */
      if (!tp_strdiff (channel_type, TP_IFACE_CHANNEL_TYPE_CONTACT_LIST) &&
          handle_type == TP_HANDLE_TYPE_GROUP)
        {
          g_print ("Got user-defined contact group: %s\n", target_id);
        }
    }
}