[Telepathy-commits] [telepathy-doc/master] Retrieving user defined lists

[Davyd Madeley]

---
 docs/book/C/channel.xml                         |   40 +++++++++++++++++++++-
 docs/examples/python_simple_presence/example.py |   25 +++++++++++++-
 2 files changed, 61 insertions(+), 4 deletions(-)

diff --git a/docs/book/C/channel.xml b/docs/book/C/channel.xml
index fadbfb6..edd7ae5 100644
--- a/docs/book/C/channel.xml
+++ b/docs/book/C/channel.xml
@@ -289,13 +289,14 @@
      <type>Handle_Type_List</type> (for
      <link linkend="sect.channel.contactlist.server-defined">server defined
      lists</link>) or
-     <type>Handle_Type_Group</type> (for a user defined list of contacts).
+     <type>Handle_Type_Group</type> (for a
+     <link linkend="sect.channel.contactlist.user-defined">user defined list of contacts</link>).
      The handle can be retrieved using the
      <methodname>RequestHandles</methodname> method on the Connection.
     </para>
 
     <para>
-     To request a contact list, 3 properties must be provided to
+     To request a contact list, three properties must be provided to
      <methodname>EnsureChannel</methodname>
      (see <xref linkend="sec-channel-requesting"/>): the channel type
      (org.freedesktop.Telepathy.Channel.Type.ContactList), the target handle
@@ -440,6 +441,41 @@
 
      </variablelist>
     </sect2>
+
+    <sect2 id="sect.channel.contactlist.user-defined">
+     <title>User Defined Groups</title>
+
+     <para>
+      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.
+     </para>
+
+     <para>
+      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 <property>Channels</property>
+      property or connecting to the <methodname>NewChannels</methodname>
+      signal on the <interfacename>Requests</interfacename> interface.
+     </para>
+
+     <para>
+      This returns a list of <type>Channel_Details</type>, which gives the
+      channel object and a map of properties for the channel. This map
+      always contains the properties
+      <property>Channel.ChannelType</property>,
+      <property>Channel.TargetHandleType</property>,
+      <property>Channel.TargetHandle</property>,
+      <property>Channel.TargetID</property>, and
+      <property>Channel.Requested</property>.
+      Filtering on <property>Channel.ChannelType</property> equals
+      <interfacename>Channel.Type.ContactList</interfacename> and
+      <property>Channel.TargetHandleType</property> equals
+      <type>Handle_Type_Group</type> will yield the user-defined contact
+      groups.
+     </para>
+    </sect2>
   
   </sect1>
 
diff --git a/docs/examples/python_simple_presence/example.py b/docs/examples/python_simple_presence/example.py
index 55ba1a1..2c03228 100755
--- a/docs/examples/python_simple_presence/example.py
+++ b/docs/examples/python_simple_presence/example.py
@@ -19,7 +19,8 @@ from telepathy.interfaces import CONNECTION_MANAGER, \
                                  CHANNEL_INTERFACE_GROUP
 from telepathy.constants import CONNECTION_STATUS_CONNECTED, \
                                 CONNECTION_STATUS_DISCONNECTED, \
-                                CONNECTION_HANDLE_TYPE_LIST
+                                HANDLE_TYPE_LIST, \
+                                HANDLE_TYPE_GROUP
 
 DBUS_PROPERTIES = 'org.freedesktop.DBus.Properties'
 
@@ -127,6 +128,8 @@ class Example (object):
                 # end ex.channel.groups.getting-members
 
             def get_contact_attributes_cb (self, attributes):
+                return # DEBUG
+
                 print '-' * 78
                 print self.group
                 print '-' * 78
@@ -146,7 +149,7 @@ class Example (object):
             print "Ensuring channel to %s..." % group
             conn[CONNECTION_INTERFACE_REQUESTS].EnsureChannel({
                 CHANNEL + '.ChannelType'     : CHANNEL_TYPE_CONTACT_LIST,
-                CHANNEL + '.TargetHandleType': CONNECTION_HANDLE_TYPE_LIST,
+                CHANNEL + '.TargetHandleType': HANDLE_TYPE_LIST,
                 CHANNEL + '.TargetID'        : group,
                 },
                 reply_handler = ensure_channel_cb(self, group),
@@ -168,6 +171,15 @@ class Example (object):
                                       'deny',
                                       'known')
 
+            # get the open channels
+            conn[CONNECTION_INTERFACE_REQUESTS].connect_to_signal(
+                                    'NewChannels',
+                                    self.get_channels_cb)
+            conn[DBUS_PROPERTIES].Get(CONNECTION_INTERFACE_REQUESTS,
+                                    'Channels',
+                                    reply_handler = self.get_channels_cb,
+                                    error_handler = self.error_cb)
+
         if CONNECTION_INTERFACE_SIMPLE_PRESENCE in interfaces:
             # begin ex.connection.presence.set-presence
             # request the statuses
@@ -193,6 +205,15 @@ class Example (object):
                                     reply_handler = self.get_contact_ifaces_cb,
                                     error_handler = self.error_cb)
 
+    def get_channels_cb (self, channels):
+        for channel, props in channels:
+            # find the group channels
+            if props[CHANNEL + '.ChannelType'] != CHANNEL_TYPE_CONTACT_LIST or \
+               props[CHANNEL + '.TargetHandleType'] != HANDLE_TYPE_GROUP:
+                continue
+
+            print 'GROUP: Got channel %s: %s' % (channel, props[CHANNEL + '.TargetID'])
+
     def get_statuses_cb (self, value):
         print "Statuses:"
 
-- 
1.5.6.5