Deferred
[xmpp:xmpp.git] / extensions / xep-0214.xml
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>File Repository and Sharing</title>
10   <abstract>While a protocol has been described for initiating a file transfer from one user to another, there is not yet a way for users to designate a set of files as available for retrieval by other users of their choosing. This extension fills that functionality, with additional features such as file versioning, multiple download mirrors across several internet protocols, collaborative modification of the file listing, and all the other benefits of Pubsub.</abstract>
11   <legal>This XMPP Extension Protocol is copyright 1999 - 2007 by the XMPP Standards Foundation (XSF) and is in full conformance with the XSF's Intellectual Property Rights Policy (<link url="http://www.xmpp.org/extensions/ipr-policy.shtml">http://www.xmpp.org/extensions/ipr-policy.shtml</link>). This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<link url="http://creativecommons.org/licenses/by/2.5/">http://creativecommons.org/licenses/by/2.5/</link>).</legal>
12   <number>0214</number>
13   <status>Deferred</status>
14   <type>Standards Track</type>
15   <jig>Standards JIG</jig>
16   <approver>Council</approver>
17   <dependencies>
18     <spec>XMPP Core</spec>
19     <spec>XEP-0001</spec>
20     <spec>XEP-0060</spec>
21     <spec>XEP-0082</spec>
22     <spec>XEP-0137</spec>
23   </dependencies>
24   <supersedes/>
25   <supersededby/>
26   <shortname>Not yet assigned</shortname>
27   <author>
28     <firstname>Nicholas</firstname>
29     <surname>Parker</surname>
30     <email>nickbp@gmail.com</email>
31     <jid>nickp@jabber.org</jid>
32   </author>
33   <revision>
34     <version>0.1</version>
35     <date>2007-04-20</date>
36     <initials>psa</initials>
37     <remark><p>Initial published version.</p></remark>
38   </revision>
39   <revision>
40     <version>0.0.3</version>
41     <date>2007-03-18</date>
42     <initials>nbp</initials>
43     <remark><p>Added support for Stream Initiation Requests. Clarified purpose of additional mirror types.</p></remark>
44   </revision>
45   <revision>
46     <version>0.0.2</version>
47     <date>2007-01-26</date>
48     <initials>nbp</initials>
49     <remark><p>Rewritten to use Pubsub.</p></remark>
50   </revision>
51   <revision>
52     <version>0.0.1</version>
53     <date>2006-09-01</date>
54     <initials>nbp</initials>
55     <remark><p>First draft.</p></remark>
56   </revision>
57 </header>
58 <section1 topic='Introduction' anchor='intro'>
59   <p>Describes how a Jabber user may find and retrieve files which other Jabber users have published. The listing of files is done through a Pubsub (XEP-0060) server, allowing multiple users to manage the same listing. Other features include file metadata, revisions, and download mirrors.</p>
60   <p>Retrieval of the files provided in the listing MAY be performed through any relevant protocol for transferring data (http, ftp, etc), but this protocol emphasizes the use of Stream Initiation (XEP-0137) to establish the connection.</p>
61 </section1>
62 <section1 topic='Requirements' anchor='reqs'>
63   <p>The protocol defined herein provides the following functionality:</p>
64   <ol>
65     <li>Publication of a list of available files to a Pubsub server, with tree structure, file metadata, user permissions, and file versioning.</li>
66     <li>Request that a file be sent from a Jabber contact directly to oneself using Stream Initiation.</li>
67   </ol>
68 </section1>
69 <section1 topic='Glossary' anchor='glossary'>
70   <table caption="File Sharing Terms">
71     <tr><th>File Listing</th><td>Top-level Pubsub Collection Node, containing information about files and/or subsections which a user or group of users have published.</td></tr>
72     <tr><th>Subsection</th><td>Non-Root Collection Node which containts files and/or other subsections.</td></tr>
73     <tr><th>File</th><td>Pubsub Node, stored within a File Listing, which describes all revisions of a given file. The filename and (optionally) description are provided here.</td></tr>
74     <tr><th>Revision</th><td>Pubsub Item which describes a given file revision. Other metadata which can vary between revisions is provided here (file size, checksum, available mirrors, etc).</td></tr>
75     <tr><th>Mirror</th><td>A location which has a given Revision available for download. Additional information about a given Mirror MAY be provided for protocols that require it. A list of available protocols is provided below.</td></tr>
76   </table>
77 </section1>
78 <section1 topic='Use Cases' anchor='usecases'>
79   
80   <section2 topic='File Listing' anchor='list'>
81     
82     <p>The following use cases describe tasks which are already covered by XEP-0060 in a more generic context. These tasks are explicitly described in order to demonstrate the wide range of capabilities afforded by this system and convey the data structure of the file listing itself. Consult XEP-0060 for the full range of node and user management commands as well as their server responses.</p>
83     
84     <section3 topic='Publication' anchor='list-publication'>
85       
86       <p>Juliet wishes to make her sonnets available for retrieval by the public. She creates a Root Pubsub Collection Node which will contain her file listing:</p>
87       
88       <example caption='Creating a New File Listing'><code><![CDATA[<iq type='set'
89     from='juliet@capulet.com/balcony'
90     to='pubsub.shakespeare.lit'
91     id='create3'>
92   <pubsub xmlns='http://jabber.org/protocol/pubsub'>
93     <create node='juliets_sonnets'/>
94     <configure>
95       <x xmlns='jabber:x:data' type='submit'>
96         <field var='FORM_TYPE' type='hidden'>
97           <value>http://jabber.org/protocol/pubsub#node_config</value>
98         </field>
99         <field var='pubsub#node_type'><value>collection</value></field>
100       </x>
101     </configure>
102   </pubsub>
103 </iq>
104
105 <iq type='set'
106     from='juliet@capulet.com/balcony'
107     to='pubsub.shakespeare.lit'
108     id='config2'>
109   <pubsub xmlns='http://jabber.org/protocol/pubsub'>
110     <configure node='juliets_sonnets'/>
111       <x xmlns='jabber:x:data' type='submit'>
112         <field var='FORM_TYPE' type='hidden'>
113           <value>http://jabber.org/protocol/pubsub#meta-data</value>
114         </field>
115         <field var='pubsub#title'><value>Juliet's Sonnets</value></field>
116         <field var='pubsub#description'><value>Optional Description</value></field>
117       </x>
118     </configure>
119   </pubsub>
120 </iq>
121         ]]></code></example>
122       
123       <p>Juliet also wishes to add a subsection for her sonnets about Romeo. She creates another Pubsub Collection Node under the Root Node:</p>
124       
125       <example caption='Adding a Subsection to the Listing'><code><![CDATA[<iq type='set'
126     from='juliet@capulet.com/balcony'
127     to='pubsub.shakespeare.lit'
128     id='create3'>
129   <pubsub xmlns='http://jabber.org/protocol/pubsub'>
130     <create node='35227eec194a4f3971a5f3771e9c2271'/>
131     <configure>
132       <x xmlns='jabber:x:data' type='submit'>
133         <field var='FORM_TYPE' type='hidden'>
134           <value>http://jabber.org/protocol/pubsub#node_config</value>
135         </field>
136         <field var='pubsub#collection'><value>juliets_sonnets</value></field>
137         <field var='pubsub#node_type'><value>collection</value></field>
138       </x>
139     </configure>
140   </pubsub>
141 </iq>
142
143 <iq type='set'
144     from='juliet@capulet.com/balcony'
145     to='pubsub.shakespeare.lit'
146     id='config2'>
147   <pubsub xmlns='http://jabber.org/protocol/pubsub'>
148     <configure node='35227eec194a4f3971a5f3771e9c2271'/>
149       <x xmlns='jabber:x:data' type='submit'>
150         <field var='FORM_TYPE' type='hidden'>
151           <value>http://jabber.org/protocol/pubsub#meta-data</value>
152         </field>
153         <field var='pubsub#title'><value>Sonnets About Romeo</value></field>
154         <field var='pubsub#description'><value>Optional Description</value></field>
155       </x>
156     </configure>
157   </pubsub>
158 </iq>
159         ]]></code></example>
160       
161     </section3>
162     <section3 topic='Subscription' anchor='list-subscription'>
163       
164       <p>Romeo wishes to view all of Juliet's shared sonnets. To do this, Romeo subscribes to the Root Collection Node:</p>
165       
166       <example caption='Subscription to entire File Listing'><code><![CDATA[<iq type='set'
167     from='romeo@montague.net/orchard'
168     to='pubsub.shakespeare.lit'
169     id='collsub2'>
170   <pubsub xmlns='http://jabber.org/protocol/pubsub'>
171     <subscribe jid='romeo@montague.net' node='juliets_sonnets'/>
172     <options>
173       <x xmlns='jabber:x:data'>
174         <field var='FORM_TYPE' type='hidden'>
175           <value>http://jabber.org/protocol/pubsub#subscribe_options</value>
176         </field>
177         <field var='pubsub#subscription_type'><value>items</value></field>
178         <field var='pubsub#subscription_depth'><value>all</value></field>
179       </x>
180     </options>
181   </pubsub>
182 </iq>
183           ]]></code></example>
184       
185     </section3>
186     <section3 topic='Addition' anchor='list-addition'>
187       
188       <p>Juliet has just finished a new sonnet and wishes to announce its availability on her File Listing. She adds the sonnet as a new Pubsub Node stored in her Collection Node, then inserts a first revision of her sonnet as an Item within that Node:</p>
189       
190       <example caption='Adding a new File'><code><![CDATA[<iq type='set'
191     from='juliet@capulet.com/balcony'
192     to='pubsub.shakespeare.lit'
193     id='create4'>
194   <pubsub xmlns='http://jabber.org/protocol/pubsub#node_config'>
195     <create node='a6190c5d38e22452041d1c5798eff3f5'/>
196     <configure>
197       <x xmlns='jabber:x:data' type='submit'>
198         <field var='pubsub#collection'><value>juliets_sonnets</value></field>
199       </x>
200     </configure>
201   </pubsub>
202 </iq>
203
204 <iq type='set'
205     from='juliet@capulet.com/balcony'
206     to='pubsub.shakespeare.lit'
207     id='config2'>
208   <pubsub xmlns='http://jabber.org/protocol/pubsub'>
209     <configure node='a6190c5d38e22452041d1c5798eff3f5'>
210       <x xmlns='jabber:x:data' type='submit'>
211         <field var='FORM_TYPE' type='hidden'>
212           <value>http://jabber.org/protocol/pubsub#meta-data</value>
213         </field>
214         <field var='pubsub#title'><value>sonnet.txt</value></field>
215         <field var='pubsub#description'><value>Sonnet 42</value></field>
216       </x>
217     </configure>
218   </pubsub>
219 </iq>
220
221 <iq type='set'
222     from='juliet@capulet.com/balcony'
223     to='pubsub.shakespeare.lit'
224     id='publish1'>
225   <pubsub xmlns='http://jabber.org/protocol/pubsub'>
226     <publish node='a6190c5d38e22452041d1c5798eff3f5'>
227       <item id='1'>
228         <entry xmlns='http://jabber.org/protocol/fileshare#item_meta-data'>
229           <size>5623</size>
230           <modified>2006-12-13T18:30:02Z</modified>
231           <checksum type="sha1">59282c5db190bdc3b152c5b38363442bfda8ebdd</checksum>
232           <mime>text/plain</mime>
233           <description>My Latest Sonnet!</description>
234           <mirrors>
235             <mirror type='sipub' description='File Transfer via capulet.com fileserver'>
236               <sipub xmlns='http://jabber.org/protocol/si-pub'
237                      from='fileserver@capulet.com'
238                      id='publish-sonnet.txt'
239                      mime-type='text/plain'
240                      profile='http://jabber.org/protocol/si/profile/file-transfer'>
241                 <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
242                       name='sonnet.txt'
243                       size='5623'/>
244               </sipub>
245             </mirror>
246             <mirror type='sipub' description='Jingle HTTP File Transfer via capulet.com fileserver'>
247               <sipub xmlns='http://jabber.org/protocol/si-pub'
248                      from='fileserver-httpft@capulet.com'
249                      id='publish-sonnet.txt'
250                      mime-type='text/plain'
251                      profile='http://jabber.org/protocol/si/profile/jingle-httpft'>
252                 <description xmlns='http://www.xmpp.org/extensions/xep-XXXX.html#ns'>
253                   <manifest>
254                     <file>
255                       <name>sonnet.txt</name>
256                     </file>
257                   </manifest>
258                   <http>
259                     <url name='source-path'>/source/23A53F01/</url>
260                     <url name='preview-path'>/preview/90266EA1/</url>
261                   </http>
262                 </description>
263               </sipub>
264             </mirror>
265             <mirror type='http' description='Shakespeare.lit Torrent'
266                     address='www.shakespeare.lit'
267                     ref='torrents/sonnet.torrent'/>
268             <mirror type='http' description='Shakespeare.lit Website'
269                     address='www.shakespeare.lit'
270                     ref='~juliet/sonnet.txt'/>
271             <mirror type='https' description='Shakespeare.lit Website (SSL)'
272                     address='ssl.shakespeare.lit'
273                     ref='~juliet/sonnet.txt'/>
274             <mirror type='ftp' description='Shakespeare.lit FTP'
275                     user='guest' pass='guest'
276                     address='files.shakespeare.lit' port='21'
277                     ref='public/sonnet.txt'/>
278             <mirror type='sftp' description='Shakespeare.lit SFTP'
279                     user='guest' pass='guest'
280                     address='ssh.shakespeare.lit' port='22'
281                     ref='public/sonnet.txt'/>
282             <mirror type='smb' description='Capulet Intranet SMB Share'
283                     user='guest' pass='guest'
284                     address='smbfiles.capulet.com'
285                     ref='juliet/mysonnets/sonnet.txt'/>
286           </mirrors>
287         </entry>
288       </item>
289     </publish>
290   </pubsub>
291 </iq>
292 ]]></code></example>
293       
294       <p>The Item ID is set to 1, signifying the first revision for this file. Subsequent revisions/items will have incremented ID values, like one would see in a versioning system such as CVS or SVN. Implementations MAY follow this convention, but are not required to do so. For example, a given implementation may instead mark revisions using version numbers ("Beta 1", "6.2", etc) or use other arbitrary strings. However, no two revisions of a given file may share the same ID.</p>
295       <p>Here is a listing of the possible metadata in a file revision (Item), each field is OPTIONAL:</p>
296
297       <table caption="Revision Metadata">
298         <tr><th>Size</th><td>The size, in bytes, of the file.</td></tr>
299         <tr><th>Modified</th><td>The last modified time of the revision. Follows the format described in XEP-0082. If a publisher prefers to only make a single revision available to clients, the publisher MAY instead update this value (and others, such as size and/or checksum) to announce that a new version of the file is available.</td></tr>
300         <tr><th>Checksum</th><td>A checksum of the revision, using the specified hash algorithm. Acceptable types are "sha512", "sha1", "md5", and "crc32".</td></tr>
301         <tr><th>Mime</th><td>The file's MIME type.</td></tr>
302         <tr><th>Description</th><td>Description text for the revision. As an example, could contain release notes.</td></tr>
303         <tr><th>Mirrors</th><td>A list of mirrors; their properties are defined below. If no downloads are available, MAY be left empty or removed entirely.</td></tr>
304       </table>
305       <p>Because Romeo is now subscribed, he receives notice of Juliet's addition:</p>
306       
307       <example caption='Notification of Addition'><code><![CDATA[<message from='pubsub.shakespeare.lit' to='romeo@montague.net' id='create4'>
308   <event xmlns='http://jabber.org/protocol/pubsub#event'>
309     <collection>
310       <node id='a6190c5d38e22452041d1c5798eff3f5'>
311         <x xmlns='jabber:x:data' type='result'>
312           <field var='FORM_TYPE' type='hidden'>
313             <value>http://jabber.org/protocol/pubsub#node_config</value>
314           </field>
315           <field var='pubsub#collection'><value>juliets_sonnets</value></field>
316         </x>
317       </node>
318     </collection>
319   </event>
320 </message>
321
322 <message from='pubsub.shakespeare.lit' to='romeo@montague.net' id='config2'>
323   <event xmlns='http://jabber.org/protocol/pubsub#event'>
324     <configuration node='a6190c5d38e22452041d1c5798eff3f5'>
325       <x xmlns='jabber:x:data' type='result'>
326         <field var='FORM_TYPE' type='hidden'>
327           <value>http://jabber.org/protocol/pubsub#meta-data</value>
328         </field>
329         <field var='pubsub#description'><var>Sonnet 42</var></field>
330         <field var='pubsub#title'><var>sonnet.txt</var></field>
331       </x>
332     </configuration>
333   </event>
334 </message>
335
336 <message from='pubsub.shakespeare.lit' to='romeo@montague.net' id='foo'>
337   <event xmlns='http://jabber.org/protocol/pubsub#event'>
338     <items node='a6190c5d38e22452041d1c5798eff3f5'>
339       <item id='1'>
340         <entry xmlns='http://jabber.org/protocol/fileshare#item_config'>
341           <size>5623</size>
342           <modified>2006-12-13T18:30:02Z</modified>
343           <checksum type="sha1">59282c5db190bdc3b152c5b38363442bfda8ebdd</checksum>
344           <mime>text/plain</mime>
345           <description>My Latest Sonnet!</description>
346           <mirrors>
347             ... MIRRORS ...
348           </mirrors>
349         </entry>
350       </item>
351     </items>
352   </event>
353 </message>
354 ]]></code></example>
355       
356       <p>The above examples give a listing of available mirror protocols in probable configurations. As described in the <link url="#impl">Implementation Notes</link>, only the sipub mirror type is REQUIRED, the others are only given as examples for common protocols which are not already compatible with SI. Here is a full listing of those protocols and their available settings:</p>
357       
358       <table caption="Mirror Settings">
359         <tr><th>Protocol</th>
360           <th>Description</th><th>Ref</th>
361           <th>Address</th><th>Port (default)</th>
362           <th>User</th><th>Pass</th></tr>
363         <tr><th><link url='#file-requests'>sipub</link></th>
364           <td>OPTIONAL</td><td></td>
365           <td></td><td></td>
366           <td></td><td></td></tr>
367         <tr><th>http</th>
368           <td>OPTIONAL</td><td>REQUIRED</td>
369           <td>REQUIRED</td><td>OPTIONAL (80)</td>
370           <td>OPTIONAL</td><td>OPTIONAL</td></tr>
371         <tr><th>https</th>
372           <td>OPTIONAL</td><td>REQUIRED</td>
373           <td>REQUIRED</td><td>OPTIONAL (443)</td>
374           <td>OPTIONAL</td><td>OPTIONAL</td></tr>
375         <tr><th>ftp</th>
376           <td>OPTIONAL</td><td>REQUIRED</td>
377           <td>REQUIRED</td><td>OPTIONAL (21)</td>
378           <td>OPTIONAL</td><td>OPTIONAL</td></tr>
379         <tr><th>sftp</th>
380           <td>OPTIONAL</td><td>REQUIRED</td>
381           <td>REQUIRED</td><td>OPTIONAL (22)</td>
382           <td>OPTIONAL</td><td>OPTIONAL</td></tr>
383         <tr><th>smb</th>
384           <td>OPTIONAL</td><td>REQUIRED (Incl. Share name)</td>
385           <td>REQUIRED</td><td>OPTIONAL (445)</td>
386           <td>OPTIONAL</td><td>OPTIONAL</td></tr>
387       </table>
388
389       <p>The Description field is where an arbitrary description of the mirror MAY be placed. For example, if a File Listing is advertising mirrors which are located in different geographic locations, then this field may be used to specify those locations.</p>
390       <p>The Ref field is a unique identifier which is used to request the file from the mirror server. In the above examples, it is used as a path to the file.</p>
391       <p>The address and port fields describe where the file may be retrieved using the specified protocol. If a port is not provided, the default value (specified in parentheses) is assumed.</p>
392       <p>The User and Pass fields are for providing credentials which, if given by the File Listing, SHOULD be used when requesting the file. For example, an sftp mirror MAY require that the user log in using specified credentials before the file may be retrieved.</p>
393
394     </section3>
395     <section3 topic='New Revisions' anchor='list-newrevisions'>
396       
397       <p>Juliet has revised her sonnet and wishes to publish the new version, while still leaving the original copy available for retrieval. To do this, she inserts a new Item, representing her new revision, into the file's Node:</p>
398       
399       <example caption='Adding a new Revision'><code><![CDATA[<iq type='set'
400     from='juliet@capulet.com/balcony'
401     to='pubsub.shakespeare.lit'
402     id='publish1'>
403   <pubsub xmlns='http://jabber.org/protocol/pubsub'>
404     <publish node='a6190c5d38e22452041d1c5798eff3f5'>
405       <item id='2'>
406         <entry xmlns='http://jabber.org/protocol/fileshare#item_config'>
407           <size>6102</size>
408           <modified>2007-01-13T18:30:02Z</modified>
409           <checksum type="md5">6aaa20212a99548765b3b15f24f19aaa</checksum>
410           <checksum type="sha1">97cbc0e445435af94db5cc2133b94ab5faf1399a</checksum>
411           <mime>text/plain</mime>
412           <description>A revised copy, fixed some spelling errors.</description>
413           <mirrors>
414             <mirror type='ftp' description='Shakespeare.lit FTP'
415                     user='guest' pass='guest'
416                     address='files.shakespeare.lit' port='21'
417                     ref='public/juliet/sonnet2.txt'/>
418             <mirror type='http' description='Shakespeare.lit Website'
419                     address='www.shakespeare.lit'
420                     ref='~juliet/sonnet2.txt'/>
421             <mirror type='sipub' description='File Transfer via capulet.com fileserver'>
422               <sipub xmlns='http://jabber.org/protocol/si-pub'
423                      from='fileserver@capulet.com'
424                      id='publish-sonnet2.txt'
425                      mime-type='text/plain'
426                      profile='http://jabber.org/protocol/si/profile/file-transfer'>
427                 <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
428                       name='sonnet2.txt'
429                       size='6102'/>
430               </sipub>
431             </mirror>
432           </mirrors>
433         </entry>
434       </item>
435     </publish>
436   </pubsub>
437 </iq>
438           ]]></code></example>
439       
440     </section3>
441     <section3 topic='Modification/Deletion' anchor='list-deletion'>
442       
443       <p>Juliet has uploaded a copy of her revised sonnet to a new mirror, and wishes to let her subscribers know about this secondary source. She is able to do this by modifying the revision in question to include a reference to her website, overwriting the existing mirrors in the Item with an updated list:</p>
444       
445       <example caption='Modifying a Revision'><code><![CDATA[<iq type='set'
446     from='juliet@capulet.com/balcony'
447     to='pubsub.shakespeare.lit'
448     id='publish1'>
449   <pubsub xmlns='http://jabber.org/protocol/pubsub'>
450     <publish node='a6190c5d38e22452041d1c5798eff3f5'>
451       <item id='2'>
452         <entry xmlns='http://jabber.org/protocol/fileshare#item_config'>
453           <mirrors>
454             <mirror type='ftp' description='Shakespeare.lit FTP'
455                     user='guest' pass='guest'
456                     address='files.shakespeare.lit' port='21'
457                     ref='public/juliet/sonnet2.txt'/>
458             <mirror type='http' description='Shakespeare.lit Website'
459                     address='www.shakespeare.lit'
460                     ref='~juliet/sonnet2.txt'/>
461             <mirror type='sipub' description='File Transfer via capulet.com fileserver'>
462               <sipub xmlns='http://jabber.org/protocol/si-pub'
463                      from='fileserver@capulet.com'
464                      id='publish-sonnet2.txt'
465                      mime-type='text/plain'
466                      profile='http://jabber.org/protocol/si/profile/file-transfer'>
467                 <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
468                       name='sonnet2.txt'
469                       size='6102'/>
470               </sipub>
471             </mirror>
472             <mirror type='http' description='Shakespeare.lit Boston Mirror'
473                     address='www.capulet.com'
474                     ref='~juliet/sonnet2.txt'/>
475           </mirrors>
476         </entry>
477       </item>
478     </publish>
479   </pubsub>
480 </iq>
481           ]]></code></example>
482
483       <p>Juliet now wishes to allow others to contribute to her sonnet collection. She gives owner access for the entire Listing to Romeo, and publisher access to her nurse:</p>
484       
485       <example caption='Modifying Users'><code><![CDATA[<iq type='set'
486     from='juliet@capulet.com/balcony'
487     to='pubsub.shakespeare.lit'
488     id='ent3'>
489   <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
490     <affiliations node='juliets_sonnets'>
491       <affiliation jid='nurse@capulet.com' affiliation='publisher'/>
492       <affiliation jid='romeo@montague.net' affiliation='owner'/>
493     </affiliations>
494   </pubsub>
495 </iq>
496           ]]></code></example>
497
498       <p>Romeo uses his owner access to remove the older revision of Juliet's sonnet:</p>
499
500       <example caption='Deleting a Revision'><code><![CDATA[<iq type='set'
501     from='romeo@montague.net/orchard'
502     to='pubsub.shakespeare.lit'
503     id='retract1'>
504   <pubsub xmlns='http://jabber.org/protocol/pubsub'>
505     <retract node='a6190c5d38e22452041d1c5798eff3f5'>
506       <item id='1'/>
507     </retract>
508   </pubsub>
509 </iq>
510           ]]></code></example>
511
512       <p>Other deletion, modification, and user management operations are available as described in XEP-0060. These examples are provided here to explicitly illustrate the capabilities offered by this system.</p>
513
514     </section3>
515   </section2>
516   
517   <section2 topic='File Requests' anchor='file-requests'>
518
519     <p>Romeo is interested in seeing what files Juliet has made available. To do this, Romeo sends Juliet a request for repositories which she is associated with:</p>
520
521     <example caption='Request for File Repository listing'><code><![CDATA[<iq type='get'
522     from='romeo@montague.net/orchard'
523     to='juliet@capulet.com'
524     id='repolistreq'>
525   <fileshare xmlns='http://jabber.org/protocol/si/profile/fileshare'>
526     <list/>
527   </fileshare>
528 </iq>
529         ]]></code></example>
530
531     <p>Juliet responds with a list of Pubsub nodes where she has published files or which she believes would be interesting to Romeo. If no such locations exist, Juliet SHOULD respond with an empty list.</p>
532
533     <example caption='File Repository listing'><code><![CDATA[<iq type='get'
534     from='romeo@montague.net/orchard'
535     to='juliet@capulet.com'
536     id='repolist'>
537   <fileshare xmlns='http://jabber.org/protocol/si/profile/fileshare'>
538     <list>
539       <repo address='pubsub.shakespeare.lit'
540             node='juliets_sonnets' description='My Sonnets'/>
541     </list>
542   </fileshare>
543 </iq>
544         ]]></code></example>    
545
546     <p>After browsing Juliet's repository, Romeo has chosen to download her sonnet. The most recent revision of this file contains a listing of available mirrors, and one of them is an SI stream. Romeo sends an SI request to that mirror:</p>
547     
548     <example caption='Request that a file be sent'><code><![CDATA[<iq type='get'
549     id='sipub-request-0'
550     from='romeo@montague.net/orchard'
551     to='fileserver@capulet.com'>
552   <start xmlns='http://jabber.org/protocol/sipub'
553          id='publish-sonnet2.txt'/>
554 </iq>
555         ]]></code></example>
556
557     <p>The rest of the negotiation and transfer occurs as described in XEP-0137.</p>
558   </section2>
559 </section1>
560 <section1 topic='Implementation Notes' anchor='impl'>
561   <p>Since Pubsub is used for the File Listing, the access models described in XEP-0060 MUST be followed. Users MUST NOT be able to view or control information in the File Listing to which they do not have access.</p>
562
563   <p>Node IDs MAY take the form of "path/to/file.ext", rather than the randomized strings provided in the above use cases. For example, Juliet's sonnet MAY use a Node ID of "juliets_sonnets/sonnet.txt" rather than "a6190c5d38e22452041d1c5798eff3f5", as long as this ID is unique to the PubSub server. Randomized strings were used in order to explicitly illustrate that Node IDs SHOULD NOT be depended upon for storing information about files.</p>
564
565   <p>The "sipub" mirror type MUST be implemented by the client, while the other mirror types are entirely OPTIONAL, and are provided only as examples for custom client implementations which desire use of common protocols which are currently incompatible with SI requests.</p>
566   
567   <p>If user access to files is restricted, the mirror servers and the File Listing server MUST be able to synchronize these restrictions between them. See <link url='#security'>Security Considerations</link>.</p>
568 </section1>
569 <section1 topic='Security Considerations' anchor='security'>
570   <p>When restricted files are being distributed, mirrors need to know which users have permission to access which files. If mirrors are not provided this information by the File Listing (or some other entity), unauthorized users could request files from mirrors directly, thus bypassing any such restrictions.</p>
571 </section1>
572 <section1 topic='IANA Considerations' anchor='iana'>
573   <p>No interaction with the Internet Assigned Numbers Authority (IANA) is required as a result of this XEP.</p>
574 </section1>
575 <section1 topic='Jabber Registrar Considerations' anchor='registrar'>
576   <p>TODO</p>
577 </section1>
578 <section1 topic='XML Schema' anchor='schema'>
579   <p>TODO</p>
580 </section1>
581 </xep>