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.

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.

Note: The content 'creator' attribute does not specify who created or is sending the file, it only specifies which party to the session added the Jingle content to the session.

To start a File Offer, the initiator sends a Jingle session-initiation request to a potential responder. The request specifies three things:

1. A content 'senders' attribute with the value of 'initiator' to indicate this is a File Offer.
2. 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.
3. An appropriate transport method.

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).

The flow is as follows.

First the initiator sends a Jingle session-initiate.

Note: Inclusion of the <range/> child of the <file/> element indicates that the initiator supports ranged transfers as described below under Ranged Transfers.

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 Checksum.

The responder immediately acknowledges receipt of the Jingle session-initiate.

The initiator then attempts to initiate a SOCKS5 Bytestream with the responder as described in XEP-0260 and XEP-0065. 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 Ranged Transfers. If the responder includes a <range /> element with a limit or offset, the File Sender SHOULD respect the provided range settings.

The initiator acknowledges the Jingle session-accept.

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 Use of Jingle Content Senders) 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.

See File not Available for how to respond if the requester does not have permission to request the file, or if the file cannot be found.

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.

The other party then acks the content-add request.

At this point, the content-add request needs to be either accepted or rejected using Jingle content-accept or content-reject actions.

As in XEP-0096, 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.

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).

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.

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.

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.

The other party then acks the content-remove request.

If after removing the content there are no other Jingle contents the session MUST be terminated as described in the next section.

Once all file content in the session has been transfered, either party MAY acknowledge receipt of the received files (see Received) 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).

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.

At any time during the lifetime of the file transfer session, the File Sender can communicate the checksum of the file to the File Receiver.

This can be done in the session-initiate message if the File Sender already knows the checksum, as shown above in Example 3.

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;.

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.

If the initiator wishes to communicate only the hashing algorithm at the beginning of the session (e.g., because it has not yet calculated the checksum), it can send an empty <hash/> element (without a checksum in the XML character data as shown in the previous examples) in the session-initiate message; this enables the recipient to check the file during the transfer session (which can be helpful in the case of transfers that are truncated or fail mid-stream).

If a requested file cannot be found (or the requester does not have permission to request or know about the existence of the file in question), then the File Sender SHOULD send either a session-terminate or content-reject action in response to the session-initiate or content-add request, and SHOULD include a Jingle reason of <failed-application/> and MAY include an application specific reason of a <file-not-available/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:errors:0' namespace.

There are several situations where a File Receiver might wish to abort a transfer due to an excess of file data, for example:

• The File Receiver has reached a file system storage quota or other hard limit that prevents continuing to receive file data.
• The File Sender has continued sending data past the initially specified size of the file.

In such cases, the File Receiver MAY abort the transfer by sending a Jingle session-terminate (or content-remove as appropriate) which includes a Jingle reason of <media-error/> and MAY include an application specific reason of a <file-too-large/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:errors:0' namespace.

To prevent denial of service and other attacks, the File Receiver is fully within its rights to drop received data or not send a session-terminate message.

All implementations MUST support the Jingle In-Band Bytestreams Transport Method (XEP-0261) as a reliable method of last resort. An implementation SHOULD support other transport methods as well, especially ICE-TCP (RFC 6544) and the Jingle SOCKS5 Bytestreams Transport Method (XEP-0260).

An application MAY present transport methods in any order, except that the Jingle In-Band Bytestreams Transport Method MUST be the lowest preference.

Support for Jingle file transfer can be determined through discovery of the 'urn:xmpp:jingle:apps:file-transfer:5' namespace &VNOTE;, via either service discovery (XEP-0030) or entity capabilities (XEP-0115). If the initiator knows that the responder supports Jingle file transfer, it SHOULD first attempt negotiation using Jingle rather than Stream Initiation.

This specification defines the following XML namespace:

• urn:xmpp:jingle:apps:file-transfer:5

Upon advancement of this specification from a status of Experimental to a status of Draft, the ®ISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.

The XMPP Registrar shall include "file-transfer" in its registry of Jingle application formats. The registry submission is as follows: