mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-24 10:12:19 -05:00
206 lines
8.4 KiB
XML
206 lines
8.4 KiB
XML
<?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>
|