[telepathy-doc/master] More on receiving files

[Davyd Madeley]

---
 docs/book/C/contactinfo.xml  |    9 ++++++
 docs/book/C/filetransfer.xml |   59 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 0 deletions(-)

diff --git a/docs/book/C/contactinfo.xml b/docs/book/C/contactinfo.xml
index 139d7d0..097e2ab 100644
--- a/docs/book/C/contactinfo.xml
+++ b/docs/book/C/contactinfo.xml
@@ -241,6 +241,15 @@
     </para>
    </tip>
 
+   <para>
+    A <classname>TpChannel</classname>'s
+    <methodname>group-members-changed</methodname> signal can be used to
+    monitor the lifetime of a group. Members that have been
+    <parameter>added</parameter> can have their
+    <classname>TpContact</classname> requested.
+    <!-- FIXME: what happens to a TpContact when a member is removed -->
+   </para>
+
   </sect2>
 
  </sect1>
diff --git a/docs/book/C/filetransfer.xml b/docs/book/C/filetransfer.xml
index b6e836a..6853829 100644
--- a/docs/book/C/filetransfer.xml
+++ b/docs/book/C/filetransfer.xml
@@ -151,6 +151,65 @@
     </tgroup>
    </table>
 
+   <para>
+    If the user declines to receive the file, simply closing the channel
+    will cancel the transfer.
+   </para>
+
+  </sect2>
+
+  <sect2 id="table.filetransfer.receiving.accepting">
+   <title>Accepting The File</title>
+
+   <para>
+    Before calling <methodname>AcceptFile</methodname>, the client should
+    first connect the <methodname>FileTransferStateChanged</methodname>
+    signal.
+   </para>
+
+   <para>
+    <methodname>AcceptFile</methodname> takes as its arguments the type of
+    socket we wish to use to transfer the file from the Connection Manager
+    to the client. Different Connection Managers and different OS platforms
+    might support different socket options. The property
+    <property>AvailableSocketTypes</property> lists the supported socket
+    types and their access modes. This property would have been passed in
+    as one of the channel properties to
+    <methodname>NewChannels</methodname>.
+   </para>
+
+   <para>
+    <methodname>AcceptFile</methodname> also takes a requested initial
+    file offset (for continuations, if a partial transfer was deemed to
+    occur), or <literal>0</literal> for the whole file. Note that
+    this is a <emphasis>requested</emphasis> offset, and depending on the
+    protocol and sending client may not be honoured. Clients must check
+    <property>InitialOffset</property> property once the channel is open.
+   </para>
+
+   <para>
+    Calling <methodname>AcceptFile</methodname> will return the address of
+    a socket opened by the Connection Manager and put the channel into the
+    <emphasis>Pending</emphasis> state
+    (<type>File_Transfer_State_Pending</type>). However, you should not
+    attempt to open the socket yourself until the channel enters the
+    <emphasis>Open</emphasis> state (<type>File_Transfer_State_Open</type>).
+   </para>
+
+   <note>
+    <para>
+     The socket address returned by <methodname>AcceptFile</methodname> and
+     <methodname>ProvideFile</methodname> is a socket shared between the
+     client and the Connection Manager. It is not the address of the socket
+     between you and the remote client.
+    </para>
+    <para>
+     The file itself is transferred by the Connection Manager using the most
+     appropriate mechanism to reach the remote host, be it a peer-to-peer
+     socket, SOCKS5 proxy, using ICE or in-band via the server. A Telepathy
+     client doesn't have to be concerned with the mechanism.
+    </para>
+   </note>
   </sect2>
 
  </sect1>
-- 
1.5.6.5