<?xml version="1.0" ?>
<node name="/Channel_Type_File" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>
Copyright (C) 2008 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.File.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>
<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>
<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>
</tp:docstring>
<property name="State" type="u" tp:type="File_Transfer_State"
access="read">
<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">
<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:docstring>
</property>
<property name="Filename" type="s" access="readwrite">
<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
CreateChannels requests 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">
<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
CreateChannels requests 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">
<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>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:docstring>
</property>
<property name="ContentHash" type="s" access="readwrite">
<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>
<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
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">
<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:docstring>
</property>
<property name="AvailableSocketTypes" type="a{uau}"
tp:type="Supported_Socket_Map" access="read">
<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.</p>
<p>A typical value for a host that supports only Unix sockets:</p>
<pre>
{
Socket_Address_Type_Unix:
[Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
Socket_Address_Type_Abstract_Unix:
[Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
}
</pre>
</tp:docstring>
</property>
<property name="TransferredBytes" type="t" access="read">
<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: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>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>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>
The file transfer is currently not set up correctly.
</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.
</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.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Local_Pending" value="3">
<tp:docstring>
The file transfer is waiting to be accepted/closed locally.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Remote_Pending" value="4">
<tp:docstring>
The file transfer is waiting to be accepted/closed remotely.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Open" value="5">
<tp:docstring>
The file transfer is open for traffic.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Completed" value="6">
<tp:docstring>
The file transfer has been completed successfully.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Canceled" value="7">
<tp:docstring>
The file transfer has been canceled.
</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="Local_Stopped" value="1">
<tp:docstring>
The file transfer was canceled 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.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Local_Error" value="3">
<tp:docstring>
The file transfer was canceled 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.
</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, which SHOULD be
lower-case if they are letters.
</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.
</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.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<method name="AcceptFile">
<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.
</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 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.
</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: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.
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
<method name="OfferFile">
<tp:docstring>
Offer a file transfer that's in the "not offered" state. The file transfer
becomes remote pending after this method is called.
</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.NetworkError"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
<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.
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
<signal name="FileTransferStateChanged">
<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 canceled.
</tp:docstring>
</arg>
</signal>
<signal name="TransferredBytesChanged">
<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.
</tp:docstring>
<arg name="count" type="t">
<tp:docstring>
The number of already transferred bytes.
</tp:docstring>
</arg>
</signal>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
