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-0137.xml 15KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326
  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>Publishing Stream Initiation Requests</title>
  10. <abstract>This specification defines an XMPP protocol extension that enables an XMPP entity to advertise the fact that it is willing accept a particular Stream Initiation request. The protocol is used mainly to inform other entities that a particular file is available for transfer via the File Transfer protocol defined in XEP-0096.</abstract>
  11. &LEGALNOTICE;
  12. <number>0137</number>
  13. <status>Deprecated</status>
  14. <type>Standards Track</type>
  15. <sig>Standards</sig>
  16. <dependencies>
  17. <spec>XMPP Core</spec>
  18. <spec>XEP-0030</spec>
  19. <spec>XEP-0095</spec>
  20. </dependencies>
  21. <supersedes/>
  22. <supersededby/>
  23. <shortname>sipub</shortname>
  24. <schemaloc>
  25. <url>http://www.xmpp.org/schemas/sipub.xsd</url>
  26. </schemaloc>
  27. &linuxwolf;
  28. &temas;
  29. <revision>
  30. <version>1.1</version>
  31. <date>2018-02-28</date>
  32. <initials>XEP Editor (ssw)</initials>
  33. <remark><p>Deprecated per a vote of the XMPP Council.</p></remark>
  34. </revision>
  35. <revision>
  36. <version>1.0</version>
  37. <date>2005-08-26</date>
  38. <initials>psa</initials>
  39. <remark>Per a vote of the Jabber Council, advanced status to Draft.</remark>
  40. </revision>
  41. <revision>
  42. <version>0.3</version>
  43. <date>2005-07-21</date>
  44. <initials>psa</initials>
  45. <remark>Corrected several errors in the text and examples.</remark>
  46. </revision>
  47. <revision>
  48. <version>0.2</version>
  49. <date>2004-11-03</date>
  50. <initials>psa</initials>
  51. <remark>Editorial review: clarified text throughout and corrected several errors in the examples.</remark>
  52. </revision>
  53. <revision>
  54. <version>0.1</version>
  55. <date>2004-06-16</date>
  56. <initials>lw/tjm</initials>
  57. <remark>Initial version.</remark>
  58. </revision>
  59. </header>
  60. <section1 topic='Introduction' anchor='intro'>
  61. <p>&xep0095; defines a protocol to initiate a data stream between two Jabber/XMPP entities (e.g., for the purpose of &xep0096;). However, the sender is still responsible for informing potential receivers about the existence of a given stream. This document provides an automated way for a sender to announce the availability of a stream without initiating the data transfer. The purpose is to provide a "pull" protocol that enables a receiver to then request initiation of the stream from the sender.</p>
  62. </section1>
  63. <section1 topic='Requirements' anchor='requirements'>
  64. <p>This proposal addresses the following requirements:</p>
  65. <ul>
  66. <li>Allow a potential receiver (rather than the sender) to initiate a data stream.</li>
  67. <li>Integrate Stream Initiation (SI) with &xep0060;.</li>
  68. <li>Integrate Stream Initiation with &xep0004;.</li>
  69. </ul>
  70. </section1>
  71. <section1 topic='Use Cases' anchor='usecase'>
  72. <section2 topic='Publishing an SI Request' anchor='usecase.publish'>
  73. <p>A stream owner uses the &lt;sipub/&gt; element to announce that it can perform a specific SI request. This element can be sent to a publish-subscribe (XEP-0060) node, or sent directly to potential recipients within a &MESSAGE; stanza.</p>
  74. <p>The format of the &lt;sipub/&gt; element is as follows:</p>
  75. <example caption='Sample &lt;sipub/&gt;'><![CDATA[
  76. <sipub xmlns='http://jabber.org/protocol/sipub'
  77. from='sender-jid'
  78. id='publish-0123'
  79. profile='si-profile'
  80. mime-type='mime/type'>
  81. <profile xmlns='si-profile'></profile>
  82. </sipub>
  83. ]]></example>
  84. <p>This format is nearly identical to that for the stream initiation &lt;si/&gt; element (see <cite>XEP-0095</cite>). The major difference is the lack of the feature negotiation for the stream methods, and the addition of a 'from' attribute.</p>
  85. <p>The 'from' attribute SHOULD be present, and MUST be present if the stanza containing the &lt;sipub/&gt; is not from the stream owner (e.g., if the stream is advertised at a publish-subscribe node). If present, this attribute MUST be the valid JID for the stream owner.</p>
  86. <p>The 'id' attribute is an opaque identifier. This attribute MUST be present, and MUST be a valid non-empty string. It uniquely identifies the published request at the potential sender.</p>
  87. <p>As with stream initiation, the 'profile' attribute MUST be present, and MUST be the namespace URI governing the profile information. It identifies the format for the SI profile.</p>
  88. <p>As with stream initiation, the 'mime-type' attribute SHOULD be present, and MUST be an IANA-registered content type. <note>The IANA registry of content types is located at &lt;<link url='http://www.iana.org/assignments/media-types/'>http://www.iana.org/assignments/media-types/</link>&gt;.</note> It provides the receiver with additional information about what the data stream will be.</p>
  89. <p>The &lt;sipub/&gt; element MUST contain an element qualified by the namespace specified by the 'profile' attribute (e.g., &lt;file xmlns='http://jabber.org/protocol/si/profile/file-transfer'/&gt; for file transfer). This is the additional information about the data stream.</p>
  90. <p>The &lt;sipub/&gt; information is typically provided via pubsub:</p>
  91. <example caption='Sender advertises stream via publish-subscribe'><![CDATA[
  92. <iq from='bard@shakespeare.lit/globe'
  93. to='pubsub.shakespeare.lit'
  94. id='ps1'>
  95. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  96. <publish node='characters'>
  97. <sipub xmlns='http://jabber.org/protocol/sipub'
  98. from='bard@shakespeare.lit'
  99. id='publish-0123'
  100. mime-type='application/pdf'
  101. profile='http://jabber.org/protocol/si/profile/file-transfer'>
  102. <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
  103. name='NDA.pdf'
  104. size='138819'
  105. date='2004-01-28T10:07Z'>
  106. <desc>All Shakespearean characters must sign and return this NDA ASAP</desc>
  107. </file>
  108. </sipub>
  109. </publish>
  110. </pubsub>
  111. </iq>
  112. ]]></example>
  113. <example caption='Pubsub service pushes announcement to all subscribers'><![CDATA[
  114. <message from='pubsub.shakespeare.lit' to='juliet@capulet.com/balcony'>
  115. <event xmlns='http://jabber.org/protocol/pubsub#event'>
  116. <items node='characters'>
  117. <item id='current'>
  118. <sipub xmlns='http://jabber.org/protocol/sipub'
  119. from='bard@shakespeare.lit'
  120. id='publish-0123'
  121. mime-type='application/pdf'
  122. profile='http://jabber.org/protocol/si/profile/file-transfer'>
  123. <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
  124. name='NDA.pdf'
  125. size='138819'
  126. date='2004-01-28T10:07Z'>
  127. <desc>All Shakespearean characters must sign and return this NDA ASAP</desc>
  128. </file>
  129. </sipub>
  130. </item>
  131. </items>
  132. </event>
  133. </message>
  134. ]]></example>
  135. <p>The &lt;sipub/&gt; element MAY also be included directly within a &MESSAGE; stanza sent to another entity (or multiple entities, e.g., in &xep0045; or via &xep0033;). This can be especially useful for informing an offline entity about an available stream.</p>
  136. <example caption='Advertising a stream in a message stanza'><![CDATA[
  137. <message from='romeo@montague.net/pda' to='juliet@capulet.com'>
  138. <sipub xmlns='http://jabber.org/protocol/sipub'
  139. id='publish-0123'
  140. mime-type='application/pdf'
  141. profile='http://jabber.org/protocol/si/profile/file-transfer'>
  142. <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
  143. name='NDA.pdf'
  144. size='138819'
  145. date='2004-01-28T10:07Z'>
  146. <desc>All Shakespearean characters must sign and return this NDA ASAP</desc>
  147. </file>
  148. </sipub>
  149. </message>
  150. ]]></example>
  151. </section2>
  152. <section2 topic='Integration with Data Forms' anchor='usecase.xdata'>
  153. <p>One of the goals of sipub is to integrate <cite>Stream Initiation</cite> with <cite>Data Forms</cite> to provide a "file upload" capability. This is accomplished via the datatypes specified in &xep0122;. Each datatype is specific to the profile desired.</p>
  154. <p>For example the datatype "sipub:file-transfer" is used to identify the file upload field(s) corresponding to <cite>XEP-0096</cite>:</p>
  155. <example caption='"Upload File" Data Forms Field'><![CDATA[
  156. <field var='file' type='text-single' label='File to Upload'>
  157. <validate xmlns='http://jabber.org/protocol/xdata-validate'
  158. datatype='sipub:file-transfer'/>
  159. </field>
  160. ]]></example>
  161. <p>When submitting such a form, a field's value(s) MUST be the &lt;sipub/&gt; identifier(s). Also, the submitter MUST provide an &lt;sipub/&gt; element within the data form for each file to be uploaded:</p>
  162. <example caption='Submitting an "Upload File" form'><![CDATA[
  163. <x xmlns='jabber:x:data' type='submit'>
  164. <field var='file'>
  165. <value>publish-0123</value>
  166. </field>
  167. <sipub xmlns='http://jabber.org/protocol/sipub'
  168. id='publish-0123'
  169. mime-type='text/html'
  170. profile='http://jabber.org/protocol/si/profile/file-transfer'>
  171. <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
  172. name='missive.html'
  173. size='1024'
  174. date='2005-07-21T11:21Z'/>
  175. </sipub>
  176. </x>
  177. ]]></example>
  178. <p>The form processor will use this to retrieve the file(s) to be uploaded.</p>
  179. </section2>
  180. <section2 topic='Triggering the Stream Initiation Request' anchor='usecase.trigger'>
  181. <p>A potential receiver starts the stream initiation session by sending an IQ-get to the sender, using the &lt;start xmlns='http://jabber.org/protocol/sipub'/&gt; element. This element contains the 'id' attribute to specify which published stream to retrieve:</p>
  182. <example caption='Receiver requests start of stream'><![CDATA[
  183. <iq type='get'
  184. id='sipub-request-0'
  185. from='juliet@capulet.com/balcony'
  186. to='romeo@montague.net/pda'>
  187. <start xmlns='http://jabber.org/protocol/sipub'
  188. id='publish-0123'/>
  189. </iq>
  190. ]]></example>
  191. <p>If the sender accepts the request, it responds with an IQ-result containing a &lt;starting/&gt; element. This element indicates the stream initiation identifier to be used:</p>
  192. <example caption='Sender accepts request to start stream'><![CDATA[
  193. <iq type='result'
  194. id='sipub-request-0'
  195. from='romeo@montague.net/pda'
  196. to='juliet@capulet.com/balcony'>
  197. <starting xmlns='http://jabber.org/protocol/sipub'
  198. sid='session-87651234'/>
  199. </iq>
  200. ]]></example>
  201. <p>Then the sender begins the stream initiation negotiation:</p>
  202. <example caption='Sender starts negotiation'><![CDATA[
  203. <iq type='set'
  204. id='sipub-set-1'
  205. from='romeo@montague.net/pda'
  206. to='juliet@capulet.com/balcony'>
  207. <si xmlns='http://jabber.org/protocol/si'
  208. id='session-87651234'
  209. mime-type='text/html'
  210. profile='http://jabber.org/protocol/si/profile/file-transfer'>
  211. <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
  212. name='missive.html'
  213. size='1024'
  214. date='2005-07-21T11:21Z'>
  215. <desc>A love letter</desc>
  216. </file>
  217. </si>
  218. </iq>
  219. ]]></example>
  220. <p>If the requested identifier is not valid, the sender SHOULD respond with a &notacceptable; error:</p>
  221. <example caption='Sender denies because of invalid id'><![CDATA[
  222. <iq type='error'
  223. id='sipub-set-1'
  224. from='romeo@montague.net/pda'
  225. to='juliet@capulet.com/balcony'>
  226. <start xmlns='http://jabber.org/protocol/sipub'>publish-0123</start>
  227. <error code='405' type='modify'>
  228. <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  229. </error>
  230. </iq>
  231. ]]></example>
  232. <p>If the receiver does not have permission to request the data stream, the sender SHOULD respond with a &forbidden; error:</p>
  233. <example caption='Sender denies because receiver is forbidden'><![CDATA[
  234. <iq type='error'
  235. id='sipub-set-1'
  236. from='romeo@montague.net/pda'
  237. to='juliet@capulet.com/balcony'>
  238. <start xmlns='http://jabber.org/protocol/sipub'>publish-0123</start>
  239. <error code='403' type='auth'>
  240. <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  241. </error>
  242. </iq>
  243. ]]></example>
  244. </section2>
  245. </section1>
  246. <section1 topic='Implementation Notes' anchor='impl-notes'>
  247. <section2 topic='Publish ID versus SI ID'>
  248. <p>When publishing a stream via the &lt;sipub/&gt; element, the identifier SHOULD NOT be used as-is for the &lt;si/&gt; element, since a single publication will likely result in multiple &lt;si/&gt; requests, possibly from the same receiver.</p>
  249. </section2>
  250. </section1>
  251. <section1 topic='Security Considerations' anchor='security'>
  252. <p>This document introduces no security concerns beyond those specified in <cite>XEP-0060</cite> and the relevant Stream Initiation profile in use.</p>
  253. </section1>
  254. <section1 topic='IANA Considerations' anchor='iana'>
  255. <p>This document requires no interaction with &IANA;.</p>
  256. </section1>
  257. <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  258. <section2 topic='Protocol Namespaces' anchor='registrar.namespaces'>
  259. <p>The &REGISTRAR; includes 'http://jabber.org/protocol/sipub' in its registry of protocol namespaces.</p>
  260. </section2>
  261. <section2 topic='Data Form Validation Datatypes' anchor='registrar.xdata-validate'>
  262. <p>The XMPP Registrar includes 'sipub:' in its registry of Data Forms Validation Datatype Prefixes.</p>
  263. <p>Normally, each SI profile that wishes to be considered for use with Data Forms MUST register its own datatype qualified by the "sipub:" prefix. However, this document provides an initial seed, based on the currently accepted SI profiles. The following datatypes shall be registered for use with Data Forms Validation:</p>
  264. <code caption='Data Forms Validation Datatypes Registry Submission'><![CDATA[
  265. <datatype>
  266. <name>sipub:file-transfer</name>
  267. <desc>Datatype for publishing an SI using the File Transfer Profile</desc>
  268. <doc>XEP-0096</doc>
  269. </datatype>
  270. ]]></code>
  271. </section2>
  272. </section1>
  273. <section1 topic='XML Schema' anchor='schema'>
  274. <code><![CDATA[
  275. <?xml version='1.0' encoding='UTF-8'?>
  276. <xs:schema
  277. xmlns:xs='http://www.w3.org/2001/XMLSchema'
  278. targetNamespace='http://jabber.org/protocol/sipub'
  279. xmlns='http://jabber.org/protocol/sipub'
  280. elementFormDefault='qualified'>
  281. <xs:annotation>
  282. <xs:documentation>
  283. The protocol documented by this schema is defined in
  284. XEP-0137: http://www.xmpp.org/extensions/xep-0137.html
  285. </xs:documentation>
  286. </xs:annotation>
  287. <xs:element name='sipub'>
  288. <xs:annotation>
  289. <xs:documentation>This is the root content element for advertising a stream.</xs:documentation>
  290. </xs:annotation>
  291. <xs:complexType>
  292. <xs:sequence>
  293. <xs:any namespace='##other' minOccurs='1' maxOccurs='1'/>
  294. </xs:sequence>
  295. <xs:attribute name='id' type='xs:string' use='required'/>
  296. <xs:attribute name='from' type='xs:string' use='optional'/>
  297. <xs:attribute name='mime-type' type='xs:string' use='optional'/>
  298. <xs:attribute name='profile' type='xs:string' use='optional'/>
  299. </xs:complexType>
  300. </xs:element>
  301. <xs:element name='start'>
  302. <xs:annotation>
  303. <xs:documentation>This is the element for requesting retrieval of a stream.</xs:documentation>
  304. </xs:annotation>
  305. <xs:complexType>
  306. <xs:attribute name='id' type='xs:string' use='required'/>
  307. </xs:complexType>
  308. </xs:element>
  309. <xs:element name='starting'>
  310. <xs:annotation>
  311. <xs:documentation>This is the element for specifying the stream to be retrieved.</xs:documentation>
  312. </xs:annotation>
  313. <xs:complexType>
  314. <xs:attribute name='sid' type='xs:string' use='required'/>
  315. </xs:complexType>
  316. </xs:element>
  317. </xs:schema>
  318. ]]></code>
  319. </section1>
  320. </xep>