<?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 File channel type may be requested for handles of type
HANDLE_TYPE_CONTACT.</p>
</tp:docstring>
<property name="Direction" type="u" tp:type="File_Transfer_Direction"
access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The direction of the file transfer.</p>
<p>This property should become useless with the new request API.</p>
</tp:docstring>
</property>
<property name="State" type="u" tp:type="File_Transfer_State"
access="readwrite">
<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. 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>If this property is an empty string, then its value is unspecified.</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>If this property is UINT64_MAX, then its value is unspecified.</p>
</tp:docstring>
</property>
<property name="EstimatedSize" type="t" access="readwrite">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An estimate of the size of the file. This property should be used
when the protocol doesn't allow exact file sizes (For example, accurate
to the nearest megabyte). This property should not be set if the Size
property can, or has, been set. This cannot change once the channel
has been created.</p>
<p>If this property is UINT64_MAX, then its value is unspecified.</p>
</tp:docstring>
</property>
<property name="ContentMD5" type="s" access="readwrite">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>MD5 digest of the file as a string of 32 ASCII hex digits, which
SHOULD be lower-case if they are letters. This cannot change once
the channel has been created.</p>
<p>If this property is an empty string, then its value is unspecified.</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>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="SocketPath" type="s" access="readwrite">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Path to the UNIX socket in use.</p>
<p>If this is an empty string, its value is undefined.</p>
</tp:docstring>
</property>
<tp:enum name="File_Transfer_Direction">
<tp:enumvalue suffix="Incoming" value="0">
<tp:docstring>
The file transfer is incoming.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Outgoing" value="1">
<tp:docstring>
The file transfer is outgoing.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<tp:enum name="File_Transfer_State">
<tp:enumvalue suffix="Local_Pending" value="0">
<tp:docstring>
The file transfer is waiting to be accepted/closed locally.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Remote_Pending" value="1">
<tp:docstring>
The file transfer is waiting to be accepted/closed remotely.
</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="Canceled" value="4">
<tp:docstring>
The file transfer has been canceled.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<tp:enum name="File_Transfer_State_Change_Reason">
<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>
<!-- Taken from org.freedesktop.Telepathy.Channel.Type.Tubes -->
<tp:enum name="Socket_Address_Type" type="u">
<tp:enumvalue suffix="Unix" value="0">
<tp:docstring>
A Unix socket. The variant contains a byte-array, signature 'ay',
containing the path of the socket.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Abstract_Unix" value="1">
<tp:docstring>
An abstract Unix socket. The variant contains a byte-array,
signature 'ay', containing the path of the socket including the
leading null byte.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="IPv4" value="2">
<tp:docstring>
An IPv4 socket. The variant contains a Socket_Address_IPv4,
i.e. a structure with signature (sq)
in which the string is an IPv4 dotted-quad address literal
(and must not be a DNS name), while the 16-bit unsigned integer is
the port number.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="IPv6" value="3">
<tp:docstring>
An IPv6 socket. The variant contains a Socket_Address_IPv6,
i.e. a structure with signature (sq)
in which the string is an IPv6 address literal as specified in
RFC2373 (and must not be a DNS name), while the 16-bit unsigned
integer is the port number.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<!-- Taken from org.freedesktop.Telepathy.Channel.Type.Tubes -->
<tp:enum name="Socket_Access_Control" type="u">
<tp:enumvalue suffix="Localhost" value="0">
<tp:docstring>
The IP or Unix socket can be accessed by any local user (e.g.
a Unix socket that accepts all local connections, or an IP socket
listening on 127.0.0.1 (or ::1) or rejecting connections not from
that address). The associated variant must be ignored.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Port" value="1">
<tp:docstring>
May only be used on IP sockets. The associated variant must contain
a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
containing the string form of an IP address of the appropriate
version, and a port number. The socket can only be accessed if the
connecting process has that address and port number; all other
connections will be rejected.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Netmask" value="2">
<tp:docstring>
May only be used on IP sockets. The associated variant must contain
a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with
signature (sy), containing the string form of an
IP address of the appropriate version, and a prefix length "n".
The socket can only be accessed if the first n bits of the
connecting address match the first n bits of the given address.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Credentials" value="3">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The connecting process must send a single zero (NUL) byte when
it first connects, which is not considered to be part of the data
stream. If the operating system uses sendmsg() with SCM_CREDS or
SCM_CREDENTIALS to pass credentials over sockets, the connecting
process must do so if possible; if not, it must still send the
byte.</p>
<p>The listening process will disconnect the connection unless it
can determine by OS-specific means that the connecting process
has the same user ID as the listening process.</p>
<p>The associated variant must be ignored.</p>
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<!-- Taken from org.freedesktop.Telepathy.Channel.Type.Tubes -->
<tp:mapping name="Supported_Socket_Map">
<tp:docstring>The supported socket address and access-control types
for tubes. See GetAvailableStreamTubeTypes.</tp:docstring>
<tp:member name="Address_Type" type="u" tp:type="Socket_Address_Type"/>
<tp:member name="Access_Control" type="au"
tp:type="Socket_Access_Control[]"/>
</tp:mapping>
<method name="AcceptFile">
<tp:docstring>
Accept a file transfer that's in the "local pending" state. The file
transfer becomes open 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 "local pending" state, which is the only
state this method makes sense.
</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 change
with every single byte change. Instead, the most frequent this signal will
be emmitted 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: -->