XEP-0105: Tree Transfer Stream Initiation Profile

WARNING: This document has been automatically Deferred after 12 months of inactivity in its previous Experimental state. Implementation of the protocol described herein is not recommended for production systems. However, exploratory implementations are encouraged to resume the standards process.

Table of Contents

1. Introduction

File transfers of entire trees require a lot more metadata and prior setup to link paths to files with unique ids so that clients can track them. This profile provides a more robust method of defining that metadata so that directory trees can be transfered.

2. Requirements

• Provide a full featured set of information that is applicable to tree transfers.
• Meta-data that is to be provided:
  • number of files
  • size of entire tree
  • list of files and stream ids

3. Usage

The tree transfer profile is in the "http://jabber.org/protocol/si/profile/tree-transfer" namespace. The profile is fairly simple: it consists of the root element with child elements that specify a directory structure of files with stream ids that will be used for each file.

This profile requires support for the File Transfer profile described in SI File Transfer (XEP-0096) [1]. Once you have accepted this SI, a new SI using the File Transfer profile will be offered for each file in the tree. This profile provides a mapping of files with paths and reserved stream ids which will be used to auto-accept a File Transfer SI that uses that same stream id from the sender.

The root element is <tree> and has two attributes. The attributes are used only during the offer stage of stream initiation:

• size - The size, in bytes, of all of the files to be sent.
• numfiles - The number of files/File Transfer SIs that are in the tree.

The size and numfiles attributes MUST be present in the profile.

The only possible child element of the root is <directory/> since there are other specifications that handle single file transfers. The directory structure is sent in a hierarchical manner with nested <directory/> and/or <file/> tags. One or more <file/> elements will be sent, one for each file. One or more <directory/> elements will be sent, one for each directory.

The <directory/> element has one attribute:

• name - The name of the directory to create on the target system.

The attribute is REQUIRED on each <directory/> element.

The <file/> element has two attributes:

• sid - The stream id that MUST be sent for the File Transfer SI.
• name - The name of the file. The file should be saved to the same location in the target directory tree as the <directory/> hierarchy defines.

Both attributes are REQUIRED on each <file/> element. The total number of <file> elements MUST equal the numfiles attribute sent in the <tree/> element.

The stream-method that is accepted for a Tree Profile SI MUST be remembered and the subsequent File Transfer SIs MUST NOT provide a Feature Negotiation packet. The stream-method has already been chosen and should be used for all of the streams.

Implementations of this profile MUST support Stream Initiation (XEP-0095) [2] and XEP-0096.

4. Examples

Example 1. Profile Usage in Stream Initiation Offer

<iq type='set' id='offer1' to='receiver@jabber.org/resource'>
  <si
    xmlns='http://jabber.org/protocol/si'
    id='a0'
    profile='http://jabber.org/protocol/si/profile/tree-transfer'>
    <tree
      xmlns='http://jabber.org/profile/si/profile/tree-transfer'
      numfiles='9'
      size='80500'>
      <directory name='cd_collection'>
        <file sid='ft1' name='coll.index'/>
        <directory name='album1'>
          <file sid='ft2' name='song1.mp3'/>
          <file sid='ft3' name='song2.mp3'/>
          <file sid='ft4' name='song3.mp3'/>
          <file sid='ft5' name='song4.mp3'/>
        </directory>
        <directory name='album2'>
          <file sid='ft6' name='song1.mp3'/>
          <file sid='ft7' name='song2.mp3'/>
          <file sid='ft8' name='song3.mp3'/>
          <file sid='ft9' name='song4.mp3'/>
        </directory>
      </directory>
    </tree>
    <feature xmlns='http://jabber.org/protocol/feature-neg'>
      <x xmlns='jabber:x:data'>
        <field var='stream-method' type='list-single'>
          <option><value>http://jabber.org/protocol/bytestreams</value></option>
          <option><value>http://jabber.org/protocol/ibb</value></option>
        </field>
      </x>
    </feature>
  </si>
</iq>

Example 2. Simple Profile Usage in Stream Initiation Result

<iq type='result' to='sender@jabber.org/resource' id='offer1'>
  <si xmlns='http://jabber.org/protocol/si'>
    <feature xmlns='http://jabber.org/protocol/feature-neg'>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='stream-method'>
          <value>http://jabber.org/protocol/bytestreams</value>
        </field>
      </x>
    </feature>
  </si>
</iq>

Example 3. Subsequent File Transfer Offer

<iq type='set' id='offer2' to='receiver@jabber.org/resource'>
  <si xmlns='http://jabber.org/protocol/si'
      id='ft1'
      mime-type='text/plain'
      profile='http://jabber.org/protocol/si/profile/file-transfer'>
    <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
          name='coll.index'
          size='500'/>
  </si>
</iq>

Example 4. Subsequent File Transfer Result

<iq type='result' to='sender@jabber.org/resource' id='offer2'>
  <si xmlns='http://jabber.org/protocol/si'/>
</iq>

Above is repeated for ft2, ft3, etc...

5. IANA Considerations

No interaction with the Internet Assigned Numbers Authority (IANA) [3] is required as a result of this document.

6. XMPP Registrar Considerations

The profile described in this document will be registered with XMPP Registrar [4] as a valid Stream Initiation profile.

7. XML Schema

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/si/profile/tree-transfer'
    xmlns='http://jabber.org/protocol/si/profile/tree-transfer'
    elementFormDefault='qualified'>

  <xs:element name='tree'>
    <xs:complexType>
      <xs:attribute name='numfiles' use='required' type='xs:integer'/>
      <xs:attribute name='size' use='required' type='xs:integer'/>
      <xs:element ref='directory' minOccurs='0' maxOccurs='1'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='directory'>
    <xs:complexType>
      <xs:attribute name='name' use='required' type='xs:string'/>
      <xs:element ref='directory' minOccurs='0' maxOccurs='unbounded'/>
      <xs:element ref='file' minOccurs='0' maxOccurs='unbounded'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='file'>
    <xs:complexType>
      <xs:attribute name='name' use='required' type='xs:string'/>
      <xs:attribute name='sid' use='required' type='xs:string'/>
    </xs:complexType>
  </xs:element>

</xs:schema>

Appendices

Appendix A: Document Information

Series: XEP
Number: 0105
Publisher: XMPP Standards Foundation
Status: Deferred
Type: Standards Track
Version: 0.3.1
Last Updated: 2018-11-03
Approving Body: XMPP Council
Dependencies: XEP-0095, XEP-0096
Supersedes: None
Superseded By: None
Short Name: si-treetransfer
Source Control: HTML
This document in other formats: XML  PDF

Appendix B: Author Information

Appendix C: Legal Notices

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) 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.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

The following requirements 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".

Appendix G: Notes

Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

END