No Description
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.

xep-0105.xml 8.2KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199
  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY % ents SYSTEM 'xep.ent'>
  4. %ents;
  5. ]>
  6. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  7. <xep>
  8. <header>
  9. <title>Tree Transfer Stream Initiation Profile</title>
  10. <abstract>A profile describing meta-data for transferring trees of files using stream inititation.</abstract>
  11. &LEGALNOTICE;
  12. <number>0105</number>
  13. <status>Deferred</status>
  14. <type>Standards Track</type>
  15. <sig>Standards</sig>
  16. <dependencies>
  17. <spec>XEP-0095</spec>
  18. <spec>XEP-0096</spec>
  19. </dependencies>
  20. <supersedes/>
  21. <supersededby/>
  22. <shortname>si-treetransfer</shortname>
  23. &reatmon;
  24. <revision>
  25. <version>0.3</version>
  26. <date>2003-09-22</date>
  27. <initials>rwe</initials>
  28. <remark>Updated directory structure from flat to hierarchical.</remark>
  29. </revision>
  30. <revision>
  31. <version>0.2</version>
  32. <date>2003-07-23</date>
  33. <initials>rwe</initials>
  34. <remark>Fixed bad data types in the schema.</remark>
  35. </revision>
  36. <revision>
  37. <version>0.1</version>
  38. <date>2003-07-09</date>
  39. <initials>rwe</initials>
  40. <remark>Initial version.</remark>
  41. </revision>
  42. </header>
  43. <section1 topic='Introduction'>
  44. <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>
  45. </section1>
  46. <section1 topic='Requirements'>
  47. <ul>
  48. <li>Provide a full featured set of information that is applicable to tree transfers.</li>
  49. <li>Meta-data that is to be provided:
  50. <ul>
  51. <li>number of files</li>
  52. <li>size of entire tree</li>
  53. <li>list of files and stream ids</li>
  54. </ul>
  55. </li>
  56. </ul>
  57. </section1>
  58. <section1 topic='Usage'>
  59. <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>
  60. <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>
  61. <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>
  62. <ul>
  63. <li><em>size</em> - The size, in bytes, of all of the files to be sent.</li>
  64. <li><em>numfiles</em> - The number of files/File Transfer SIs that are in the tree.</li>
  65. </ul>
  66. <p>The <em>size</em> and <em>numfiles</em> attributes MUST be present in the profile.</p>
  67. <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>
  68. <p>The &lt;directory/&gt; element has one attribute:</p>
  69. <ul>
  70. <li><em>name</em> - The name of the directory to create on the target system.</li>
  71. </ul>
  72. <p>The attribute is REQUIRED on each &lt;directory/&gt; element.</p>
  73. <p>The &lt;file/&gt; element has two attributes:</p>
  74. <ul>
  75. <li><em>sid</em> - The stream id that MUST be sent for the File Transfer SI.</li>
  76. <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>
  77. </ul>
  78. <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>
  79. <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>
  80. <p>Implementations of this profile MUST support &xep0095; and XEP-0096.</p>
  81. </section1>
  82. <section1 topic='Examples'>
  83. <example caption='Profile Usage in Stream Initiation Offer'><![CDATA[
  84. <iq type='set' id='offer1' to='receiver@jabber.org/resource'>
  85. <si
  86. xmlns='http://jabber.org/protocol/si'
  87. id='a0'
  88. profile='http://jabber.org/protocol/si/profile/tree-transfer'>
  89. <tree
  90. xmlns='http://jabber.org/profile/si/profile/tree-transfer'
  91. numfiles='9'
  92. size='80500'>
  93. <directory name='cd_collection'>
  94. <file sid='ft1' name='coll.index'/>
  95. <directory name='album1'>
  96. <file sid='ft2' name='song1.mp3'/>
  97. <file sid='ft3' name='song2.mp3'/>
  98. <file sid='ft4' name='song3.mp3'/>
  99. <file sid='ft5' name='song4.mp3'/>
  100. </directory>
  101. <directory name='album2'>
  102. <file sid='ft6' name='song1.mp3'/>
  103. <file sid='ft7' name='song2.mp3'/>
  104. <file sid='ft8' name='song3.mp3'/>
  105. <file sid='ft9' name='song4.mp3'/>
  106. </directory>
  107. </directory>
  108. </tree>
  109. <feature xmlns='http://jabber.org/protocol/feature-neg'>
  110. <x xmlns='jabber:x:data'>
  111. <field var='stream-method' type='list-single'>
  112. <option><value>http://jabber.org/protocol/bytestreams</value></option>
  113. <option><value>http://jabber.org/protocol/ibb</value></option>
  114. </field>
  115. </x>
  116. </feature>
  117. </si>
  118. </iq>
  119. ]]></example>
  120. <example caption='Simple Profile Usage in Stream Initiation Result'><![CDATA[
  121. <iq type='result' to='sender@jabber.org/resource' id='offer1'>
  122. <si xmlns='http://jabber.org/protocol/si'>
  123. <feature xmlns='http://jabber.org/protocol/feature-neg'>
  124. <x xmlns='jabber:x:data' type='submit'>
  125. <field var='stream-method'>
  126. <value>http://jabber.org/protocol/bytestreams</value>
  127. </field>
  128. </x>
  129. </feature>
  130. </si>
  131. </iq>
  132. ]]></example>
  133. <example caption='Subsequent File Transfer Offer'><![CDATA[
  134. <iq type='set' id='offer2' to='receiver@jabber.org/resource'>
  135. <si xmlns='http://jabber.org/protocol/si'
  136. id='ft1'
  137. mime-type='text/plain'
  138. profile='http://jabber.org/protocol/si/profile/file-transfer'>
  139. <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
  140. name='coll.index'
  141. size='500'/>
  142. </si>
  143. </iq>
  144. ]]></example>
  145. <example caption='Subsequent File Transfer Result'><![CDATA[
  146. <iq type='result' to='sender@jabber.org/resource' id='offer2'>
  147. <si xmlns='http://jabber.org/protocol/si'/>
  148. </iq>
  149. ]]></example>
  150. <p>Above is repeated for ft2, ft3, etc...</p>
  151. </section1>
  152. <section1 topic='IANA Considerations'>
  153. <p>
  154. No interaction with &IANA; is required as a result of this document.
  155. </p>
  156. </section1>
  157. <section1 topic='XMPP Registrar Considerations'>
  158. <p>
  159. The profile described in this document will be registered with &REGISTRAR; as a valid Stream
  160. Initiation profile.
  161. </p>
  162. </section1>
  163. <section1 topic='XML Schema'>
  164. <code><![CDATA[
  165. <?xml version='1.0' encoding='UTF-8'?>
  166. <xs:schema
  167. xmlns:xs='http://www.w3.org/2001/XMLSchema'
  168. targetNamespace='http://jabber.org/protocol/si/profile/tree-transfer'
  169. xmlns='http://jabber.org/protocol/si/profile/tree-transfer'
  170. elementFormDefault='qualified'>
  171. <xs:element name='tree'>
  172. <xs:complexType>
  173. <xs:attribute name='numfiles' use='required' type='xs:integer'/>
  174. <xs:attribute name='size' use='required' type='xs:integer'/>
  175. <xs:element ref='directory' minOccurs='0' maxOccurs='1'/>
  176. </xs:complexType>
  177. </xs:element>
  178. <xs:element name='directory'>
  179. <xs:complexType>
  180. <xs:attribute name='name' use='required' type='xs:string'/>
  181. <xs:element ref='directory' minOccurs='0' maxOccurs='unbounded'/>
  182. <xs:element ref='file' minOccurs='0' maxOccurs='unbounded'/>
  183. </xs:complexType>
  184. </xs:element>
  185. <xs:element name='file'>
  186. <xs:complexType>
  187. <xs:attribute name='name' use='required' type='xs:string'/>
  188. <xs:attribute name='sid' use='required' type='xs:string'/>
  189. </xs:complexType>
  190. </xs:element>
  191. </xs:schema>
  192. ]]></code>
  193. </section1>
  194. </xep>