<abstract>This specification defines a Jingle application type for transferring a file from one entity to another. The protocol provides a modular framework that enables the exchange of information about the file to be transferred as well as the negotiation of parameters such as the transport to be used.</abstract>
<li>Recast the document to match the registration procedure defined by XEP-0166 for new application types.</li>
<li>Explicitly defined the schema of the <file/> element instead of referencing XEP-0096.</li>
<li>Defined the use of a 'length' attribute on <range/> elements. This attribute was always there because the <file/> and <range/> elements had been defined as the same as the parallel elements in XEP-0096, but the 'length' attribute was not explicitly referenced in this document.</li>
<li>Clarified the need for the 'senders' attribute on Jingle <content/> elements to distinguish between File Offers and File Requests.</li>
<li>Added the <file-not-found/> and <file-too-large/> reason types.</li>
<li>Clarified how to abort a file transfer via 'content-remove' or 'session-terminate' actions.</li>
<li>Added <received/> element for indicating that a transfer was successful, particularly when there are multiple transfers.</li>
<li>Removed the 'urn:xmpp:jingle:apps:file-transfer:info:2' namespace by putting all elements into the 'urn:xmpp:jingle:apps:file-transfer:4' namespace</li>
<remark><p>Added multi-file use case; updated spec to reflect XEP-0260 and XEP-0261; added algorithm attribute from XEP-0096; increased namespace versions from 1 to 2.</p></remark>
<remark><p>Clarified usage of Jingle actions as well as several ambiguous points in the text, including use of the range feature from XEP-0096.</p></remark>
<li>Because the jingle-s5b and jingle-ibb transport methods are backward-incompatible, incremented protocol version number from 0 to 1 and changed namespace from urn:xmpp:jingle:apps:file-transfer:0 to urn:xmpp:jingle:apps:file-transfer:2.</li>
<remark><p>Initial published version.</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2008-02-29</date>
<initials>psa</initials>
<remark><p>Corrected use of content-replace action; specified that the In-Band Bytestreams transport method is mandatory-to-implement but must have the lowest preference order.</p></remark>
<p>&xep0166; can be used to initiate and negotiate a wide range of peer-to-peer sessions. One session type of interest is file transfer. This document specifies an application format for negotiating Jingle file transfer sessions, where files are exchanged via any available reliable transport.</p>
<p>&xep0096; was the original XMPP protocol extension for file transfer negotiation. However, that protocol has several drawbacks, most related to the &xep0095; protocol on which it depends:</p>
<li><p>It does not enable a true, bidirectional negotiation; instead, the initiator sets the terms for the file transfer and the responder either accepts the terms or cancels the negotiation.</p></li>
<li><p>It is the only technology in the Jabber/XMPP protocol "stack" that uses <cite>XEP-0095: Stream Initiation</cite>. More modern technologies such as voice and video session negotiation use &xep0166;, and it would be helpful if implementors could re-use the same code for all negotiation use cases.</p></li>
<p>Note that Jingle file transfer is only as reliable as the transports on which it depends. In particular, SOCKS5 Bytestreams ("S5B") does not always result in NAT or firewall traversal. To work around that problem, this specification requires all implementations to support as a fallback mechanism In-Band Bytestreams ("IBB"), which usually results in a successful (if slow) file transfer. A more robust and adaptable option is ICE-TCP (RFC 6544); at the time of writing &xep0176; is being updated to include the ability to negotiate ICE-TCP candidates.</p>
<dd>A Jingle File Transfer Content is said to be a File Offer if the content creator is the same as the content sender (see <linkurl='#content-senders'>Use of Jingle Content Senders</link>).</dd>
</di>
<di>
<dt>File Request</dt>
<dd>A Jingle File Transfer Content is said to be a File Request if the content creator is the opposite of the content sender (see <linkurl='#content-senders'>Use of Jingle Content Senders</link>).</dd>
</di>
<di>
<dt>File Sender</dt>
<dd>The File Sender is the side of the Jingle session responsible for sending the file data. The File Sender is not necessarily the same entity as the Jingle session initiator, and an entity could be both a File Sender and File Receiver in the context of a single Jingle session with multiple files.</dd>
</di>
<di>
<dt>File Receiver</dt>
<dd>The File Receiver is the side of the Jingle session responsible for receiving the file data. The File Receiver is not necessarily the same entity as the Jingle session responder, and an entity could be both a File Receiver and File Sender in the context of a single Jingle session with multiple files.</dd>
</di>
</dl>
</section1>
<section1topic='Jingle Conformance'>
<p>In accordance with Section 12 of <cite>XEP-0166</cite>, this document specifies the following information related to the Jingle File Transfer ("Jingle FT") application type:</p>
<li><p>The application format negotiation process is defined in the <linkurl='#negotiation'>Negotiating a Jingle File Transfer Session</link> section of this document.</p></li>
<li><p>The semantics of the &DESCRIPTION; element are defined in the <linkurl='#format'>Application Format</link> section of this document.</p></li>
<li><p>A mapping of Jingle semantics to the Session Description Protocol is provided in the <linkurl='#sdp'>Mapping to Session Description Protocol</link> section of this document.</p></li>
<li><p>A Jingle File Transfer session SHOULD use a streaming transport method, not a datagram transport method.</p></li>
<li><p>Transport components are not used in Jingle File Transfer.</p></li>
<li>
<p>Content is to be sent and received as follows:</p>
<p>For streaming transports, outbound content shall be encoded into packets (as defined by the transport mechanism) without any other framing mechanism and sent in succession over the transport. Incoming data received over the transport shall be processed as a stream of packets, where each packet's content payload is entirely composed of the next portion of file data to be processed.</p>
<section2topic='Use of Jingle Content Senders'anchor='content-senders'>
<p>Jingle File Transfer makes critical use of the 'senders' attribute of Jingle &CONTENT; elements in order to specify which party is responsible for sending the described file. As such, Jingle File Transfer content MUST include a 'senders' attribute, where the allowed values are "initiator" and "responder". The semantics of the values "both" and "none" are undefined in Jingle File Transfer and thus NOT RECOMMENDED for use with Jingle File Transfer content.</p>
<p>In general, a Jingle File Transfer content is said to be a "File Offer" if the 'senders' attribute is the same as the role of the party adding the content to the session, and a "File Request" if the 'senders' value is the opposite role of the party adding the content.</p>
<p>Note: The content 'creator' attribute does <em>not</em> specify who created or is sending the file, it only specifies which party to the session added the Jingle content to the session.</p>
<tablecaption='Distinguishing File Offers and Requests'>
<tr>
<th>Jingle Session Role</th>
<th>Content Senders</th>
<th>File Transfer Type</th>
</tr>
<tr>
<td>initiator</td>
<td>initiator</td>
<td>File Offer</td>
</tr>
<tr>
<td>initiator</td>
<td>responder</td>
<td>File Request</td>
</tr>
<tr>
<td>responder</td>
<td>initiator</td>
<td>File Request</td>
</tr>
<tr>
<td>responder</td>
<td>responder</td>
<td>File Offer</td>
</tr>
</table>
</section2>
</section1>
<section1topic='Application Format'>
<p>A Jingle File Transfer session is described by a content type that contains one application format and one transport method. Each &CONTENT; element defines the details of a single file transfer. A Jingle negotiation MAY result in the establishment of multiple file transfers by including multiple &CONTENT; elements.</p>
<p>The application format consists of a file description contained within a &DESCRIPTION; element qualified by the "urn:xmpp:jingle:apps:file-transfer:5" namespace &VNOTE;. The file description is a <file/> element specifying metadata such as the name of the file, media type, etc., as illustrated in the following example.</p>
<td>A hash of the file content, using the <hash/> element defined in &xep0300; and qualifed by the 'urn:xmpp:hashes:2' namespace. Multiple hashes MAY be included for hash agility.</td>
<td>Alternatively to a <hash/> element, the initiator can also include a <hash-used/> element. This avoids the need to read the file twice to calculate the hash.</td>
<td>Either a <hash/> or a <hash-used/> element MUST be included when offering a file.</td>
<td>The media type of the file content, which SHOULD be a valid MIME-TYPE as registered with &IANA; (specifically, as listed at <<linkurl='http://www.iana.org/assignments/media-types'>http://www.iana.org/assignments/media-types</link>>). If not specified, the content is assumed to be "application/octet-stream".</td>
<td>RECOMMENDED when offering a file, otherwise OPTIONAL</td>
</tr>
<tr>
<td>name</td>
<td>The name of the file. The name SHOULD NOT contain characters or character sequences that would be interpreted as a directory structure by the local file system (e.g. "/", "\", "../", etc.). If any such characters or character sequences are present (possibly because the local and remote file systems use different syntax for directory structure), they SHOULD be escaped (e.g., via percent-encoding) before using the name as part of any file system operation. See <linkurl='#security'>Security Considerations</link>.</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>size</td>
<td>The length of the file's content, in bytes.</td>
<td>OPTIONAL, but SHOULD be present when offering a file.</td>
</tr>
<tr>
<td>range</td>
<td>The presence of the <range/> element indicates support of ranged transfers, and can be used to control where a transfer starts.</td>
<td>OPTIONAL</td>
</tr>
</table>
<p>One or more <hash/> elements MUST be present when offering a file, but those elements MAY be empty if the hash has not yet been computed. If there is no computed hash value, the <hash/> element(s) MUST possess an 'algo' attribute specifying which hash algorithm will be used. Once a hash has been calculated by the File Sender, the File Sender SHOULD inform the File Receiver of the hash value as described in <linkurl='#checksum'>Checksum</link>.</p>
<p>Additional elements MAY be included as children of the <file/> element to provide additional metadata about the file, such as &xep0264;.</p>
<p>The optional <range/> element MAY possess two attributes:</p>
<tablecaption='Range Element Attributes'>
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Inclusion</th>
</tr>
<tr>
<td>offset</td>
<td>Specifies the position, in bytes, from which to start transferring file data. This defaults to zero (0) if not specified.</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>length</td>
<td>Specifies the number of bytes to retrieve starting at offset. This defaults to the length of the file from offset to the end.</td>
<td>OPTIONAL</td>
</tr>
</table>
<p>Inclusion of a <range/> element in a File Offer indicates support of ranged transfers for future File Requests if the transfer is interrupted and needs to be restarted.</p>
<p>A <range/> element MAY include an 'offset' attribute set to begin the transfer at a point other than the start of the file, and MAY include a 'length' attribute to request a portion of the file smaller than the remaining length of the file. If no 'offset' or 'length' attributes are present then it is the same as if no <range/> element was present, because the default values of the attributes would indicate a requested range of the entire file. In general, the first byte of data to be transferred is at the (zero-indexed) position specified by the 'offset' value, with a total of 'length' bytes sent.</p>
</section1>
<section1topic='Negotiating a Jingle File Transfer Session'>
<p>In general, the process for negotiating a Jingle File Transfer session is as follows:</p>
<li>An application type of "urn:xmpp:jingle:apps:file-transfer:5". In particular, the <description/> element contains a <file/> elements describing the file to be sent.</li>
<p>In this example, the initiator is <romeo@montague.example>, the responder is <juliet@capulet.example>, the application type is a File Offer, and the transport method is jingle-s5b (XEP-0260).</p>
<p>The flow is as follows.</p>
<p>First the initiator sends a Jingle session-initiate.</p>
<p>Note: Inclusion of the <range/> child of the <file/> element indicates that the initiator supports ranged transfers as described below under <linkurl='#range'>Ranged Transfers</link>.</p>
<p>Note: Computing the hash of the file before sending it can slow down the process of file transfer, because the sending application needs to process the file twice. The File Sender might prefer to send the hash after the file transfer has begun, using a session-info message as described under <linkurl='#hash'>Checksum</link>.</p>
<p>The initiator then attempts to initiate a SOCKS5 Bytestream with the responder as described in <cite>XEP-0260</cite> and <cite>XEP-0065</cite>. In the meantime, the responder returns a Jingle session-accept. In the session-accept message, the <file/> element MAY contain a <range/> element to indicate that the receiver also supports ranged transfers as described below under <linkurl='#range'>Ranged Transfers</link>. If the responder includes a <range /> element with a limit or offset, the File Sender SHOULD respect the provided range settings.</p>
<p>If the File Sender has advertised the existence of a file that it hosts, such as by &xep0358;, or if a previous file transfer attempt has failed and the File Receiver would like to initiate another attempt, the File Receiver can "pull" the file from the File Sender. This is done by sending a Jingle session-initiate to the File Sender which includes a <content/> with the 'senders' attribute set to the opposite Jingle session role of the party requesting the file (see <linkurl='#content-senders'>Use of Jingle Content Senders</link>) and a <description/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:5' namespace and which includes a <file/> element with enough information included to form a "file selector" (see Section 5 of &rfc5547;) to identify the requested file.</p>
<p>See <linkurl='#file-not-available'>File not Available</link> for how to respond if the requester does not have permission to request the file, or if the file cannot be found.</p>
</section2>
<section2topic='Offering or Requesting Additional Files'>
<p>While the Jingle File Transfer session is active, either party MAY choose to add additional files (both offers and requests) to the transfer session. To do so, a Jingle content-add action is used, as shown in the following examples.</p>
<p>At this point, the content-add request needs to be either accepted or rejected using Jingle content-accept or content-reject actions.</p>
</section2>
<section2topic='Ranged Transfers'anchor='range'>
<p>As in <cite>XEP-0096</cite>, a transfer can include only part of a file (e.g., to restart delivery of a truncated transfer session at a point other than the start of the file). This is done using the <range/> element. The usage is illustrated in the following examples.</p>
<p>Let us imagine that the parties negotiate a file transfer session using, say, In-Band Bytestreams. During the transfer, the recipient goes offline unexpectedly and IBB stanzas from the File Sender to the File Receiver begin to bounce. When the recipient comes back online, the File Sender could initiate a new Jingle session and specify that it wants to send all chunks after byte 270336 (which might be the 66th chunk of size 4096).</p>
<examplecaption="File Sender requests session to send file, with range"><![CDATA[
<p>At any point, either party MAY choose to abort the transfer of a single file, or end the session entirely to abort all active transfers.</p>
<p>When there is only a single Jingle content or if a party wishes to abort the transfer of all files in the session, a session-terminate including a Jingle reason of <cancel /> is sent.</p>
<examplecaption='File Receiver aborts all active file transfers'><![CDATA[
<p>If a party chooses to abort the transfer of a single file out of several active transfers, a Jingle content-remove action is used, which MAY include a Jingle reason of <cancel/>, as shown in the following example.</p>
<examplecaption='File Receiver aborts the transfer'><![CDATA[
<p>If after removing the content there are no other Jingle contents the session MUST be terminated as described in the next section.</p>
</section2>
<section2topic='Ending the Session'>
<p>Once all file content in the session has been transfered, either party MAY acknowledge receipt of the received files (see <linkurl='#received'>Received</link>) or, if there are no other active file transfers, terminate the Jingle session with a Jingle session of <success/>. Preferably, sending the session-terminate is done by the last entity to finish receiving a file to ensure that all offered or requested files by either party have been completely received (up to the advertised sizes).</p>
<examplecaption='File Receiver ends the session after successfully receiving all files'><![CDATA[
<section1topic='Mapping to Session Description Protocol'anchor='sdp'>
<p>&rfc5547; defines the general process for including file transfer information in SDP.</p>
<p>The SDP media type for Jingle File Transfer can be "message" (e.g. when used with &rfc4975;) or "application"; however, this media value is not reflected in the Jingle File Transfer application format.</p>
<p>Any combination of <name/>, <size/>, <media-type/>and <hash/> values MAY be used to form a "file selector" (see Section 5 of &rfc5547;), which would be mapped to SDP as follows:</p>
<p>(The hash value MUST be encoded as hexadecimal with each byte separated by a colon.)</p>
<p>The <date/> value is the last modified time of the file, and thus is mapped as follows:</p>
<code><![CDATA[
a=file-date:modification:"<date>"]]></code>
<p>Note: the format used here for <date> is the date-time format defined in &rfc5322;.</p>
<p>If a range is specified, the SDP mapping requires both a start and stop offset. If no length was specified for the range, the stop offset is "*". If a length was specified, the stop offset is the <range/> offset value plus the length.</p>
<p>Once a file has been successfully received, the recipient MAY send a Jingle session-info message indicating receipt of the complete file, which consists of a <received/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:5' namespace. The <received/> element SHOULD contain 'creator' and 'name' attributes sufficient to identify the content that was received.</p>
<p>After the session-initiate message, this can also be done by sending a session-info message containing a <checksum/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:5' namespace. In such a case however, the session-initiate message MUST contain a <hash-used/> element. The <checksum/> element SHOULD contain 'creator' and 'name' attributes sufficient to identitfy the content the checksum belongs to. Additionally, the <checksum/> element MUST contain a <file/> element which MUST contain at least one <hash/> or <hash-used/> element qualified by the 'urn:xmpp:hashes:2' namespace. Each <hash/> element contains a checksum of the file data produced in accordance with the hashing function specified by the 'algo' attribute, which MUST be one of the functions listed in the &ianahashes;.</p>
<p>If a ranged transfer was requested, the <file/> element inside the <checksum/> element MAY include a <range/> element specifying the offset and length of the requested range, which in turn includes <hash/> element(s) with hashes of the data that was transferred for that range.</p>
<examplecaption="Initiator sends checksum in session-info for a specific range"><