From 84190ffca8c5c58ad6f42dba53436ef10cf54cbc Mon Sep 17 00:00:00 2001 From: Guillaume Desmottes Date: Wed, 5 Nov 2008 11:22:13 +0000 Subject: Channel_Type_File_Transfer.xm: sync with latest draft --- extensions/Channel_Type_File_Transfer.xml | 127 +++++++++++++++++++----------- 1 file changed, 81 insertions(+), 46 deletions(-) (limited to 'extensions') diff --git a/extensions/Channel_Type_File_Transfer.xml b/extensions/Channel_Type_File_Transfer.xml index 4838f7f1..489c2bbf 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. +

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.

+ AcceptFile. + +
  • Once the offset has been negotiated, the + InitialOffsetDefined signal + is emitted and the InitialOffset property + is defined. The InitialOffsetDefined signal MUST be emitted before the + 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.

    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. - + - 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,10 @@ 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 + 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 receiver must wait for the state to change to Open, and then - InitialOffset should be checked in case + point, the receiver MUST wait for the state to change to Open, and then + InitialOffset should be respected in case its value differs from the offset that was specified as an argument to AcceptFile. @@ -380,19 +400,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. + Open 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 +451,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 +493,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.1