mirror of
https://github.com/moparisthebest/xeps
synced 2024-12-21 23:28:51 -05:00
0.6
This commit is contained in:
stpeter
parent
911b25a38d
commit
a9503ce9ac
153
xep-0261.xml
153
xep-0261.xml
@ -22,6 +22,12 @@
|
||||
<shortname>jingle-ibb</shortname>
|
||||
<discuss>jingle</discuss>
|
||||
&stpeter;
|
||||
<revision>
|
||||
<version>0.6</version>
|
||||
<date>2011-03-07</date>
|
||||
<initials>psa</initials>
|
||||
<remark><p>Clarified error flows and handling of multiple IBB sessions within the bytestream.</p></remark>
|
||||
</revision>
|
||||
<revision>
|
||||
<version>0.5</version>
|
||||
<date>2010-04-14</date>
|
||||
@ -67,13 +73,15 @@
|
||||
</header>
|
||||
|
||||
<section1 topic='Introduction' anchor='intro'>
|
||||
<p>&xep0166; defines a framework for negotiating and managing data sessions over XMPP. In order to provide a flexible framework, the base Jingle specification defines neither data transport methods nor application formats, leaving that up to separate specifications. The current document defines a transport method for establishing and managing data exchanges between XMPP entities using the existing In-Band Bytestreams (IBB) protocol specified in &xep0047;. This "jingle-ibb" method results in a streaming transport method suitable for use in Jingle application types where packet loss cannot be tolerated (e.g., file transfer); however, because the "jingle-ibb" transport method sends data over the XMPP channel itself (albeit not the Jingle signalling channel), it is intended as a transport of last resort when other streaming transports cannot be negotiated.</p>
|
||||
<p>The approach taken in this specification is to use the existing IBB mechanisms described in XEP-0047 for transporting the data, and to define Jingle-specific methods only to start and end the in-band bytestream.</p>
|
||||
<p>&xep0166; defines a framework for negotiating and managing data sessions over XMPP. In order to provide a flexible framework, the base Jingle specification defines neither data transport methods nor application formats, leaving that up to separate specifications. The current document defines a transport method for establishing and managing data exchanges between XMPP entities using the existing In-Band Bytestreams (IBB) protocol specified in &xep0047;. This "jingle-ibb" method results in a streaming transport method suitable for use in Jingle application types where packet loss cannot be tolerated (e.g., file transfer); however, because the "jingle-ibb" transport method sends data over the XMPP channel itself (albeit not the Jingle signalling channel), it is intended as a transport of last resort when other streaming transports (e.g., &xep0260;) cannot be negotiated.</p>
|
||||
<p>The approach taken in this specification is to use the existing IBB mechanisms described in <cite>XEP-0047</cite> for transporting the data, and to define Jingle-specific methods only to start and end the in-band bytestream.</p>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Protocol' anchor='protocol'>
|
||||
<para>The basic flow is as follows.</para>
|
||||
<code><![CDATA[
|
||||
|
||||
<section2 topic='Flow' anchor='protocol-flow'>
|
||||
<p>The basic flow is as follows.</p>
|
||||
<code><![CDATA[
|
||||
Initiator Responder
|
||||
| |
|
||||
| session-initiate |
|
||||
@ -96,10 +104,13 @@ Initiator Responder
|
||||
| ack |
|
||||
|--------------------------->|
|
||||
| |
|
||||
]]></code>
|
||||
<p>This flow is illustrated in the following examples (to prevent confusion these use a "stub" description instead of a real application type).</p>
|
||||
<p>First the initiator sends a Jingle session-initiate request.</p>
|
||||
<example caption="Initiator sends session-initiate (stub)"><![CDATA[
|
||||
]]></code>
|
||||
<p>This flow is illustrated in the following sections (to prevent confusion these use a "stub" description instead of a real application type).</p>
|
||||
</section2>
|
||||
|
||||
<section2 topic='Establishing a Bytestream' anchor='protocol-start'>
|
||||
<p>First the initiator sends a Jingle session-initiate request.</p>
|
||||
<example caption="Initiator sends session-initiate (stub)"><![CDATA[
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='xn28s7gk'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
@ -116,16 +127,17 @@ Initiator Responder
|
||||
</content>
|
||||
</jingle>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The responder immediately acknowledges receipt (but does not yet accept the session).</p>
|
||||
<example caption="Responder acknowledges session-initiate"><![CDATA[
|
||||
]]></example>
|
||||
<p>Note: The default value of the 'stanza' attribute is "iq", signifying use of &IQ; stanzas for data exchange; a value of "message" signifies that &MESSAGE; stanzas are to be used for data exchange. See <cite>XEP-0047</cite> for further discussion regarding use of these stanza types for data exchange.</p>
|
||||
<p>The responder immediately acknowledges receipt (but does not yet accept the session).</p>
|
||||
<example caption="Responder acknowledges session-initiate"><![CDATA[
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='xn28s7gk'
|
||||
to='romeo@montague.lit/orchard'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>If the offer is acceptable, the responder returns a Jingle session-accept. If the responder wishes to use a smaller block-size, the responder can specify that in the session-accept by returning a different value for the 'block-size' attribute.</p>
|
||||
<example caption="Responder definitively accepts the session"><![CDATA[
|
||||
]]></example>
|
||||
<p>If the offer is acceptable, the responder returns a Jingle session-accept. If the responder wishes to use a smaller block-size, the responder can specify that in the session-accept by returning a different value for the 'block-size' attribute.</p>
|
||||
<example caption="Responder definitively accepts the session"><![CDATA[
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='bsa91h56'
|
||||
to='romeo@montague.lit/orchard'
|
||||
@ -143,35 +155,39 @@ Initiator Responder
|
||||
</content>
|
||||
</jingle>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The initiator then acknowledges the session-accept.</p>
|
||||
<example caption="Initiator acknowledges session-accept"><![CDATA[
|
||||
]]></example>
|
||||
<p>The initiator then acknowledges the session-accept.</p>
|
||||
<example caption="Initiator acknowledges session-accept"><![CDATA[
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='bsa91h56'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>In essence, the foregoing Jingle negotiation replaces the <open/> element from <cite>XEP-0047</cite>. However, to provide consistent layering of Jingle on top of IBB (thus enabling separation of existing IBB code from new Jingle code), the initiator now MUST also send the <open/> element, with the same 'block-size' and 'sid' values as for the Jingle <transport/> element. This adds a roundtrip to the negotiation and could be considered a "no-op", but the extra roundtrip is inconsequential given that the parties are exchanging base64-encoded data in-band.</p>
|
||||
<example caption='Initiator sends IBB <open/>'><![CDATA[
|
||||
]]></example>
|
||||
<p>In essence, the foregoing Jingle negotiation replaces the <open/> element from <cite>XEP-0047</cite>. However, to provide consistent layering of Jingle on top of IBB (thus enabling separation of existing IBB code from new Jingle code), the initiator now MUST also send the <open/> element, with the same 'block-size' and 'sid' values as for the Jingle <transport/> element it negotiated with the recipient (i.e., if the recipient sent a modified <transport/> element element containing a different block size, the initiator MUST use the negotiated values). This adds a roundtrip to the negotiation and could be considered a "no-op", but the extra roundtrip is inconsequential given that the parties will be exchanging base64-encoded data in-band.</p>
|
||||
<example caption='Initiator sends IBB <open/>'><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
id='jn3h8g65'
|
||||
to='juliet@capulet.com/balcony'
|
||||
type='set'>
|
||||
<open xmlns='http://jabber.org/protocol/ibb'
|
||||
block-size='4096'
|
||||
block-size='2048'
|
||||
sid='ch3d9s71'
|
||||
stanza='iq'/>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The responder returns an IQ-result to the initiator.</p>
|
||||
<p>If no error occurs, the responder returns an IQ-result to the initiator.</p>
|
||||
<example caption='Responder accepts IBB <open/>'><![CDATA[
|
||||
<iq from='juliet@capulet.com/balcony'
|
||||
id='jn3h8g65'
|
||||
to='romeo@montague.net/orchard'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>Now the initiator can begin sending IBB packets using an IQ-set for each chunk as described in XEP-0047, where the responder will acknowledge each IQ-set in accordance with &rfc3920;.</p>
|
||||
<example caption='An IBB packet'><![CDATA[
|
||||
<p>However, one of the errors described in <cite>XEP-0047</cite> might occur; in particular, if the value of the IBB 'block-size' attribute sent by the initiator in the <open/> element does not match the value of the 'block-size' attribute communicated by the responder in the Jingle session-accept message then the responder SHOULD return a &constraint; error as described in <cite>XEP-0047</cite>.</p>
|
||||
</section2>
|
||||
|
||||
<section2 topic='Exchanging Data' anchor='protocol-data'>
|
||||
<p>Now the initiator can begin sending IBB packets using an IQ-set for each chunk as described in <cite>XEP-0047</cite>, where the responder will acknowledge each IQ-set in accordance with &rfc3920;.</p>
|
||||
<example caption='An IBB packet'><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
id='ls72b58f'
|
||||
to='juliet@capulet.com/balcony'
|
||||
@ -184,15 +200,56 @@ Initiator Responder
|
||||
kuNEHFQiLuCY6Iv0myq6iX6tjuHehZlFSh80b5BVV9tNLwNR5Eqz1klxMhoghJOA
|
||||
</data>
|
||||
</iq>
|
||||
]]></example>
|
||||
<example caption='An IBB ack'><![CDATA[
|
||||
]]></example>
|
||||
<example caption='An IBB ack'><![CDATA[
|
||||
<iq from='juliet@capulet.com/balcony'
|
||||
id='ls72b58f'
|
||||
to='romeo@montague.net/orchard'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
<p>Once the parties have finished using the bytestream (e.g., because a complete file has been sent), either party can send a Jingle session-terminate action.</p>
|
||||
<example caption="Initiator terminates the session"><![CDATA[
|
||||
]]></example>
|
||||
</section2>
|
||||
|
||||
<section2 topic='Managing Multiple IBB Sessions' anchor='protocol-multi'>
|
||||
<p>As IBB is defined in <cite>XEP-0047</cite>, there is one session per bytestream (which can be used in both directions). However, because Jingle-IBB provides a management layer on top of IBB, it can be used to run multiple IBB sessions over a single bytestream. This can be done by sending a transport-info message that authorizes an additional session, as shown in the following example (although this example shows the initiator adding a session, the responder could just as well do so).</p>
|
||||
<example caption="Initiator adds a session to the bytestream"><![CDATA[
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='znb376s4'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='set'>
|
||||
<jingle xmlns='urn:xmpp:jingle:1'>
|
||||
action='transport-info'
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content creator='initiator' name='stub'>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:ibb:1'
|
||||
block-size='2048'
|
||||
sid='bt8a71h6'/>
|
||||
</content>
|
||||
</jingle>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>Here the Jingle Session ID is the same ("a73sjjvkla37jfea") but the new IBB Session ID ("bt8a71h6") is different from the old IBB Session ID that is already in use ("ch3d9s71").</p>
|
||||
<p>If a party wishes to close one session within a bytestream, it sends an IBB <close/> element as defined in <cite>XEP-0047</cite> specifying the appropriate IBB SessionID.</p>
|
||||
<example caption='Closing the bytestream'><![CDATA[
|
||||
<iq from='romeo@montague.net/orchard'
|
||||
id='us71g45j'
|
||||
to='juliet@capulet.com/balcony'
|
||||
type='set'>
|
||||
<close xmlns='http://jabber.org/protocol/ibb' sid='bt8a71h6'/>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The receiving party then acknowledges that the IBB session has been closed by returning an IQ-result.</p>
|
||||
<example caption='Success response'><![CDATA[
|
||||
<iq from='juliet@capulet.com/balcony'
|
||||
id='us71g45j'
|
||||
to='romeo@montague.net/orchard'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
</section2>
|
||||
|
||||
<section2 topic='Closing the Bytestream' anchor='protocol-close'>
|
||||
<p>If a party wishes to close the bytestream itself (e.g., because the parties have finished using all sessions associated with the bytestream), it sends a Jingle session-terminate action as defined in <cite>XEP-0166</cite>.</p>
|
||||
<example caption="Initiator terminates the session"><![CDATA[
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='hz81vf48'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
@ -204,45 +261,19 @@ Initiator Responder
|
||||
<reason><success/></reason>
|
||||
</jingle>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The other party then acknowledges the session-terminate and the Jingle session is finished.</p>
|
||||
<example caption="Responder acknowledges session-terminate"><![CDATA[
|
||||
]]></example>
|
||||
<p>The other party then acknowledges the session-terminate and the Jingle session is finished.</p>
|
||||
<example caption="Responder acknowledges session-terminate"><![CDATA[
|
||||
<iq from='juliet@capulet.lit/balcony'
|
||||
id='hz81vf48'
|
||||
to='romeo@montague.lit/orchard'
|
||||
type='result'/>
|
||||
]]></example>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Adding a Session to a Bytestream' anchor='session'>
|
||||
<p>As IBB is defined in XEP-0047, there is one session per bytestream (which can be used in both directions). To extend this idea, it might be useful to run multiple sessions over a single bytestream. This can be done by sending a transport-info message that authorizes an additional session, as shown in the following example.</p>
|
||||
<example caption="Initiator adds a session"><![CDATA[
|
||||
<iq from='romeo@montague.lit/orchard'
|
||||
id='znb376s4'
|
||||
to='juliet@capulet.lit/balcony'
|
||||
type='set'>
|
||||
<jingle xmlns='urn:xmpp:jingle:1'>
|
||||
action='transport-info'
|
||||
initiator='romeo@montague.lit/orchard'
|
||||
sid='a73sjjvkla37jfea'>
|
||||
<content creator='initiator' name='stub'>
|
||||
<transport xmlns='urn:xmpp:jingle:transports:ibb:1'
|
||||
block-size='4096'
|
||||
sid='bt8a71h6'/>
|
||||
</content>
|
||||
</jingle>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>Here the Jingle Session ID is the same ("a73sjjvkla37jfea") but the new IBB Session ID ("bt8a71h6") is different from the old IBB Session ID that is already in use ("ch3d9s71").</p>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Closing a Session or Bytestream' anchor='close'>
|
||||
<p>To close one session within a bytestream, the initiator sends an IBB <close/> element as specified in <cite>XEP-0047</cite>.</p>
|
||||
<p>To close the bytestream itself, the initiator terminates the Jingle session as specified in <cite>XEP-0166</cite>.</p>
|
||||
]]></example>
|
||||
</section2>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Processing Rules and Usage Guidelines' anchor='rules'>
|
||||
<p>The same processing rules and usage guidelines defined in XEP-0047 apply to the Jingle IBB Transport Method.</p>
|
||||
<p>The same processing rules and usage guidelines defined in <cite>XEP-0047</cite> apply to the Jingle IBB Transport Method.</p>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Determining Support' anchor='support'>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user