[Telepathy-commits] [telepathy-doc/master] Presence updates

[Davyd Madeley]

---
 docs/book/C/connection.xml                      |   41 +++++++++++++++++++---
 docs/examples/python_simple_presence/example.py |    3 +-
 2 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/docs/book/C/connection.xml b/docs/book/C/connection.xml
index 52bfd2a..6c2bef3 100644
--- a/docs/book/C/connection.xml
+++ b/docs/book/C/connection.xml
@@ -493,18 +493,47 @@
        <methodname>SetPresence</methodname> method. Parameters are a status
        identifier (e.g. available, away, hidden) and an optional status message
        (e.g. &quot;At the Movies&quot;). Valid status identifiers for this
-       connection can be retrieved using the <property>Statuses</property>.
+       connection can be retrieved using the <property>Statuses</property>
+       property. This is shown in
+       <xref linkend="ex.connection.presence.set-presence"/>.
       </para>
+
+      <example id="ex.connection.presence.set-presence"
+               file="python_simple_presence/example.py">
+       <title>Requesting the Statuses and Setting Our Presence</title>
+      </example>
+
      </sect3>
     </sect2>
 
-    <!--
     <sect2>
-      <title>Presence Example</title>
-      <para>This example sets the presence for a jabber account, by calling the <methodname>SetPresence()</methodname> method of the <interfacename>Connection</interfacename>'s <interfacename>SimplePresence</interfacename> interface, using telepathy-glib.</para>
-      <para><ulink url="&url_examples_base;set_presence">Source Code</ulink></para>
+     <title>Retrieving Contacts' Presence</title>
+
+     <tip>
+      <para>
+       Many of the common requests that are made when a Telepathy client
+       starts up (e.g. aliases, avatars, presence) can be batched together
+       in a call to <methodname>Contacts.GetContactAttributes</methodname>.
+      </para>
+      <para>
+       See <xref linkend="sect.connection.contacts"/> for more information.
+      </para>
+     </tip>
+
+     <para>
+      The presence for a list of contact handles can be retrieved with the
+      <methodname>GetPresences</methodname> method call. This method call
+      takes an array of handles of type <type>Handle_Type_Contact</type>
+      and returns a map of those handles to <type>Simple_Presence</type>
+      structs.
+     </para>
+
+     <para>
+      Presence updates can be tracked by connecting the
+      <methodname>PresencesChanged</methodname> signal.
+     </para>
+
     </sect2>
-    -->
 
   </sect1>
 
diff --git a/docs/examples/python_simple_presence/example.py b/docs/examples/python_simple_presence/example.py
index 2d2c117..55ba1a1 100755
--- a/docs/examples/python_simple_presence/example.py
+++ b/docs/examples/python_simple_presence/example.py
@@ -169,6 +169,7 @@ class Example (object):
                                       'known')
 
         if CONNECTION_INTERFACE_SIMPLE_PRESENCE in interfaces:
+            # begin ex.connection.presence.set-presence
             # request the statuses
             print 'Requesting statuses...'
             conn[DBUS_PROPERTIES].Get(CONNECTION_INTERFACE_SIMPLE_PRESENCE,
@@ -177,13 +178,13 @@ class Example (object):
                                     error_handler = self.error_cb)
 
             # set our presence
-            # FIXME: doesn't like this interface
             print 'Setting presence...'
             conn[CONNECTION_INTERFACE_SIMPLE_PRESENCE].SetPresence(
                                     'away',
                                     'At the Movies',
                                     reply_handler = self.generic_reply,
                                     error_handler = self.error_cb)
+            # end ex.connection.presence.set-presence
 
         if CONNECTION_INTERFACE_CONTACTS in interfaces:
             print 'Requesting contact attribute interfaces...'
-- 
1.5.6.5