upgrade to new FT draft

git-svn-id: svn+ssh://svn.gnome.org/svn/empathy/trunk@1841 4ee84921-47dd-4033-b63a-18d7a039a3e4

2 files changed, 160 insertions, 96 deletions

diff --git a/extensions/Channel_Type_File.xml b/extensions/Channel_Type_File_Transfer.xml
index b8717ad04..4838f7f1d 100644
--- a/extensions/Channel_Type_File.xml
+++ b/extensions/Channel_Type_File_Transfer.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" ?>
-<node name="/Channel_Type_File" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+<node name="/Channel_Type_File_Transfer" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   <tp:copyright>
     Copyright (C) 2008 Collabora Limited
   </tp:copyright>
@@ -18,48 +18,67 @@ Library General Public License for more details.</p>
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
   </tp:license>
-  <interface name="org.freedesktop.Telepathy.Channel.Type.File.DRAFT"
+  <interface name="org.freedesktop.Telepathy.Channel.Type.FileTransfer.DRAFT"
     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>
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <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 or accepted.</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 Close
-      on the channel.</p>
+      <ul><li>In order to send a file, one should request a FileTransfer
+      channel for a contact, and fill the mandatory 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.</li>
+
+      <li>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. If the receiver is resuming a transfer then he or she
+      should set a non-zero Offset argument when calling
+      <tp:member-ref>AcceptFile</tp:member-ref>. When the state changes to Open,
+      the receiver must check the <tp:member-ref>InitialOffset</tp:member-ref>
+      property for a difference in offset from the requested value in
+      AcceptFile.</li></ul>
+
+      <p>If something goes wrong with the transfer,
+      <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>
+      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
-      handle type then the behviour is undefined.</p>
+      handle type then the behaviour is undefined.</p>
     </tp:docstring>
 
     <property name="State" type="u" tp:type="File_Transfer_State"
-      access="read">
+      access="read" tp:name-for-bindings="State">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The state of the file transfer as described by the
         File_Transfer_State enum.</p>
       </tp:docstring>
     </property>
 
-    <property name="ContentType" type="s" access="readwrite">
+    <property name="ContentType" type="s" access="read"
+      tp:name-for-bindings="Content_Type">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The file's MIME type. This cannot change once the channel has
         been created.</p>
 
         <p>This property is mandatory when requesting the channel with the
-        CreateChannels requests method. Protocols which do not have a
-        content-type property with file transfers should set this value to
-        application/octet-stream.</p>
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+        method. Protocols which do not have a content-type property with file
+        transfers should set this value to application/octet-stream.</p>
       </tp:docstring>
     </property>
 
-    <property name="Filename" type="s" access="readwrite">
+    <property name="Filename" type="s" access="read"
+      tp:name-for-bindings="Filename">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The name of the file on the sender's side. This is therefore given
         as a suggested filename for the receiver. This cannot change
@@ -70,12 +89,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         be set to monkey.pdf.</p>
 
         <p>This property is mandatory when requesting the channel with the
-        CreateChannels requests method. This property cannot be empty and
-        must be set to a sensible value.</p>
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+        method. This property cannot be empty and must be set to a sensible value.</p>
       </tp:docstring>
     </property>
 
-    <property name="Size" type="t" access="readwrite">
+    <property name="Size" type="t" access="read"
+      tp:name-for-bindings="Size">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The size of the file. If this property is set, then the file
         transfer is guaranteed to be this size. This cannot change once
@@ -87,51 +107,70 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         to the byte.</p>
 
         <p>This property is mandatory when requesting the channel with the
-        CreateChannels requests method. If this property is UINT64_MAX,
-        then its value is unspecified.</p>
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+        method. If this property is UINT64_MAX, then its value is
+        unspecified.</p>
       </tp:docstring>
     </property>
 
     <property name="ContentHashType" type="u" tp:type="File_Hash_Type"
-      access="readwrite">
+      access="read" tp:name-for-bindings="Content_Hash_Type">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>The type of the ContentHash property from values of the
-        File_Hash_Type enum.</p>
+        <p>The type of the <tp:member-ref>ContentHash</tp:member-ref> property.</p>
 
         <p>This property is optional when requesting the channel with the
-        CreateChannels requests method. However, if you wish to include the
-        ContentHash property you MUST also include this property. If you
-        omit this property from a CreateChannels method call then its value
-        will be assumed to be File_Hash_Type_None.</p>
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+        method. However, if you wish to include the <tp:member-ref>ContentHash</tp:member-ref>
+        property you MUST also include this property. If you omit this property from a
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+        method call then its value will be assumed to be File_Hash_Type_None.</p>
       </tp:docstring>
     </property>
 
-    <property name="ContentHash" type="s" access="readwrite">
+    <property name="ContentHash" type="s" access="read"
+      tp:name-for-bindings="Content_Hash">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Hash of the contents of the file transfer, of type described
-        in the value of the ContentHashType property.</p>
+        in the value of the <tp:member-ref>ContentHashType</tp:member-ref>
+        property.</p>
 
         <p>This property is optional when requesting the channel with the
-        CreateChannels requests method. Its value MUST correspond to the
-        appropriate type of the ContentHashType property. If the
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+        method. Its value MUST correspond to the appropriate type of the
+        <tp:member-ref>ContentHashType</tp:member-ref> property. If the
         ContentHashType property is not set, or set to File_Hash_Type_None,
         then this property will not even be looked at.</p>
       </tp:docstring>
     </property>
 
-    <property name="Description" type="s" access="readwrite">
+    <property name="Description" type="s" access="read"
+      tp:name-for-bindings="Description">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Description of the file transfer. This cannot change once the
         channel has been created.</p>
 
         <p>This property is optional when requesting the channel with the
-        CreateChannel requests method. If this property is an empty string,
-        then its value is unspecified.</p>
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+        method. If this property is an empty string, then its value is
+        unspecified.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="Date" type="t" access="read"
+      tp:type="Unix_Timestamp64" tp:name-for-bindings="Date">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The last modification time of the file being transferred. This
+        cannot change once the channel has been created</p>
+
+        <p>This property is optional when requesting the channel with the
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+        method.</p>
       </tp:docstring>
     </property>
 
     <property name="AvailableSocketTypes" type="a{uau}"
-      tp:type="Supported_Socket_Map" access="read">
+      tp:type="Supported_Socket_Map" access="read"
+      tp:name-for-bindings="Available_Socket_Types">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>A mapping from address types (members of Socket_Address_Type) to
         arrays of access-control type (members of Socket_Access_Control)
@@ -153,7 +192,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:docstring>
     </property>
 
-    <property name="TransferredBytes" type="t" access="read">
+    <property name="TransferredBytes" type="t" access="read"
+      tp:name-for-bindings="Transferred_Bytes">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The number of bytes that have been transferred at the time of
         requesting the property. This will be updated as the file transfer
@@ -161,15 +201,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:docstring>
     </property>
 
-    <property name="InitialOffset" type="t" access="read">
+    <property name="InitialOffset" type="t" access="read"
+      tp:name-for-bindings="Initial_Offset">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>The offset from the beginning of the file that the transfer should
-        start from. This should be checked by the receiver after the transfer
-        changes state from Accepted to Open.</p>
+        <p>The offset in bytes from where the file should be sent. This MUST
+        be checked by both the receiver and the sender after the state
+        becomes Open, but before any data is sent or received. Until the
+        state changes to Open, this property is undefined.</p>
 
-        <p>Before setting the State property to Open, the connection manager
-        MUST set the InitialOffset property. If there is no offset then this
-        value MUST be set to 0.</p>
+        <p>Before setting the <tp:member-ref>State</tp:member-ref> property to
+        Open, the connection manager MUST set the InitialOffset property,
+        possibly to 0.</p>
 
         <p>This property MUST NOT change after the state of the transfer has
         changed to Open.</p>
@@ -179,20 +221,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     <tp:enum name="File_Transfer_State" type="u">
       <tp:enumvalue suffix="None" value="0">
         <tp:docstring>
-          The file transfer is currently not set up correctly.
+          An invalid state type used as a null value. This value MUST NOT
+          appear in the State property.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Not_Offered" value="1">
         <tp:docstring>
-          The file transfer is waiting for the local user to offer the file
-          as a transfer.
+          The transfer is waiting for the local client to call the OfferFile
+          method, in order to offer a file to be transferred.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Accepted" value="2">
         <tp:docstring>
-          The file transfer has been accepted locally, but not currently open.
-          The transfer should now wait for the state to change to open and
-          check the offset value.
+          The client has accepted the incoming file transfer, but the transfer
+          is not open. The client should now wait for the state to change to Open
+          and check the offset value.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Local_Pending" value="3">
@@ -215,9 +258,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           The file transfer has been completed successfully.
         </tp:docstring>
       </tp:enumvalue>
-      <tp:enumvalue suffix="Canceled" value="7">
+      <tp:enumvalue suffix="Cancelled" value="7">
         <tp:docstring>
-          The file transfer has been canceled.
+          The file transfer has been cancelled.
         </tp:docstring>
       </tp:enumvalue>
     </tp:enum>
@@ -228,24 +271,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           No reason was specified.
         </tp:docstring>
       </tp:enumvalue>
+      <tp:enumvalue suffix="Requested" value="1">
+        <tp:docstring>
+          The change in state was requested.
+        </tp:docstring>
+      </tp:enumvalue>
       <tp:enumvalue suffix="Local_Stopped" value="1">
         <tp:docstring>
-          The file transfer was canceled by the local user.
+          The file transfer was cancelled by the local user.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Remote_Stopped" value="2">
         <tp:docstring>
-          The file transfer was canceled by the remote user.
+          The file transfer was cancelled by the remote user.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Local_Error" value="3">
         <tp:docstring>
-          The file transfer was canceled because of a local error.
+          The file transfer was cancelled because of a local error.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Remote_Error" value="4">
         <tp:docstring>
-          The file transfer was canceled because of a remote error.
+          The file transfer was cancelled because of a remote error.
         </tp:docstring>
       </tp:enumvalue>
     </tp:enum>
@@ -258,57 +306,60 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:enumvalue>
       <tp:enumvalue suffix="MD5" value="1">
         <tp:docstring>
-          MD5 digest as a string of 32 ASCII hex digits, which SHOULD be
-          lower-case if they are letters.
+          MD5 digest as a string of 32 ASCII hex digits.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="SHA1" value="2">
         <tp:docstring>
-          SHA1 digest as a string of ASCII hex digits, which SHOULD be
-          lower-case if they are letters.
+          SHA1 digest as a string of ASCII hex digits.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="SHA256" value="3">
         <tp:docstring>
-          SHA1 digest as a string of ASCII hex digits, which SHOULD be
-          lower-case if they are letters.
+          SHA256 digest as a string of ASCII hex digits.
         </tp:docstring>
       </tp:enumvalue>
     </tp:enum>
 
-    <method name="AcceptFile">
+    <method name="AcceptFile" tp:name-for-bindings="Accept_File">
       <tp:docstring>
-        Accept a file transfer that's in the "local pending" state. The file
-        transfer's state becomes accepted after this method is called. At this
-        point, the receiver must wait for the state to change to open. When this
-        happens, the InitialOffset property should be read to find from where the
-        file is actually being sent.
+        Accept a file transfer that's in the Local_Pending state. The file
+        transfer's state becomes Accepted after this method is called. At this
+        point, the receiver must wait for the state to change to Open, and then
+        <tp:member-ref>InitialOffset</tp:member-ref> should be checked in case
+        its value differs from the offset that was specified as an argument
+        to AcceptFile.
       </tp:docstring>
-      <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
+      <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type">
         <tp:docstring>
           The type of address the connection manager should listen on.
         </tp:docstring>
       </arg>
-      <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
+      <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control">
         <tp:docstring>
           The type of access control the connection manager should apply to
           the socket.
         </tp:docstring>
       </arg>
-      <arg direction="in" name="access_control_param" type="v">
+      <arg direction="in" name="Access_Control_Param" type="v">
         <tp:docstring>
           A parameter for the access control type, to be interpreted as
           specified in the documentation for the Socket_Access_Control enum.
         </tp:docstring>
       </arg>
-      <arg direction="in" name="offset" type="t">
+      <arg direction="in" name="Offset" type="t">
         <tp:docstring>
-          The offset in bytes of wthere the file tranfer should start from.
-          The offset is taken from the beginning of the file. Values of zero
-          will start the transfer from the beginning of the file.
+          The desired offset in bytes where the file transfer should start.
+          The offset is taken from the beginning of the file. Specifying an
+          offset of zero will start the transfer from the beginning of the
+          file. The offset that is actually given in the
+          <tp:member-ref>InitialOffset</tp:member-ref> property can differ
+          from this argument where the requested offset is not supported.
+          (For example, some protocols do not support offsets at all so
+          the InitialOffset property will always be 0.)
         </tp:docstring>
       </arg>
-      <arg direction="out" name="address" type="v">
+      <arg direction="out" name="Address" type="v">
         <tp:docstring>
           The address on which the connection manager will listen for
           connections for this file transfer.
@@ -323,38 +374,44 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+          <tp:docstring>
+            Your address type, access control, access control parameter,
+            offset, or a combination of all four is invalid.
+          </tp:docstring>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
           <tp:docstring>
-          The file transfer is not in the "local pending" state, which is the only
-          state this method makes sense.
+            The file transfer is not in the Local_Pending state, there isn't
+            or there is a local error with acquiring a socket.
           </tp:docstring>
         </tp:error>
       </tp:possible-errors>
     </method>
 
-    <method name="OfferFile">
+    <method name="OfferFile" tp:name-for-bindings="Offer_File">
       <tp:docstring>
-        Offer a file transfer that's in the "not offered" state. The file transfer
-        becomes remote pending after this method is called.
+        Offer a file transfer that's in the Not_Offered state. Open a socket
+        that the client can use to provide a file to the connection manager.
+        The channel MUST be in the Not_Offered state, and will change state
+        to Remote_Pending when this method is called.
       </tp:docstring>
-      <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
+      <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type">
         <tp:docstring>
           The type of address the connection manager should listen on.
         </tp:docstring>
       </arg>
-      <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
+      <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control">
         <tp:docstring>
           The type of access control the connection manager should apply to
           the socket.
         </tp:docstring>
       </arg>
-      <arg direction="in" name="access_control_param" type="v">
+      <arg direction="in" name="Access_Control_Param" type="v">
         <tp:docstring>
           A parameter for the access control type, to be interpreted as
           specified in the documentation for the Socket_Access_Control enum.
         </tp:docstring>
       </arg>
-      <arg direction="out" name="address" type="v">
+      <arg direction="out" name="Address" type="v">
         <tp:docstring>
           The address on which the connection manager will listen for
           connections for this file transfer.
@@ -367,44 +424,51 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
             The given address type or access-control mechanism is not supported.
           </tp:docstring>
         </tp:error>
-        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+          <tp:docstring>
+            Your address type, access control, access control parameter, or
+            a combination of all three is invalid.
+          </tp:docstring>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
           <tp:docstring>
-            The file transfer is not in the "not offered" state, or there isn't
-            enough information for the transfer to start.
+            The file transfer is not in the Not_Offered state, there isn't
+            enough information for the transfer to start, or a local error
+            with acquiring a socket.
           </tp:docstring>
         </tp:error>
       </tp:possible-errors>
     </method>
 
-    <signal name="FileTransferStateChanged">
+    <signal name="FileTransferStateChanged"
+      tp:name-for-bindings="File_Transfer_State_Changed">
       <tp:docstring>
         Emitted when the state of a file transfer changes.
       </tp:docstring>
-      <arg name="state" type="u" tp:type="File_Transfer_State">
+      <arg name="State" type="u" tp:type="File_Transfer_State">
         <tp:docstring>
           The new state of the file transfer; see the File_Transfer_State enumeration.
         </tp:docstring>
       </arg>
-      <arg name="reason" type="u" tp:type="File_Transfer_State_Change_Reason">
+      <arg name="Reason" type="u" tp:type="File_Transfer_State_Change_Reason">
         <tp:docstring>
           The reason for the state change; see the File_Transfer_State_Change_Reason
           enumeration.
           The value will always be File_Transfer_State_Change_Reason_None, except
-          when changing state to canceled.
+          when changing state to cancelled.
         </tp:docstring>
       </arg>
     </signal>
 
-    <signal name="TransferredBytesChanged">
+    <signal name="TransferredBytesChanged"
+      tp:name-for-bindings="Transferred_Bytes_Changed">
       <tp:docstring>
         Emitted when the number of transferred bytes changes. This will not be
         signalled with every single byte change. Instead, the most frequent
         this signal will be emitted is once a second. This should be
-        sufficient, and the TransferredBytes property should not be polled.
+        sufficient, and the <tp:member-ref>TransferredBytes</tp:member-ref>
+        property SHOULD NOT be polled.
       </tp:docstring>
-      <arg name="count" type="t">
+      <arg name="Count" type="t">
         <tp:docstring>
           The number of already transferred bytes.
         </tp:docstring>
diff --git a/extensions/misc.xml b/extensions/misc.xml
index 40eccde1f..3182d4f13 100644
--- a/extensions/misc.xml
+++ b/extensions/misc.xml
@@ -7,6 +7,6 @@
 <xi:include href="Stream_Engine.xml"/>
 <xi:include href="Channel_Handler.xml"/>
 <xi:include href="Tube_Handler.xml"/>
-<xi:include href="Channel_Type_File.xml"/>
+<xi:include href="Channel_Type_File_Transfer.xml"/>
 
 </tp:spec>