path: root/spec/Channel_Type_File_Transfer1.xml

<?xml version="1.0" ?>
<node name="/Channel_Type_File_Transfer1" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>
    Copyright © 2008-2009 Collabora Limited
  </tp:copyright>
  <tp:license xmlns="http://www.w3.org/1999/xhtml">
    <p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.</p>

<p>This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Library General Public License for more details.</p>

<p>You should have received a copy of the GNU Lesser General Public
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="im.telepathy1.Channel.Type.FileTransfer1">
    <tp:requires interface="im.telepathy1.Channel"/>
    <tp:added version="0.17.18">(as stable API)</tp:added>
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>A channel type for transferring files. 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>A socket approach is used to make the transfer less dependent on both
      client and connection manager knowing the same protocols. As an example,
      when browsing an SMB share in a file manager, one selects "Send file"
      and chooses a contact. Instead of passing a URL which would then require
      the connection manager to connect to the SMB share itself, the client
      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 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>

      <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
        <tp:dbus-ref
          namespace="im.telepathy1.Connection.Interface.ContactCapabilities1">UpdateCapabilities</tp:dbus-ref>.
      </p>
      <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
        <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. 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 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.</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 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.</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="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>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="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 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.</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>

    <property name="Date" type="x" access="read"
      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.</p>

        <p>This property is optional when requesting a file transfer
        channel.</p>
      </tp:docstring>
    </property>

    <property name="AvailableSocketTypes" type="a{uau}"
      tp:type="Supported_Socket_Map" access="read"
      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
        <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>

        <pre>
          {
            Socket_Address_Type_IPv4:
              [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
               Socket_Access_Control_Netmask],
            Socket_Address_Type_Unix:
              [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
          }
        </pre>
      </tp:docstring>
    </property>

    <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
        continues.</p>
      </tp:docstring>
    </property>

    <property name="InitialOffset" type="t" access="read"
      tp:name-for-bindings="Initial_Offset" tp:requestable="yes">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The offset in bytes from where the file should be sent. This MUST
        be respected by both the receiver and the sender after the state
        becomes Open, but before any data is sent or received. Until the
        <tp:member-ref>InitialOffsetDefined</tp:member-ref> signal
        is emitted, this property is undefined.</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
        <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>

    <property name="URI" type="s" access="readwrite"
      tp:name-for-bindings="URI" tp:immutable="sometimes" tp:requestable="yes">
      <tp:added version="0.21.9"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>For outgoing file transfers, this requestable property allows the channel
        requester to inform observers (and the handler, if it is not the requester
        itself) of the URI of the file being transferred. Note that the
        connection manager SHOULD NOT read this file directly; the handler
        streams the file into the CM through the socket negotiated using
        <tp:member-ref>ProvideFile</tp:member-ref>.</p>

        <p>On outgoing file transfers, this property MUST NOT change after the channel
        is requested.</p>

        <p>For incoming file transfers, this property MAY be set by the channel
        handler before calling <tp:member-ref>AcceptFile</tp:member-ref> to
        inform observers where the incoming file will be saved. If set by an
        approver, the handler MUST save the file to that location.
        Setting this property once <tp:member-ref>AcceptFile</tp:member-ref>
        has been called MUST fail. Once this property has been set
        <tp:member-ref>URIDefined</tp:member-ref> is emitted.</p>

        <p>If set, this URI SHOULD generally point to a file on the local system, as
        defined by <a href='http://www.apps.ietf.org/rfc/rfc1738.html#sec-3.10'>
        RFC 1738 §3.10</a>; that is, it should be of the form
        <tt>file:///path/to/file</tt> or <tt>file://localhost/path/to/file</tt>.
        For outgoing files, this URI MAY use a different scheme, such as
        <tt>http:</tt>, if a remote resource is being transferred
        to a contact.</p>

      </tp:docstring>
    </property>

    <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 <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 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="Open" value="2">
        <tp:docstring>
          The file transfer is open for traffic.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Completed" value="3">
        <tp:docstring>
          The file transfer has been completed successfully.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Cancelled" value="4">
        <tp:docstring>
          The file transfer has been cancelled.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:enum name="File_Transfer_State_Change_Reason" type="u">
      <tp:enumvalue suffix="None" value="0">
        <tp:docstring>
          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="2">
        <tp:docstring>
          The file transfer was cancelled by the local user.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Remote_Stopped" value="3">
        <tp:docstring>
          The file transfer was cancelled by the remote user.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Local_Error" value="4">
        <tp:docstring>
          The file transfer was cancelled because of a local error.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Remote_Error" value="5">
        <tp:docstring>
          The file transfer was cancelled because of a remote error.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:enum name="File_Hash_Type" type="u">
      <tp:enumvalue suffix="None" value="0">
        <tp:docstring>
          No hash.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="MD5" value="1">
        <tp:docstring>
          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.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="SHA256" value="3">
        <tp:docstring>
          SHA256 digest as a string of ASCII hex digits.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <method name="AcceptFile" tp:name-for-bindings="Accept_File">
      <tp:docstring>
        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 <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>
          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">
        <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">
        <tp:docstring>
          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">
        <tp:docstring>
          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">
        <tp:docstring>
          The address on which the connection manager will listen for
          connections for this file transfer.
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy1.Error.NotImplemented">
          <tp:docstring>
            The given address type or access-control mechanism is not supported.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy1.Error.NetworkError"/>
        <tp:error name="im.telepathy1.Error.InvalidArgument"/>
          <tp:docstring>
            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 or there was
            a local error with acquiring a socket.
          </tp:docstring>
        </tp:error>
      </tp:possible-errors>
    </method>

    <method name="ProvideFile" tp:name-for-bindings="Provide_File">
      <tp:docstring>
        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>
          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">
        <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">
        <tp:docstring>
          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">
        <tp:docstring>
          The address on which the connection manager will listen for
          connections for this file transfer.
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="im.telepathy1.Error.NotImplemented">
          <tp:docstring>
            The given address type or access-control mechanism is not
            supported.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy1.Error.InvalidArgument"/>
          <tp:docstring>
            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>
            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>
    </method>

    <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">
        <tp:docstring>
          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. 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>

    <signal name="TransferredBytesChanged"
      tp:name-for-bindings="Transferred_Bytes_Changed">
      <tp:docstring>
        <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 new <tp:member-ref>TransferredBytes</tp:member-ref>
          property value.
        </tp:docstring>
      </arg>
    </signal>

    <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 <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.
        </tp:docstring>
      </arg>
    </signal>

    <signal name="URIDefined"
      tp:name-for-bindings="URI_Defined">
      <tp:added version="0.21.9"/>
      <tp:docstring>
        Emitted when the value of the <tp:member-ref>URI</tp:member-ref>
        property has been set. This signal MUST only be emitted on
        incoming file transfers, and only if the handler sets the
        <tp:member-ref>URI</tp:member-ref> property before
        accepting the file.
      </tp:docstring>
      <arg name="URI" type="s">
        <tp:docstring>
          The value of the <tp:member-ref>URI</tp:member-ref> property.
        </tp:docstring>
      </arg>
    </signal>

  </interface>

</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->