diff options
| -rw-r--r-- | extensions/Channel_Type_File_Transfer.xml | 513 | ||||
| -rw-r--r-- | extensions/Makefile.am | 1 | ||||
| -rw-r--r-- | extensions/misc.xml | 1 |
3 files changed, 0 insertions, 515 deletions
diff --git a/extensions/Channel_Type_File_Transfer.xml b/extensions/Channel_Type_File_Transfer.xml deleted file mode 100644 index a2432f4be..000000000 --- a/extensions/Channel_Type_File_Transfer.xml +++ /dev/null @@ -1,513 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_File_Transfer" 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.FileTransfer.DRAFT" - tp:causes-havoc="experimental"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <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> - </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> - </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="t" 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: --> diff --git a/extensions/Makefile.am b/extensions/Makefile.am index 20657bba7..0a57fe323 100644 --- a/extensions/Makefile.am +++ b/extensions/Makefile.am @@ -12,7 +12,6 @@ EXTRA_DIST = \ misc.xml \ Channel_Handler.xml \ Tube_Handler.xml \ - Channel_Type_File_Transfer.xml \ Channel_Interface_Tube.xml \ Channel_Type_DBus_Tube.xml \ Channel_Type_Stream_Tube.xml diff --git a/extensions/misc.xml b/extensions/misc.xml index e79caead2..5c89ff0d8 100644 --- a/extensions/misc.xml +++ b/extensions/misc.xml @@ -6,7 +6,6 @@ <xi:include href="Channel_Handler.xml"/> <xi:include href="Tube_Handler.xml"/> -<xi:include href="Channel_Type_File_Transfer.xml"/> <xi:include href="Channel_Interface_Tube.xml" /> <xi:include href="Channel_Type_DBus_Tube.xml" /> <xi:include href="Channel_Type_Stream_Tube.xml" /> |