diff options
Diffstat (limited to 'qt4/spec/Channel_Type_File_Transfer.xml')
| -rw-r--r-- | qt4/spec/Channel_Type_File_Transfer.xml | 580 |
1 files changed, 580 insertions, 0 deletions
diff --git a/qt4/spec/Channel_Type_File_Transfer.xml b/qt4/spec/Channel_Type_File_Transfer.xml new file mode 100644 index 000000000..6963d2133 --- /dev/null +++ b/qt4/spec/Channel_Type_File_Transfer.xml @@ -0,0 +1,580 @@ +<?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> + + <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. + 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 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> + + <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: --> |