[Telepathy-commits] [telepathy-spec/master] Updated main channel type docstring.

[Jonny Lamb]

Signed-off-by: Jonny Lamb <jonny.lamb at collabora.co.uk>
---
 spec/Channel_Type_FileTransfer.xml |   25 +++++++++++++++++++------
 1 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/spec/Channel_Type_FileTransfer.xml b/spec/Channel_Type_FileTransfer.xml
index 6aaa0fa..7c8d4f2 100644
--- a/spec/Channel_Type_FileTransfer.xml
+++ b/spec/Channel_Type_FileTransfer.xml
@@ -22,18 +22,31 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     tp:causes-havoc="experimental">
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
     <tp:docstring>
-      <p>A channel type for files offered for transferring.
-      The actual transmission of the data is done by reading or writing
-      a socket, the type of socket (local Unix, IPv4, etc.) when the File
-      channel is created.</p>
+      <p>A channel type for files offered for transferring. The
+      transmission of data between contacts is achieved by reading from
+      or writing to a socket. The type of the socket (local Unix, IPv4,
+      etc.) is decided on when the file transfer is offered.</p>
 
       <p>The Telepathy client should connect to the socket or address that
       the connection manager has set up and provided back to the clients
       through the two methods.</p>
 
-      <p>If something goes wrong with the transfer, you should call
+      <p>In order to send a file, one should request a FileTransfer channel
+      for a contact, and fill the madatory properties
+      (<tp:member-ref>Filename</tp:member-ref>, and
+      <tp:member-ref>Size</tp:member-ref>). After these are set, one should
+      call <tp:member-ref>OfferFile</tp:member-ref> to offer the transfer to
+      the contact.</p>
+
+      <p>In order to receive an incoming file transfer, one should call
+      <tp:member-ref>AcceptFile</tp:member-ref> and then wait until the state
+      changes to Open. At this point, the receiver must check the
+      <tp:member-ref>InitialOffset</tp:member-ref> property for a difference in
+      offset from the requested value in AcceptFile.</p>
+
+      <p>If something goes wrong with the transfer,
       <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>
-      on the channel.</p>
+      should be called on the channel.</p>
 
       <p>The File channel type may be requested for handles of type
       HANDLE_TYPE_CONTACT. If the channel is requested for any other
-- 
1.5.6.5