xeps/xep-0105.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
  <!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
  <title>Tree Transfer Stream Initiation Profile</title>
  <abstract>A profile describing meta-data for transferring trees of files using stream inititation.</abstract>
  &LEGALNOTICE;
  <number>0105</number>
  <status>Deferred</status>
  <type>Standards Track</type>
  <jig>Standards JIG</jig>
  <dependencies>JEP-0095, JEP-0096</dependencies>
  <supersedes>None</supersedes>
  <supersededby>None</supersededby>
  <shortname>si-treetransfer</shortname>
  &reatmon;
  <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 meta-data 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 meta-data 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 &jep0096;. 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 JEPs 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 &jep0095; and JEP-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 JEP.
  </p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
  <p>
    The profile described in this JEP 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>
</jep>