From c4acf2126b82dc13002c33989ed39b5f0065ec1a Mon Sep 17 00:00:00 2001
From: Xavier Claessens
Date: Fri, 21 Nov 2008 16:20:53 +0000
Subject: Channel_Type_File_Transfer.xml: sync with latest draft
svn path=/trunk/; revision=1848
---
extensions/Channel_Type_File_Transfer.xml | 137 +++++++++++++++++++-----------
1 file changed, 87 insertions(+), 50 deletions(-)
(limited to 'extensions')
diff --git a/extensions/Channel_Type_File_Transfer.xml b/extensions/Channel_Type_File_Transfer.xml
index 4838f7f1d..92d90dc11 100644
--- a/extensions/Channel_Type_File_Transfer.xml
+++ b/extensions/Channel_Type_File_Transfer.xml
@@ -27,25 +27,52 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
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.
+ 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.
+
+ If the connection manager relies on a library using file path only for
+ file transfers, it can use the Socket_Address_Type_Local_Path
+ Socket_Address_Type. In that case the file will be
+ read and written directly by the CM.
+
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.
- In order to send a file, one should request a FileTransfer
- channel for a contact, and fill the mandatory properties
- (Filename, and
- Size). After these are set, one should
- call OfferFile to offer the transfer to
- the contact.
+ channel for a contact, including at least the mandatory properties
+ (Filename,
+ Size and ContentType).
+ Then, one should
+ call ProvideFile to configure the socket that
+ will be used to transfer the file.
- In order to receive an incoming file transfer, one should call
AcceptFile and then wait until the state
- changes to Open. If the receiver is resuming a transfer then he or she
- should set a non-zero Offset argument when calling
- AcceptFile. When the state changes to Open,
- the receiver must check the InitialOffset
- property for a difference in offset from the requested value in
- AcceptFile.
+ 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
+ AcceptFile.
+
+ Once the offset has been negotiated, the
+ InitialOffsetDefined signal
+ is emitted and the InitialOffset property
+ is defined. The InitialOffsetDefined
+ signal is emitted before channel becomes Open.
+ The receiver MUST check the value of
+ InitialOffset for a difference in offset
+ from the requested value in AcceptFile.
+
+ When the state changes to Open, Clients can start the transfer of the
+ file using the offset previously announced.
+
If something goes wrong with the transfer,
Channel.Close
@@ -90,7 +117,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
This property is mandatory when requesting the channel with the
Connection.Interface.Requests.CreateChannel
- method. This property cannot be empty and must be set to a sensible value.
+ method. This property cannot be empty and MUST be set to a sensible value.
@@ -103,13 +130,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
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
+ property still MUST be in bytes but might not be entirely accurate
to the byte.
This property is mandatory when requesting the channel with the
Connection.Interface.Requests.CreateChannel
- method. If this property is UINT64_MAX, then its value is
- unspecified.
+ method. If this information isn't provided in the protocol, connection managers MUST set it
+ to UINT64_MAX.
@@ -151,8 +178,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
This property is optional when requesting the channel with the
Connection.Interface.Requests.CreateChannel
- method. If this property is an empty string, then its value is
- unspecified.
+ method. If this property was not provided by the remote party, connection managers MUST set it to
+ the empty string.
@@ -205,9 +232,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
tp:name-for-bindings="Initial_Offset">
The offset in bytes from where the file should be sent. This MUST
- be checked by both the receiver and the sender after the state
+ be respected by both the receiver and the sender after the state
becomes Open, but before any data is sent or received. Until the
- state changes to Open, this property is undefined.
+ InitialOffsetDefined signal
+ is emitted, this property is undefined.
Before setting the State property to
Open, the connection manager MUST set the InitialOffset property,
@@ -225,40 +253,32 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
appear in the State property.
-
+
- The transfer is waiting for the local client to call the OfferFile
- method, in order to offer a file to be transferred.
+ The file transfer is waiting to be accepted/closed by the receiver.
+ The receiver has to call AcceptFile,
+ then wait for the state to change to Open and check the offset value.
- The client has accepted the incoming file transfer, but the transfer
- is not open. The client should now wait for the state to change to Open
+ The receiver has accepted the transfer. The sender now has to
+ call ProvideFile to actually start the transfer.
+ The receiver should now wait for the state to change to Open
and check the offset value.
-
-
- The file transfer is waiting to be accepted/closed locally.
-
-
-
-
- The file transfer is waiting to be accepted/closed remotely.
-
-
-
+
The file transfer is open for traffic.
-
+
The file transfer has been completed successfully.
-
+
The file transfer has been cancelled.
@@ -323,10 +343,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
- 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, and then
- InitialOffset should be checked in case
+ 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
+ InitialOffsetDefined and change
+ the state to Open before writing to the socket.
+ Then InitialOffset should be respected in case
its value differs from the offset that was specified as an argument
to AcceptFile.
@@ -380,19 +402,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
- The file transfer is not in the Local_Pending state, there isn't
+ The file transfer is not in the Pending state, there isn't
or there is a local error with acquiring a socket.
-
+
- Offer a file transfer that's in the Not_Offered state. Open a socket
- that the client can use to provide a file to the connection manager.
- The channel MUST be in the Not_Offered state, and will change state
- to Remote_Pending when this method is called.
+ 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.
@@ -431,9 +453,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
- The file transfer is not in the Not_Offered state, there isn't
- enough information for the transfer to start, or a local error
- with acquiring a socket.
+ Channel is not an outgoing transfer, ProvideFile has already been called,
+ or there was a local error acquiring the socket.
@@ -474,6 +495,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
+
+
+ Emitted when the value of the InitialOffset
+ 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.
+
+
+
+ The value of the InitialOffset property.
+
+
+
+
--
cgit v1.2.3