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-0087.xml 14KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428
  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>Stream Initiation</title>
  10. <abstract>A common method to initiate a stream with meta information</abstract>
  11. &LEGALNOTICE;
  12. <number>0087</number>
  13. <status>Retracted</status>
  14. <type>Standards Track</type>
  15. <sig>Standards</sig>
  16. <dependencies><spec>XEP-0030</spec></dependencies>
  17. <supersedes/>
  18. <supersededby><spec>XEP-0095</spec></supersededby>
  19. <shortname>si</shortname>
  20. <author>
  21. <firstname>Thomas</firstname>
  22. <surname>Muldowney</surname>
  23. <email>temas@jabber.org</email>
  24. <jid>temas@jabber.org</jid>
  25. </author>
  26. <revision>
  27. <version>0.1</version>
  28. <date>2003-05-22</date>
  29. <initials>tjm</initials>
  30. <remark>Initial version.</remark>
  31. </revision>
  32. </header>
  33. <section1 topic='Introduction'>
  34. <p>
  35. As more people begin to make use of streams in Jabber, there becomes a need
  36. for more descriptive negotiation of which stream to use. This document provides
  37. a method to negotiate a stream and provide some meta-information about the
  38. streams usage.
  39. </p>
  40. </section1>
  41. <section1 topic='Requirements'>
  42. <ul>
  43. <li>
  44. The defined protocol will allow for negotiation of a common stream.
  45. </li>
  46. <li>
  47. The defined protocol will allow for meta-information to be sent about the
  48. stream usage.
  49. </li>
  50. <li>
  51. The defined protocol will not be required for stream usage.
  52. </li>
  53. </ul>
  54. <section2 topic='Use Case'>
  55. <p>
  56. Sender wishes to interact with another user, using a method that requires
  57. streams.
  58. </p>
  59. <p>
  60. Primary Flow:
  61. </p>
  62. <ol>
  63. <li>
  64. Sender discovers if Receiver implements the desired profile. [E1]
  65. </li>
  66. <li>
  67. Sender offers a stream initiation. [E2]
  68. </li>
  69. <li>
  70. Receiver accepts stream initiation.
  71. </li>
  72. <li>
  73. Sender uses the negotiated stream and profile to send the information.
  74. </li>
  75. </ol>
  76. <p>
  77. Error Conditions:
  78. </p>
  79. <ol>
  80. <li>
  81. The Receiver does not support the desired profile, EUC
  82. </li>
  83. <li>
  84. Receiver rejects the stream initiation, EUC
  85. </li>
  86. </ol>
  87. </section2>
  88. </section1>
  89. <section1 topic='Basic Usage'>
  90. <p>
  91. Before a Stream Initiation is attempted the Sender should be sure that the
  92. Receiver supports both Stream Initiation and the specific profile that they
  93. wish to use. This is discovered by using &xep0030;:
  94. </p>
  95. <example caption='Requesting Disco Information From Receiver'>
  96. <![CDATA[
  97. <iq
  98. type='get'
  99. to='receiver@jabber.org/resource'
  100. from='sender@jabber.org/resource'
  101. id='info1'>
  102. <query xmlns='http://jabber.org/protocol/disco#info'/>
  103. </iq>
  104. ]]>
  105. </example>
  106. <p>
  107. The Receiver will advertise the "http://jabber.org/protocol/si" namespace as
  108. a feature to represent they implement this document. The specific profiles can
  109. be found by looking for
  110. "http://jabber.org/protocol/si/profile/profile-name". Shown in the result
  111. is a potential file transfer profile:
  112. </p>
  113. <example caption='Receiver Disco Information Result'>
  114. <![CDATA[
  115. <iq
  116. type='result'
  117. to='sender@jabber.org/resource'
  118. from='receiver@jabber.org/resource'
  119. id='info1'>
  120. <query xmlns='http://jabber.org/protocol/disco#info'>
  121. <feature var='http://jabber.org/protocol/si'/>
  122. <feature var='htpt://jabber.org/protocol/si/profile/filexfer'/>
  123. </query>
  124. </iq>
  125. ]]>
  126. </example>
  127. <p>
  128. Now that the Sender is sure that the Receiver support Stream Initiation they
  129. send the offer:
  130. </p>
  131. <example caption='Offer Stream Initiation'>
  132. <![CDATA[
  133. <iq type='set' id='offer1' to='receiver@jabber.org/resource'>
  134. <si
  135. xmlns='http://jabber.org/protocol/si'
  136. id='a0'
  137. mime-type='application/octet-stream'
  138. profile='http://jabber.org/protocol/si/profile/profile-name'>
  139. <header name='key'>value</header>
  140. <feature xmlns='http://jabber.org/protocol/feature-neg'>
  141. <x xmlns='jabber:x:data'>
  142. <field var='file-transfer-method' type='list-single'>
  143. <option><value>s5b</value></option>
  144. <option><value>jabber:iq:oob</value></option>
  145. <option><value>ibb</value></option>
  146. </field>
  147. </x>
  148. </feature>
  149. </si>
  150. </iq>
  151. ]]>
  152. </example>
  153. <!--
  154. <example caption='Offer Stream Initiation (Profile in NS)'>
  155. <![CDATA[
  156. <iq type='set' id='offer1' to='receiver@jabber.org/resource'>
  157. <si
  158. xmlns='http://jabber.org/protocol/si'
  159. id='a0'
  160. mime-type='application/octet-stream'>
  161. <profile xmlns='http://jabber.org/protocol/si/profile/profile-name'>
  162. <foo>
  163. <bar>baz</bar>
  164. </foo>
  165. </profile>
  166. <feature xmlns='http://jabber.org/protocol/feature-neg'>
  167. <x xmlns='jabber:x:data'>
  168. <field var='file-transfer-method' type='list-single'>
  169. <option><value>s5b</value></option>
  170. <option><value>jabber:iq:oob</value></option>
  171. <option><value>ibb</value></option>
  172. </field>
  173. </x>
  174. </feature>
  175. </si>
  176. </iq>
  177. ]]>
  178. </example>
  179. -->
  180. <!--
  181. <example caption='Offer Regular File Transfer (Alternate Stream Negotiation)'>
  182. <![CDATA[
  183. <si
  184. xmlns='http://jabber.org/protocol/si'
  185. id='a0'
  186. mime-type='application/octet-stream'
  187. profile='filexfer'>
  188. <header name='size'>37678</header>
  189. <header name='hash'>a9234abbff332</header>
  190. <header name='name'>filename.txt</header>
  191. <stream>s5b</stream>
  192. <stream>jabber:iq:oob</stream>
  193. <stream>ibb</stream>
  194. </si>
  195. ]]>
  196. </example>
  197. -->
  198. <p>
  199. At this point the Receiver can view the headers and other information to
  200. decide if they wish to accept the Stream Initiation. If they accept they
  201. MUST select one of the presented stream types to use. If none of the stream
  202. types are acceptable the Receiver MUST reply with an error:
  203. </p>
  204. <example caption='Accept Stream Initiation'>
  205. <![CDATA[
  206. <iq type='result' to='sender@jabber.org/resource' id='offer1'>
  207. <si
  208. xmlns='http://jabber.org/si'
  209. id='a0'>
  210. <feature xmlns='http://jabber.org/protocol/feature-neg'>
  211. <x xmlns='jabber:x:data' type='submit'>
  212. <field var='file-transfer-method'>
  213. <value>s5b</value>
  214. </field>
  215. </x>
  216. </feature>
  217. </si>
  218. </iq>
  219. ]]>
  220. </example>
  221. <example caption='Rejecting Stream Initiation'>
  222. <![CDATA[
  223. <iq type='error' to='sender@jabber.org/resource' id='offer1'>
  224. <error code='403'>Offer Declined</error>
  225. </iq>
  226. ]]>
  227. </example>
  228. <example caption='No Valid Streams'>
  229. <![CDATA[
  230. <iq type='error' to='sender@jabber.org/resource' id='offer1'>
  231. <error code='406'>No Valid Streams</error>
  232. </iq>
  233. ]]>
  234. </example>
  235. <p>
  236. If the Receiver has accepted the Stream Initiation the Sender may then used
  237. the semantics defined by the selected stream and start the usage.
  238. </p>
  239. <!--
  240. <example caption='Accept File Transfer (Alternate Stream Negotiation)'>
  241. <![CDATA[
  242. <si
  243. xmlns='http://jabber.org/protocol/si'
  244. id='a0'>
  245. <stream>s5b</stream>
  246. </si>
  247. ]]>
  248. </example>
  249. <example caption='Offer to Start a MP3 Stream'>
  250. <![CDATA[
  251. <si
  252. xmlns='http://jabber.org/protocol/si'
  253. id='s0'
  254. mime-type='audio/x-mp3'
  255. profile='streaming-audio'>
  256. <feature xmlns='http://jabber.org/protocol/feature-neg'>
  257. <x xmlns='jabber:x:data'>
  258. <field var='file-transfer-method' type='list-single'>
  259. <option><value>s5b</value></option>
  260. <option><value>ibb</value></option>
  261. </field>
  262. </x>
  263. </feature>
  264. </si>
  265. ]]>
  266. </example>
  267. <example caption='Offer to Start a MP3 Stream (Alternate Stream Negotiation)'>
  268. <![CDATA[
  269. <si
  270. xmlns='http://jabber.org/protocol/si'
  271. id='s0'
  272. mime-type='audio/x-mp3'
  273. profile='streaming-audio'>
  274. <stream>s5b</stream>
  275. <stream>ibb</stream>
  276. </si>
  277. ]]>
  278. </example>
  279. -->
  280. </section1>
  281. <section1 topic='Detailed Usage'>
  282. <section2 topic='Profiles'>
  283. <p>
  284. While Stream Initiation itself is helpful, it makes much more sense when
  285. what is being transported over the stream is known. Knowing this
  286. allows the Receiver to make a more educated choice about whether or not to
  287. accept the stream. This information is transported in Stream Initiation
  288. through a <em>profile</em>. A profile is a series of required and
  289. optional headers that describe the stream data or how the stream is to be
  290. used. Each Stream Initiation MUST have only one profile, so the stream
  291. usage is kept clear.
  292. </p>
  293. <p>
  294. Creating a profile is fairly simple. First, a name is chosen, the
  295. complete name is formatted like:</p>
  296. <code>
  297. http://jabber.org/protocol/si/profile/profile-name
  298. </code>
  299. <p>
  300. The complete name is what is presented in information discovery requests
  301. in order to show that the profile is supported. It is also used for the
  302. &lt;si&gt; profile attribute. Next, the information for the headers is
  303. decided upon. Each piece of information will be transported in a
  304. &lt;header&gt; tag. The name attribute is a descriptive key that can be
  305. looked up at the XMPP Registrar or XEP describing the profile. The
  306. actual data in the &lt;header&gt; is the fact related to the name
  307. attribute. It must also be stated whether the header is required or
  308. optional.
  309. </p>
  310. <p>
  311. This document does not define any profiles, nor does it place any restrictions
  312. on what type of information a profile should detail. This document also does
  313. not place restrictions on what may be placed in a &lt;header&gt;. Other
  314. XEPs will define profiles to be used with Stream Initiation.
  315. </p>
  316. </section2>
  317. <section2 topic='Stream Interaction'>
  318. <p>
  319. While Stream Initiation is not directly required for stream usage, it does
  320. provide many benefits. In order to fully appreciate these benefits,
  321. streams must link the Stream Initiation to the stream. The id
  322. attribute of the &lt;si&gt; node is intended to provide this link. It is
  323. out of scope of this document to define how streams will make use of this
  324. facility, but it does suggest some methods:</p>
  325. <ul>
  326. <li>
  327. Transport the Stream Initiation id with the stream negotitation as a
  328. namespaced attribute, such as:
  329. <code>
  330. <![CDATA[
  331. <stream id='0' xmlns:si='http://jabber.org/protocol/si' si:id='si0'>
  332. <start/>
  333. </stream>
  334. ]]>
  335. </code>
  336. </li>
  337. <li>
  338. Transport the Stream Initiation id in a namespaced tag, such as:
  339. <code>
  340. <![CDATA[
  341. <stream id='0'>
  342. <start/>
  343. <si xmlns='http://jabber.org/protocol/si' id='si0'/>
  344. </stream>
  345. ]]>
  346. </code>
  347. </li>
  348. </ul>
  349. </section2>
  350. <section2 topic='&lt;si&gt; Explanation'>
  351. <p>
  352. The attributes and data of &lt;si&gt; are fairly simple:</p>
  353. <ul>
  354. <li>
  355. <em>id</em> - An opaque identifier generated by the Sender.
  356. </li>
  357. <li>
  358. <em>mime-type</em> - The mime-type of the data being negotiated,
  359. selected by Sender.
  360. </li>
  361. <li>
  362. <em>profile</em> - The profile's fulle name, selected by Sender.
  363. </li>
  364. </ul>
  365. <p>The data of the node is a mixture of a feature negotiation for the stream
  366. and the profiles headers.
  367. </p>
  368. <p>
  369. When the Sender is offering a Stream Initiation all of the attributes must
  370. be present. The data MUST contain the required profile headers and the
  371. feature negotiation for the stream MUST be present with at least one
  372. option. The optional profile headers MAY also be in the node data.
  373. </p>
  374. <p>
  375. When the Receiver accepts a Stream Initiation the id attribute MUST be
  376. present, all other attributes MUST NOT be present. The selected stream
  377. MUST be in the feature negotiation for the stream. There MUST only be one
  378. selected stream.
  379. </p>
  380. </section2>
  381. <section2 topic='Error Codes'>
  382. <p>
  383. There are two error codes that are used. Following are the conditions,
  384. meanings and data:</p>
  385. <ul>
  386. <li>
  387. <em>Declining Transfer (403)</em>: During the Stream Initiation
  388. the Receiver may decline the transfer by sending the 403 error. The
  389. &lt;error/&gt; CDATA MAY contain a descriptive reason why, but is not
  390. necessary.
  391. </li>
  392. <li>
  393. <em>No Available Methods (406)</em>: When the Sender presents the
  394. available stream methods, and the Receiver can not use any of them,
  395. they send a 406 error. The &lt;error/&gt; CDATA is not important.
  396. </li>
  397. </ul>
  398. </section2>
  399. </section1>
  400. <section1 topic='Security Considerations'>
  401. <p>
  402. Data security concerns are left to the profiles to define. Wire security
  403. concerns are left to the stream definitions.
  404. </p>
  405. </section1>
  406. <section1 topic='IANA Considerations'>
  407. <p>
  408. This document uses the MIME types as recorded by IANA, but no other direct
  409. interaction is necessary.
  410. </p>
  411. </section1>
  412. <section1 topic='XMPP Registrar Considerations'>
  413. <p>
  414. The "http://jabber.org/protocol/si" namespace will be registered.
  415. The registrar will track header profiles for different stream initiation
  416. uses.
  417. </p>
  418. </section1>
  419. <section1 topic='Formal Definition'>
  420. <section2 topic='Schema'>
  421. <p>To follow.</p>
  422. </section2>
  423. <section2 topic='DTD'>
  424. <p>To follow.</p>
  425. </section2>
  426. </section1>
  427. </xep>