xeps/xep-0105.xml

206 wiersze
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 &lt;tree&gt; 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 &lt;directory/&gt; since there are other specifications that handle single file transfers. The directory structure is sent in a hierarchical manner with nested &lt;directory/&gt; and/or &lt;file/&gt; tags. One or more &lt;file/&gt; elements will be sent, one for each file. One or more &lt;directory/&gt; elements will be sent, one for each directory.</p>
<p>The &lt;directory/&gt; 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 &lt;directory/&gt; element.</p>
<p>The &lt;file/&gt; 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 &lt;directory/&gt; hierarchy defines.</li>
</ul>
<p>Both attributes are REQUIRED on each &lt;file/&gt; element. The total number of &lt;file&gt; elements MUST equal the numfiles attribute sent in the &lt;tree/&gt; 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 &REGISTRAR; 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>