FileTransfer: make ContentHash{,Type} mutable before ProvideFileft-46783

This is necessary so the hashing can be done by a client who didn't
request the channel in the first place which is kind of ridiculous.

Fixes: fd.o#46783

Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>

1 files changed, 260 insertions, 171 deletions

diff --git a/spec/Channel_Type_File_Transfer1.xml b/spec/Channel_Type_File_Transfer1.xml
index dbfe5424..7703f495 100644
--- a/spec/Channel_Type_File_Transfer1.xml
+++ b/spec/Channel_Type_File_Transfer1.xml
@@ -35,47 +35,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       passes a stream from which the connection manager reads, requiring no
       further connection to the share. It also allows connection managers to
       be more restricted in their access to the system, allowing tighter
-      security policies with eg SELinux, or more flexible deployments which
+      security policies with e.g. SELinux, or more flexible deployments which
       cross user or system boundaries.</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>
 
-      <ul><li>In order to send a file, one should request a FileTransfer
-      channel for a contact, including at least the mandatory properties
-      (<tp:member-ref>Filename</tp:member-ref>,
-      <tp:member-ref>Size</tp:member-ref> and <tp:member-ref>ContentType</tp:member-ref>).
-      Then, one should
-      call <tp:member-ref>ProvideFile</tp:member-ref> to configure the socket that
-      will be used to transfer the file.</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. When the receiver wants to resume a transfer, the Offset
-      argument should be should be set to a non-zero value when calling
-      <tp:member-ref>AcceptFile</tp:member-ref>.</li>
-
-    <li>Once the offset has been negotiated, the
-      <tp:member-ref>InitialOffsetDefined</tp:member-ref> signal
-      is emitted and the <tp:member-ref>InitialOffset</tp:member-ref> property
-      is defined. The <tp:member-ref>InitialOffsetDefined</tp:member-ref>
-      signal is emitted before channel becomes Open.
-      The receiver MUST check the value of
-      <tp:member-ref>InitialOffset</tp:member-ref> for a difference in offset
-      from the requested value in AcceptFile.</li>
-
-      <li>When the state changes to Open, Clients can start the transfer of the
-      file using the offset previously announced.
-      </li></ul>
-
-      <p>If something goes wrong with the transfer,
-      <tp:dbus-ref namespace="im.telepathy1">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 behaviour is undefined.</p>
+      <p>The FileTransfer channel type may be requested for handles of type
+      <tp:value-ref type="Handle_Type">Contact</tp:value-ref>. If the
+      channel is requested for any other handle type then the
+      behaviour is undefined.</p>
 
       <p>Connection managers SHOULD NOT advertise support for file transfer to
         other contacts unless it has been indicated by a call to
@@ -85,116 +55,216 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:rationale>
         <p>People would send us files, and it would always fail. That would be silly.</p>
       </tp:rationale>
+
+      <h4>Sending a file</h4>
+
+      <ol><li>A client should request a FileTransfer channel to a
+      contact, including at least the mandatory properties. For
+      example:</li>
+
+      <blockquote><pre>{
+    <tp:dbus-ref namespace="imt1.Channel">ChannelType</tp:dbus-ref>: <tp:dbus-ref namespace="imt1.Channel.Type">FileTransfer1</tp:dbus-ref>,
+    <tp:dbus-ref namespace="imt1.Channel">TargetHandleType</tp:dbus-ref>: <tp:value-ref type="Handle_Type">Contact</tp:value-ref>,
+    <tp:dbus-ref namespace="imt1.Channel">TargetID</tp:dbus-ref>: "foo@bar.com",
+    <tp:dbus-ref namespace="imt1.Channel.Type.FileTransfer1">Filename</tp:dbus-ref>: "wickedparty.jpg",
+    <tp:dbus-ref namespace="imt1.Channel.Type.FileTransfer1">Size</tp:dbus-ref>: 1020357
+}</pre></blockquote>
+
+      <li>The channel is returned and if hashing information is to be
+      sent, it is calculated now. Note that if the client who
+      requested the channel isn't the channel handler, the
+      <tp:member-ref>URI</tp:member-ref> property should be set in the
+      channel request.
+
+      <tp:rationale>If the handler didn't request the file, it will
+      not know what file to actually send over the socket to the
+      connection manager.</tp:rationale>
+
+      The handler can update the
+      <tp:member-ref>ContentHashType</tp:member-ref> and
+      <tp:member-ref>ContentHash</tp:member-ref> properties
+      appropriately using the D-Bus properties' Set method.</li>
+
+      <li>The handler calls <tp:member-ref>ProvideFile</tp:member-ref>
+      to configure the socket that will be used to transfer the
+      file. At this point, the file transfer invitation is actually
+      sent to the other contact by the CM and the
+      <tp:member-ref>ContentHashType</tp:member-ref>,
+      <tp:member-ref>ContentHash</tp:member-ref>, and
+      <tp:member-ref>URI</tp:member-ref> properties are now
+      immutable.</li>
+
+      <li>The transfer <tp:member-ref>State</tp:member-ref> changes to
+      <tp:value-ref type="File_Transfer_State">Pending</tp:value-ref>
+      as the recipient decides whether to accept the transfer.</li>
+
+      <li>If the transfer is accepted, the
+      <tp:member-ref>State</tp:member-ref> changes to <tp:value-ref
+      type="File_Transfer_State">Open</tp:value-ref> and the handler
+      must then start sending the file to the CM using the socket
+      previously set up in the
+      <tp:member-ref>ProvideFile</tp:member-ref> call.</li>
+      </ol>
+
+      <h4>Receiving a file</h4>
+
+      <ol><li>A wild FileTransfer channel appears.</li>
+
+      <li>The <tp:member-ref>URI</tp:member-ref> property MAY be set
+      by the channel handler before calling
+      <tp:member-ref>AcceptFile</tp:member-ref> to inform observers
+      where the file will be saved. If the property is set by an
+      approver, the channel handler MUST save the file to that
+      location.</li>
+
+      <li>The handler then calls
+      <tp:member-ref>AcceptFile</tp:member-ref> to configure the
+      socket that will be used to receive the file.</li>
+
+      <li>When the transfer <tp:member-ref>State</tp:member-ref>
+      changes to <tp:value-ref
+      type="File_Transfer_State">Open</tp:value-ref>, the handler
+      MUST check the <tp:member-ref>InitialOffset</tp:member-ref>
+      property to see if it differs from the value given in
+      <tp:member-ref>AcceptFile</tp:member-ref> and act accordingly.</li>
+
+      <li>The handler can now start receiving the file from the CM
+      using the socket previously set up in the
+      <tp:member-ref>AcceptFile</tp:member-ref> call.</li></ol>
+
+      <h4>During a file transfer</h4>
+
+      <p>To reject an incoming file transfer, or to cancel an ongoing
+      transfer, handlers should call <tp:dbus-ref
+      namespace="imt1">Channel.Close</tp:dbus-ref>.</p>
+
     </tp:docstring>
 
     <property name="State" type="u" tp:type="File_Transfer_State"
       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:type>File_Transfer_State</tp:type> enum.</p>
       </tp:docstring>
     </property>
 
     <property name="ContentType" type="s" access="read"
       tp:name-for-bindings="Content_Type" tp:immutable="yes" tp:requestable="yes">
       <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>The file's MIME type. Protocols which do not have a "content
+        type" property with file transfers should set this value to
+        <tt>application/octet-stream</tt>.</p>
 
-        <p>This property is mandatory when requesting the channel with the
-        <tp:dbus-ref namespace="im.telepathy1">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>
+        <p>This property is mandatory when requesting a file transfer
+        channel.</p>
       </tp:docstring>
     </property>
 
     <property name="Filename" type="s" access="read"
       tp:name-for-bindings="Filename" tp:immutable="yes" tp:requestable="yes">
       <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
-        once the channel has been created.</p>
+        <p>The name of the file on the sender's side. This is
+        therefore given as a suggested filename for the receiver.</p>
 
-        <p>This property should be the basename of the file being sent. For example,
-        if the sender sends the file /home/user/monkey.pdf then this property should
-        be set to monkey.pdf.</p>
+        <p>This property should be the basename of the file being
+        sent. For example, if the sender sends the file
+        <tt>/home/user/monkey.pdf</tt> then this property should be set to
+        <tt>monkey.pdf</tt>.</p>
 
-        <p>This property is mandatory when requesting the channel with the
-        <tp:dbus-ref namespace="im.telepathy1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
-        method. This property cannot be empty and MUST be set to a sensible value.</p>
+        <p>This property is mandatory when requesting a file transfer
+        channel; it cannot be empty and MUST be set to a sensible
+        value.</p>
       </tp:docstring>
     </property>
 
     <property name="Size" type="t" access="read"
       tp:name-for-bindings="Size" tp:immutable="yes" tp:requestable="yes">
       <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
-        the channel has been created.</p>
-
-        <p>When you are creating a channel with this property, its value
-        MUST be accurate and in bytes. However, when receiving a file, this
-        property still MUST be in bytes but might not be entirely accurate
-        to the byte.</p>
-
-        <p>This property is mandatory when requesting the channel with the
-        <tp:dbus-ref namespace="im.telepathy1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
-        method. If this information isn't provided in the protocol, connection managers MUST set it
-        to UINT64_MAX.</p>
+        <p>The size of the file.</p>
+
+        <p>For outgoing transfers, the value of this property MUST be
+        in bytes, and accurate to the nearest byte. For incoming
+        transfers, the value of this property MUST be in bytes but
+        clients SHOULD NOT treat it as accurate to the nearest
+        byte.</p>
+
+        <p>This property is mandatory when requesting a file transfer
+        channel. If this information isn't provided in the protocol,
+        connection managers MUST set it to UINT64_MAX.</p>
       </tp:docstring>
     </property>
 
     <property name="ContentHashType" type="u" tp:type="File_Hash_Type"
-      access="read" tp:name-for-bindings="Content_Hash_Type" tp:immutable="yes"
-      tp:requestable="yes">
+      access="readwrite" tp:name-for-bindings="Content_Hash_Type"
+      tp:immutable="sometimes" tp:requestable="yes">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <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
-        <tp:dbus-ref namespace="im.telepathy1">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="im.telepathy1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
-        method call then its value will be assumed to be File_Hash_Type_None.</p>
-
-        <p>For each supported hash type, implementations SHOULD include an entry
-          in <tp:dbus-ref
-            namespace="im.telepathy1.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
-          with this property fixed to that hash type. If the protocol supports
-          offering a file without a content hash, implementations SHOULD list
-          this property in Allowed in a requestable channel class, mapping hash
-          types they don't understand to None.
-        </p>
+        <p>The type of the <tp:member-ref>ContentHash</tp:member-ref>
+        property.</p>
+
+        <p>For outgoing file transfers, this property is mutable until
+        <tp:member-ref>ProvideFile</tp:member-ref> has been
+        called. The property, along with
+        <tp:member-ref>ContentHash</tp:member-ref>, can be updated
+        using the D-Bus properties interface. Its value MUST
+        correspond to the appropriate type of the
+        <tp:member-ref>ContentHash</tp:member-ref> property.</p>
+
+        <p>For incoming file transfers, this property is always
+        immutable.</p>
+
+        <p>For each supported hash type, implementations SHOULD
+        include an entry in <tp:dbus-ref
+        namespace="imt1.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
+        with this property fixed to that hash type. If the protocol
+        supports offering a file without a content hash,
+        implementations SHOULD list this property in Allowed in a
+        requestable channel class, mapping hash types they don't
+        understand to <tp:value-ref
+        type="File_Hash_Type">None</tp:value-ref>.</p>
+
+        <p>This property is optional when requesting file transfer
+        channels. Its default value is <tp:value-ref
+        type="File_Hash_Type">None</tp:value-ref>.</p>
       </tp:docstring>
     </property>
 
-    <property name="ContentHash" type="s" access="read"
-      tp:name-for-bindings="Content_Hash" tp:immutable="yes"
+    <property name="ContentHash" type="s" access="readwrite"
+      tp:name-for-bindings="Content_Hash" tp:immutable="sometimes"
       tp:requestable="yes">
       <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 <tp:member-ref>ContentHashType</tp:member-ref>
-        property.</p>
-
-        <p>This property is optional when requesting the channel with the
-        <tp:dbus-ref namespace="im.telepathy1">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>
+        <p>Hash of the contents of the file transfer, of type
+        described by the value of the
+        <tp:member-ref>ContentHashType</tp:member-ref> property.</p>
+
+        <p>For outgoing file transfers, this property is mutable until
+        <tp:member-ref>ProvideFile</tp:member-ref> has been
+        called. The property, along with
+        <tp:member-ref>ContentHashType</tp:member-ref>, can be updated
+        using the D-Bus properties interface. Its value MUST
+        correspond to the appropriate type of the
+        <tp:member-ref>ContentHashType</tp:member-ref> property. If
+        the <tp:member-ref>ContentHashType</tp:member-ref> property is
+        not set, or set to <tp:value-ref
+        type="File_Hash_Type">None</tp:value-ref>, then this property
+        should not be set.</p>
+
+        <p>For incoming file transfers, this property is always
+        immutable.</p>
+
+        <p>This property is optional when requesting file transfer
+        channels. Its default value is the empty string.</p>
       </tp:docstring>
     </property>
 
     <property name="Description" type="s" access="read"
       tp:name-for-bindings="Description" tp:immutable="yes" tp:requestable="yes">
       <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>Description of the file transfer.</p>
 
-        <p>This property is optional when requesting the channel with the
-        <tp:dbus-ref namespace="im.telepathy1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
-        method. If this property was not provided by the remote party, connection managers MUST set it to
-        the empty string.</p>
+        <p>This property is optional when requesting a file transfer
+        channel. If this property was not provided by the remote
+        party, connection managers MUST set it to the empty
+        string.</p>
       </tp:docstring>
     </property>
 
@@ -202,12 +272,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       tp:type="Unix_Timestamp64" tp:name-for-bindings="Date" tp:immutable="yes"
       tp:requestable="yes">
       <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>The last modification time of the file being transferred.</p>
 
-        <p>This property is optional when requesting the channel with the
-        <tp:dbus-ref namespace="im.telepathy1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
-        method.</p>
+        <p>This property is optional when requesting a file transfer
+        channel.</p>
       </tp:docstring>
     </property>
 
@@ -216,12 +284,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       tp:name-for-bindings="Available_Socket_Types"
       tp:immutable="yes" tp:requestable="yes">
       <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)
-        that the connection manager supports for sockets with that
-        address type. For simplicity, if a CM supports offering a
-        particular type of file transfer, it is assumed to support accepting
-        it. Connection Managers MUST support at least Socket_Address_Type_IPv4.</p>
+        <p>A mapping from address types (members of
+        <tp:type>Socket_Address_Type</tp:type>) to arrays of access
+        control type (members of
+        <tp:type>Socket_Access_Control</tp:type>) that the connection
+        manager supports for sockets with that address type. For
+        simplicity, if a CM supports offering a particular type of
+        file transfer, it is assumed to support accepting
+        it. Connection Managers MUST support at least <tp:value-ref
+        type="Socket_Address_Type">IPv4</tp:value-ref>.</p>
 
         <p>A typical value for a host without IPv6 support:</p>
 
@@ -259,8 +330,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         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>
+        <p>This property MUST NOT change after the
+        <tp:member-ref>State</tp:member-ref> of the transfer has
+        changed to <tp:value-ref
+        type="File_Transfer_State">Open</tp:value-ref>.</p>
       </tp:docstring>
     </property>
 
@@ -300,36 +373,33 @@ 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>
-          An invalid state type used as a null value. This value MUST NOT
-          appear in the State property.
+          An invalid state type used as a null value. This value MUST
+          NOT appear in the <tp:member-ref>State</tp:member-ref>
+          property.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Pending" value="1">
         <tp:docstring>
-          The file transfer is waiting to be accepted/closed by the receiver.
-          The receiver has to call <tp:member-ref>AcceptFile</tp:member-ref>,
-          then wait for the state to change to Open and check the offset value.
+          The file transfer is waiting to be accepted or rejected by
+          the recipient. If incoming, the handler should accept the
+          file by calling <tp:member-ref>AcceptFile</tp:member-ref>,
+          wait for the <tp:member-ref>State</tp:member-ref> to change
+          to <tp:value-ref
+          type="File_Transfer_State">Open</tp:value-ref> and check the
+          <tp:member-ref>InitialOffset</tp:member-ref> value.
         </tp:docstring>
       </tp:enumvalue>
-      <tp:enumvalue suffix="Accepted" value="2">
-        <tp:docstring>
-          The receiver has accepted the transfer. The sender now has to
-          call <tp:member-ref>ProvideFile</tp:member-ref> to actually start the transfer.
-          The receiver should now wait for the state to change to Open
-          and check the offset value.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Open" value="3">
+      <tp:enumvalue suffix="Open" value="2">
         <tp:docstring>
           The file transfer is open for traffic.
         </tp:docstring>
       </tp:enumvalue>
-      <tp:enumvalue suffix="Completed" value="4">
+      <tp:enumvalue suffix="Completed" value="3">
         <tp:docstring>
           The file transfer has been completed successfully.
         </tp:docstring>
       </tp:enumvalue>
-      <tp:enumvalue suffix="Cancelled" value="5">
+      <tp:enumvalue suffix="Cancelled" value="4">
         <tp:docstring>
           The file transfer has been cancelled.
         </tp:docstring>
@@ -394,14 +464,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
     <method name="AcceptFile" tp:name-for-bindings="Accept_File">
       <tp:docstring>
-        Accept a file transfer that's in the Pending state. The file
-        transfer's state becomes Accepted after this method is called.
-        At this point the client can connect to the socket. CM MUST emit
+        Accept a file transfer that's in the <tp:value-ref
+        type="File_Transfer_State">Pending</tp:value-ref> state. The
+        CM MUST then emit
         <tp:member-ref>InitialOffsetDefined</tp:member-ref> and change
-        the state to Open before writing to the socket.
-        Then <tp:member-ref>InitialOffset</tp:member-ref> should be respected in case
-        its value differs from the offset that was specified as an argument
-        to AcceptFile.
+        the <tp:member-ref>State</tp:member-ref> to <tp:value-ref
+        type="File_Transfer_State">Open</tp:value-ref> before the
+        handler writes to the
+        socket. <tp:member-ref>InitialOffset</tp:member-ref> should be
+        respected in case its value differs from the offset that was
+        specified as an argument to this method.
       </tp:docstring>
       <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type">
         <tp:docstring>
@@ -416,8 +488,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </arg>
       <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.
+          A parameter for the access control type, to be interpreted
+          as specified in the documentation for the
+          <tp:type>Socket_Access_Control</tp:type> enum.
         </tp:docstring>
       </arg>
       <arg direction="in" name="Offset" type="t">
@@ -448,13 +521,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <tp:error name="im.telepathy1.Error.NetworkError"/>
         <tp:error name="im.telepathy1.Error.InvalidArgument"/>
           <tp:docstring>
-            Your address type, access control, access control parameter,
+            The address type, access control, access control parameter,
             offset, or a combination of all four is invalid.
           </tp:docstring>
         <tp:error name="im.telepathy1.Error.NotAvailable">
           <tp:docstring>
-            The file transfer is not in the Pending state, there isn't
-            or there is a local error with acquiring a socket.
+            The file transfer is not in the Pending state or there was
+            a local error with acquiring a socket.
           </tp:docstring>
         </tp:error>
       </tp:possible-errors>
@@ -462,10 +535,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
     <method name="ProvideFile" tp:name-for-bindings="Provide_File">
       <tp:docstring>
-        Provide the file for an outgoing file transfer which has been offered.
-        Opens a socket that the client can use to provide a file to the connection manager.
-        The channel MUST have been requested, and will change state
-        to Open when this method is called if its state was Accepted.
+        Provide the file for an outgoing file transfer. Opens a socket
+        that the handler can use to send the file to the connection
+        manager. The channel MUST have been requested, and will
+        change state to <tp:value-ref
+        type="File_Transfer_State">Open</tp:value-ref>.
       </tp:docstring>
       <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type">
         <tp:docstring>
@@ -474,14 +548,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </arg>
       <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.
+          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">
         <tp:docstring>
-          A parameter for the access control type, to be interpreted as
-          specified in the documentation for the Socket_Access_Control enum.
+          A parameter for the access control type, to be interpreted
+          as specified in the documentation for the
+          <tp:type>Socket_Access_Control</tp:type> enum.
         </tp:docstring>
       </arg>
       <arg direction="out" name="Address" type="v">
@@ -494,18 +569,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:possible-errors>
         <tp:error name="im.telepathy1.Error.NotImplemented">
           <tp:docstring>
-            The given address type or access-control mechanism is not supported.
+            The given address type or access-control mechanism is not
+            supported.
           </tp:docstring>
         </tp:error>
         <tp:error name="im.telepathy1.Error.InvalidArgument"/>
           <tp:docstring>
-            Your address type, access control, access control parameter, or
-            a combination of all three is invalid.
+            The address type, access control, access control
+            parameter, or a combination of all three is invalid.
           </tp:docstring>
         <tp:error name="im.telepathy1.Error.NotAvailable">
           <tp:docstring>
-            Channel is not an outgoing transfer, ProvideFile has already been called,
-            or there was a local error acquiring the socket.
+            The channel is not outgoing,
+            <tp:member-ref>ProvideFile</tp:member-ref> has already
+            been called, or there was a local error acquiring the
+            socket.
           </tp:docstring>
         </tp:error>
       </tp:possible-errors>
@@ -518,15 +596,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:docstring>
       <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.
+          The new state of the file transfer.
         </tp:docstring>
       </arg>
       <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 cancelled.
+          The reason for the state change. The value will always be
+          <tp:value-ref
+          type="File_Transfer_State_Change_Reason">None</tp:value-ref>,
+          except when changing state to <tp:value-ref
+          type="File_Transfer_State">Cancelled</tp:value-ref>.
         </tp:docstring>
       </arg>
     </signal>
@@ -534,15 +613,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     <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 <tp:member-ref>TransferredBytes</tp:member-ref>
-        property SHOULD NOT be polled.
+        <p>Emitted when the
+        <tp:member-ref>TransferredBytes</tp:member-ref> property
+        changes. This signal SHOULD NOT be emitted for every byte
+        transferred; instead it should be signalled a maximum of once
+        a second.</p>
+
+        <tp:rationale>This would flood the bus with useless signal
+        emissions.</tp:rationale>
+
+        <p>The <tp:member-ref>TransferredBytes</tp:member-ref>
+        property SHOULD NOT be polled.</p>
       </tp:docstring>
       <arg name="Count" type="t">
         <tp:docstring>
-          The number of already transferred bytes.
+          The new <tp:member-ref>TransferredBytes</tp:member-ref>
+          property value.
         </tp:docstring>
       </arg>
     </signal>
@@ -550,14 +636,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     <signal name="InitialOffsetDefined"
       tp:name-for-bindings="Initial_Offset_Defined">
       <tp:docstring>
-        Emitted when the value of the <tp:member-ref>InitialOffset</tp:member-ref>
-        property has been negotiated. This signal MUST be emitted before the channel
-        becomes Open and clients have to use this offset when transferring the
-        file.
+        Emitted when the value of the
+        <tp:member-ref>InitialOffset</tp:member-ref> property has been
+        negotiated. This signal MUST be emitted before the channel
+        becomes <tp:value-ref
+        type="File_Transfer_State">Open</tp:value-ref>. Clients must
+        use this offset when transferring files.
       </tp:docstring>
       <arg name="InitialOffset" type="t">
         <tp:docstring>
-          The value of the <tp:member-ref>InitialOffset</tp:member-ref> property.
+          The value of the
+          <tp:member-ref>InitialOffset</tp:member-ref> property.
         </tp:docstring>
       </arg>
     </signal>