<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE xep SYSTEM 'xep.dtd' [ <!ENTITY % ents SYSTEM 'xep.ent'> %ents; ]> <?xml-stylesheet type='text/xsl' href='xep.xsl'?> <xep> <header> <title>Tree Transfer Stream Initiation Profile</title> <abstract>A profile describing metadata for transferring trees of files using stream inititation.</abstract> &LEGALNOTICE; <number>0105</number> <status>Deferred</status> <type>Standards Track</type> <sig>Standards</sig> <dependencies> <spec>XEP-0095</spec> <spec>XEP-0096</spec> </dependencies> <supersedes/> <supersededby/> <shortname>si-treetransfer</shortname> &reatmon; <revision> <version>0.3.1</version> <date>2018-11-03</date> <initials>pep</initials> <remark>Fix a bunch of typos, batch-style.</remark> </revision> <revision> <version>0.3</version> <date>2003-09-22</date> <initials>rwe</initials> <remark>Updated directory structure from flat to hierarchical.</remark> </revision> <revision> <version>0.2</version> <date>2003-07-23</date> <initials>rwe</initials> <remark>Fixed bad data types in the schema.</remark> </revision> <revision> <version>0.1</version> <date>2003-07-09</date> <initials>rwe</initials> <remark>Initial version.</remark> </revision> </header> <section1 topic='Introduction'> <p>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.</p> </section1> <section1 topic='Requirements'> <ul> <li>Provide a full featured set of information that is applicable to tree transfers.</li> <li>Meta-data that is to be provided: <ul> <li>number of files</li> <li>size of entire tree</li> <li>list of files and stream ids</li> </ul> </li> </ul> </section1> <section1 topic='Usage'> <p>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.</p> <p>This profile requires support for the File Transfer profile described in &xep0096;. 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.</p> <p>The root element is <tree> and has two attributes. The attributes are used only during the offer stage of stream initiation:</p> <ul> <li><em>size</em> - The size, in bytes, of all of the files to be sent.</li> <li><em>numfiles</em> - The number of files/File Transfer SIs that are in the tree.</li> </ul> <p>The <em>size</em> and <em>numfiles</em> attributes MUST be present in the profile.</p> <p>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.</p> <p>The <directory/> element has one attribute:</p> <ul> <li><em>name</em> - The name of the directory to create on the target system.</li> </ul> <p>The attribute is REQUIRED on each <directory/> element.</p> <p>The <file/> element has two attributes:</p> <ul> <li><em>sid</em> - The stream id that MUST be sent for the File Transfer SI.</li> <li><em>name</em> - The name of the file. The file should be saved to the same location in the target directory tree as the <directory/> hierarchy defines.</li> </ul> <p>Both attributes are REQUIRED on each <file/> element. The total number of <file> elements MUST equal the numfiles attribute sent in the <tree/> element.</p> <p>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.</p> <p>Implementations of this profile MUST support &xep0095; and XEP-0096.</p> </section1> <section1 topic='Examples'> <example caption='Profile Usage in Stream Initiation Offer'><![CDATA[ <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> <example caption='Simple Profile Usage in Stream Initiation Result'><![CDATA[ <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> <example caption='Subsequent File Transfer Offer'><![CDATA[ <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> <example caption='Subsequent File Transfer Result'><![CDATA[ <iq type='result' to='sender@jabber.org/resource' id='offer2'> <si xmlns='http://jabber.org/protocol/si'/> </iq> ]]></example> <p>Above is repeated for ft2, ft3, etc...</p> </section1> <section1 topic='IANA Considerations'> <p> No interaction with &IANA; is required as a result of this document. </p> </section1> <section1 topic='XMPP Registrar Considerations'> <p> The profile described in this document will be registered with ®ISTRAR; as a valid Stream Initiation profile. </p> </section1> <section1 topic='XML Schema'> <code><![CDATA[ <?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> ]]></code> </section1> </xep>