mirror of https://github.com/moparisthebest/xeps
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
205 lines
8.4 KiB
205 lines
8.4 KiB
<?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>
|
|
|