<?xml version="1.0" ?>
<node name="/Channel_Type_File_Transfer" 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="org.freedesktop.Telepathy.Channel.Type.FileTransfer">
    <tp:requires interface="org.freedesktop.Telepathy.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 eg 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="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 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="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">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>
    </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:docstring>
    </property>

    <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
        <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="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
        once the channel has been created.</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 is mandatory when requesting the channel with the
        <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="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
        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="org.freedesktop.Telepathy">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>
      </tp:docstring>
    </property>

    <property name="ContentHashType" type="u" tp:type="File_Hash_Type"
      access="read" tp:name-for-bindings="Content_Hash_Type">
      <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="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>

        <p>For each supported hash type, implementations SHOULD include an entry
          in <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.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>
      </tp:docstring>
    </property>

    <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 <tp:member-ref>ContentHashType</tp:member-ref>
        property.</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. 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="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
        <tp:dbus-ref namespace="org.freedesktop.Telepathy">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>
      </tp:docstring>
    </property>

    <property name="Date" type="x" 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: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)
        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 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: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 state of the transfer has
        changed to Open.</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 State 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.
        </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:docstring>
          The file transfer is open for traffic.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Completed" value="4">
        <tp:docstring>
          The file transfer has been completed successfully.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Cancelled" value="5">
        <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 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
        <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.
      </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 Socket_Access_Control 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="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            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,
            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 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="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.
      </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 Socket_Access_Control 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="org.freedesktop.Telepathy.Error.NotImplemented">
          <tp:docstring>
            The given address type or access-control mechanism is not supported.
          </tp:docstring>
        </tp:error>
        <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>
            Channel is not an outgoing transfer, ProvideFile 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; see the File_Transfer_State enumeration.
        </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.
        </tp:docstring>
      </arg>
    </signal>

    <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.
      </tp:docstring>
      <arg name="Count" type="t">
        <tp:docstring>
          The number of already transferred bytes.
        </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 Open and clients have to use this offset when transferring the
        file.
      </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>

  </interface>

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