[Telepathy-commits] [telepathy-doc/master] Section on Receiving messages

[Davyd Madeley]

---
 docs/book/C/channel.xml                         |   61 ++++++++++++++++++++++-
 docs/examples/python_iface_messaging/example.py |    5 ++-
 2 files changed, 63 insertions(+), 3 deletions(-)

diff --git a/docs/book/C/channel.xml b/docs/book/C/channel.xml
index 7ea4ebb..b283d80 100644
--- a/docs/book/C/channel.xml
+++ b/docs/book/C/channel.xml
@@ -633,7 +633,7 @@
        <row>
         <entry>Transient Chatroom</entry>
 	<entry>MSN conversation</entry>
-	<entry>Handle_Type_None</entry>
+	<entry><type>Handle_Type_None</type></entry>
 	<entry><interfacename>Group</interfacename></entry>
 	<entry>Appears as an anonymous channel.</entry>
        </row>
@@ -733,7 +733,7 @@
       <ulink url="http://xmpp.org/extensions/xep-0071.html">XHTML-IM</ulink>.
      </para>
 
-     <sect3>
+     <sect3 id="sect.channel.text.messages.format">
       <title>Message Structure</title>
 
       <para>
@@ -834,6 +834,63 @@
         </tgroup>	
        </informaltable>
       </example>
+
+      <para>
+       Alternatives with the same name should be ordered from highest
+       fidelity to lowest fidelity (i.e. rich text before plain text).
+       Clients should display the first alternative they understand.
+      </para>
+
+     </sect3>
+
+     <sect3 id="sect.channel.text.messages.receiving">
+      <title>Receiving Messages</title>
+
+      <para>
+       When a remote user initiates a new text chat, Telepathy will
+       automatically create a new channel for the chat, who's creation will
+       be heralded by the <methodname>NewChannels</methodname> signal.
+       Filter on the channels given for channels of type
+       <type>Channel_Type_Text</type>.
+       <xref linkend="ex.channel.text.messages.newchannels"/> shows
+       how to discover this channel.
+      </para>
+
+      <example id="ex.channel.text.messages.receiving.newchannels"
+               file="python_iface_messaging/example.py">
+        <title>Discovering Incoming Channels</title>
+      </example>
+
+      <para>
+       Set up a D-Bus proxy for the channel, like you would for any other
+       channel (see <xref linkend="sec-channel-requesting"/>). Check to
+       ensure that the <interfacename>Messages</interfacename> interface
+       is available.
+      </para>
+
+      <para>
+       Incoming messages are announced with the
+       <methodname>MessageReceived</methodname> signal, which places them on
+       the pending message queue. To remove messages from the pending
+       message queue, they must be acknowledged with
+       <methodname>Text.AcknowledgePendingMessages</methodname>. There will
+       already be messages pending, the ones that caused the creation of
+       the channel. These can be accessed via the
+       <property>PendingMessages</property> property.
+       See <xref linkend="ex.channel.text.messages.receiving.main"/>.
+      </para>
+
+      <para>
+       The message id to acknowledge the message is contained in the headers
+       of the message as the key <literal>pending-message-id</literal>
+       (see <xref linkend="sect.channel.text.messages.format"/>).
+      </para>
+      
+      <example id="ex.channel.text.messages.receiving.main"
+               file="python_iface_messaging/example.py">
+        <title>Setting Up and Receiving Messages</title>
+      </example>
+
      </sect3>
 
     </sect2>
diff --git a/docs/examples/python_iface_messaging/example.py b/docs/examples/python_iface_messaging/example.py
index 2fefd88..8d1022d 100755
--- a/docs/examples/python_iface_messaging/example.py
+++ b/docs/examples/python_iface_messaging/example.py
@@ -32,7 +32,7 @@ class TextChannel (telepathy.client.Channel):
         channel[DBUS_PROPERTIES].Get(CHANNEL, 'Interfaces',
                                      reply_handler = self.interfaces_cb,
                                      error_handler = self.parent.error_cb)
-
+    # begin ex.channel.text.messages.receiving.main
     def interfaces_cb (self, interfaces):
         channel = self
 
@@ -64,6 +64,7 @@ class TextChannel (telepathy.client.Channel):
         channel[CHANNEL_TYPE_TEXT].AcknowledgePendingMessages([msg_id],
             reply_handler = self.parent.generic_reply,
             error_handler = self.parent.error_cb)
+        # end ex.channel.text.messages.receiving.main
 
         print '-' * 78
         print 'Received Message:'
@@ -159,6 +160,7 @@ class Example (object):
         conn[CONNECTION].GetInterfaces(reply_handler = self.get_interfaces_cb,
                                        error_handler = self.error_cb)
 
+    # begin ex.channel.text.messages.receiving.newchannels
     def get_interfaces_cb (self, interfaces):
         conn = self.conn
 
@@ -176,6 +178,7 @@ class Example (object):
                 print 'New chat from %s' % props[CHANNEL + '.TargetID']
                 # let's hook up to this channel
                 TextChannel(self, channel)
+    # end ex.channel.text.messages.receiving.newchannels
 
 if __name__ == '__main__':
     import getpass
-- 
1.5.6.5