This document describes a content type used for transferring files with Jingle, using the Hypertext Transfer Protocol.
WARNING: This document has not yet been accepted for consideration or approved in any official manner by the XMPP Standards Foundation, and this document must not be referred to as an XMPP Extension Protocol (XEP). If this document is accepted as a XEP by the XMPP Council, it will be published at <http://www.xmpp.org/extensions/> and announced on the <email@example.com> mailing list.
Publisher: XMPP Standards Foundation
Type: Standards Track
Last Updated: 2007-02-05
Approving Body: XMPP Council
Dependencies: XMPP Core, XMPP IM, XEP-166
Superseded By: None
Short Name: Not yet assigned
This XMPP Extension Protocol is copyright 1999 - 2007 by the XMPP Standards Foundation (XSF) and is in full conformance with the XSF's Intellectual Property Rights Policy (<http://www.xmpp.org/extensions/ipr-policy.shtml>). This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).
The preferred venue for discussion of this document is the Standards discussion list: <http://mail.jabber.org/mailman/listinfo/standards>.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.
The following keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
The Jingle protocols, originally designed to enable XMPP clients to create voice sessions, has proven to be a suitable protocol for managing state in peer-to-peer sessions of any type. This document describes a filesharing content type that uses HTTP (see RFC 2068 ) to transfer files from one host to another.
Currently, File Transfer  is the preferred method of transfering files between two XMPP client using Stream Initiation . However, this protocol has some limitations addressed in the following design requirements for this protocol:
A Jingle HTTP File Transfer content description describes what files are being offered, and how to request them over HTTP. The <description/> element, qualified by the 'http://www.xmpp.org/extensions/xep-XXXX.html#ns' namespace, MUST contain two elements: <manifest/> which describes the files being offered, and <http/> which describes the paths hosted by the sender's HTTP server implementation.
<description xmlns='http://www.xmpp.org/extensions/xep-XXXX.html#ns'> <manifest> <file size='341'> <name>file.txt</name> </file> <file size='51321'> <name>picture.jpg</name> <image width='480' height='320'/> </file> <folder> <name>directory</name> </folder> </manifest> <http> <url name='source-path'>/source/23A53F01/</url> <url name='preview-path'>/preview/90266EA1/</url> </http> </description>
The <manifest/> element contains any number of <file/> and <folder/> elements, describing the files and directories being offered. Both the <file/> and <folder> elements SHOULD possess a 'size' attribute, whose value is the size of the file (or total size of all files within a directory) in bytes. If calculating the size of all the files within a directory is too resource-intensive, this attribute MAY be omitted.
Both the <file/> and <folder/> elements MUST contain a <name/> element, whose character data is the filename of the file or directory.
An image file SHOULD contain an <image/> child containing additional metadata about the file. The <image/> element SHOULD possess 'width' and 'height' attributes, describing the dimensions of the image in pixels.
An initiating client acts as an HTTP server, hosting files from the paths specified by 'preview-path' and 'source-path'. A receiving client acts as an HTTP client requesting files as needed. A client may create as many components as it desires, over which it can make an HTTP request. A receiver creates the components as negotiated by the transport type, listens for HTTP requests on them, and responds with the appropriate HTTP response.
Before the session is accepted by a 'session-accept' message, but after the content and transport are accepted, the initiating client should respect requests to the preview path, as the receiving client may wish to preview the offered files before accepting the transfer.
This preview SHOULD be done for image files, but MAY be done for any file. In either case, the initiating client MUST respond with an image file. The receiving client MAY request that the preview be a certain size by adding width and height queries to the requested URL. The initiating client SHOULD honor the requested size, but MAY send a preview of any size.
If the client cannot offer a preview image it MUST return an HTTP 404 error
GET /preview/90266EA1/picture.jpg?width=50&height=50 HTTP/1.1
HTTP/1.1 200 Content-Type: image/jpg Content-length: 4582 [image data]
Once the session has been accepted, by sending a 'session-accept' message, the receiver SHOULD preform HTTP GET requests on the the files in 'source-path.'
GET /source/23A53F01/file.txt HTTP/1.1
The initator MUST respond with the requested file, or with with the appropriate HTTP error, when applicable
HTTP/1.1 200 Content-Type: text/plain Content-length: 341 [file data]
If the URL requested represents a folder, rather than a file, the client responds with a document of content type 'application/x-tar', which contains the contents of the directory in tar file format
GET /source/23A53F01/directory HTTP/1.1
HTTP/1.1 200 Content-Type: application/x-tar Content-length: 98121 [tar data]
The initiating client SHOULD send a <complete/> description-info message, qualified by the 'http://www.xmpp.org/extensions/xep-XXXX#ns' namespace when the recipient has finished receiving all the offered files.
<iq firstname.lastname@example.org/Filereceive' id='jingle-ft' type='set'> <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns' action='description-info' sid='5341736A17'> <complete xmlns='http://www.xmpp.org/extensions/xep-XXXX.html#ns'/> </jingle> </iq>
To support resuming of interrupted transfers, clients SHOULD support Range as defiend in section 14.36 of RFC 2616 .
As with all applications that allow files to be downloaded, clients must take care to protect file recipients from potentially harmful files.
This document requires no interaction with the Internet Assigned Numbers Authority (IANA) .
The XMPP Registrar  includes 'http://xmpp.org/extensions/xep-XXXX.html#ns' in its registry of protocol namespaces.
5. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.
6. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://www.xmpp.org/registrar/>.