diff options
| -rw-r--r-- | extensions/Channel_Type_File_Transfer.xml | 137 |
1 files changed, 87 insertions, 50 deletions
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.</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>If the connection manager relies on a library using file path only for + file transfers, it can use the Socket_Address_Type_Local_Path + <tp:type>Socket_Address_Type</tp:type>. In that case the file will be + read and written directly by the CM.</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, and fill the mandatory properties - (<tp:member-ref>Filename</tp:member-ref>, and - <tp:member-ref>Size</tp:member-ref>). After these are set, one should - call <tp:member-ref>OfferFile</tp:member-ref> to offer the transfer to - the contact.</li> + 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. If the receiver is resuming a transfer then he or she - should set a non-zero Offset argument when calling - <tp:member-ref>AcceptFile</tp:member-ref>. When the state changes to Open, - the receiver must check the <tp:member-ref>InitialOffset</tp:member-ref> - property for a difference in offset from the requested value in - AcceptFile.</li></ul> + 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> @@ -90,7 +117,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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> + method. This property cannot be empty and MUST be set to a sensible value.</p> </tp:docstring> </property> @@ -103,13 +130,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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 + 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 property is UINT64_MAX, then its value is - unspecified.</p> + method. If this information isn't provided in the protocol, connection managers MUST set it + to UINT64_MAX.</p> </tp:docstring> </property> @@ -151,8 +178,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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 is an empty string, then its value is - unspecified.</p> + method. If this property was not provided by the remote party, connection managers MUST set it to + the empty string.</p> </tp:docstring> </property> @@ -205,9 +232,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ 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 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.</p> + <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, @@ -225,40 +253,32 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ appear in the State property. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Not_Offered" value="1"> + <tp:enumvalue suffix="Pending" value="1"> <tp:docstring> - 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 <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 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 <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="Local_Pending" value="3"> - <tp:docstring> - The file transfer is waiting to be accepted/closed locally. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Remote_Pending" value="4"> - <tp:docstring> - The file transfer is waiting to be accepted/closed remotely. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Open" value="5"> + <tp:enumvalue suffix="Open" value="3"> <tp:docstring> The file transfer is open for traffic. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Completed" value="6"> + <tp:enumvalue suffix="Completed" value="4"> <tp:docstring> The file transfer has been completed successfully. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Cancelled" value="7"> + <tp:enumvalue suffix="Cancelled" value="5"> <tp:docstring> The file transfer has been cancelled. </tp:docstring> @@ -323,10 +343,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="AcceptFile" tp:name-for-bindings="Accept_File"> <tp:docstring> - 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 - <tp:member-ref>InitialOffset</tp:member-ref> 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 + <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> @@ -380,19 +402,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring> - 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. </tp:docstring> </tp:error> </tp:possible-errors> </method> - <method name="OfferFile" tp:name-for-bindings="Offer_File"> + <method name="ProvideFile" tp:name-for-bindings="Provide_File"> <tp:docstring> - 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. </tp:docstring> <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type"> <tp:docstring> @@ -431,9 +453,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring> - 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. </tp:docstring> </tp:error> </tp:possible-errors> @@ -474,6 +495,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </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> |