moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-21 23:28:51 -05:00
Code Issues Releases Wiki Activity

1.2rc1

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2752 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2009-02-18 23:37:27 +00:00
parent ddcb924cef
commit 9ea7f52358
1 changed files with 90 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

204
xep-0047.xml
View File

@ -24,11 +24,18 @@
</schemaloc>
<shortname>ibb</shortname>
&infiniti;
&stpeter;
<revision>
<version>1.2rc1</version>
<date>in progress, last updated 2009-02-18</date>
<initials>psa/jk</initials>
<remark>Encouraged use of IQ stanzas rather than message stanzas for sending data; clarified bidirectional nature of IBB.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2006-11-21</date>
<initials>jk</initials>
<remark>Allow IQ for delivery.</remark>
<remark>Allowed IQ for delivery.</remark>
</revision>
<revision>
<version>1.0</version>
@ -87,155 +94,124 @@
</header>
<section1 topic='Introduction'>
<p>This document describes In-Band Bytestreams (or IBB), a reliable bytestream protocol between two Jabber entities over a Jabber XML stream. The basic idea is that binary data is encoded as Base64 and transferred over the Jabber network.</p>
<p>This document describes In-Band Bytestreams (or IBB), a reliable bytestream protocol between two Jabber entities over a Jabber XML stream. The basic idea is that binary data is encoded as Base64 and transferred over the Jabber network.</p>
</section1>
<section1 topic='Uses'>
<p>IBB is a generic bytestream, and so its usage is left open-ended. It is likely to be useful for sending small payloads, such as files that would otherwise be too cumbersome to send as an instant message (such as a text file) or impossible to send (such as a small binary image file). It could also be useful for any kind of low-bandwidth activity, such as a chess game or a shell session. And, while it is mostly intended as a fallback in situations where a &xep0065; is unavailable, IBB could be more desirable for many of the simple bytestream use-cases that do not have high bandwidth requirements.</p>
<p>IBB is a generic bytestream, and so its usage is left open-ended. It is likely to be useful for sending small payloads, such as files that would otherwise be too cumbersome to send as an instant message (such as a text file) or impossible to send (such as a small binary image file). It could also be useful for any kind of low-bandwidth activity, such as a chess game or a shell session. And, while it is mostly intended as a fallback in situations where a &xep0065; is unavailable, IBB could be more desirable for many of the simple bytestream use-cases that do not have high bandwidth requirements.</p>
</section1>
<section1 topic='Implementation'>
<section2 topic='Creating a bytestream'>
<example caption='Initiation of Interaction'><![CDATA[
<section1 topic='Protocol'>
<section2 topic='Creating a Bytestream'>
<example caption='Initiation of interaction'><![CDATA[
<iq type='set'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='inband_1'>
<open sid='mySID'
<open sid='i781hf64'
block-size='4096'
xmlns='http://jabber.org/protocol/ibb'/>
</iq>
]]></example>
<p>This asks Juliet if she would like to form an In-Band Bytestreams connection, using the session ID 'mySID' (generated by the initiator here) to uniquely reference the bytestream. The 'block-size' attribute specifies the maximum amount of data (in bytes) that an IBB packet may contain.</p>
<example caption='Success Response'><![CDATA[
]]></example>
<p>This asks Juliet if she would like to form an In-Band Bytestreams connection, using the session ID 'i781hf64' (generated by the initiator here) to uniquely reference the bytestream. The 'block-size' attribute specifies the maximum amount of data (in bytes) that an IBB packet may contain.</p>
<example caption='Success Response'><![CDATA[
<iq type='result'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='inband_1'/>
]]></example>
<p>This is a success response from juliet@capulet.com/balcony, saying that the bytestream is active.</p>
<example caption='Error'><![CDATA[
]]></example>
<p>This is a success response from juliet@capulet.com/balcony, saying that the bytestream is active.</p>
<example caption='Error'><![CDATA[
<iq type='error'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='inband_1'/>
<error code='501' type='cancel'>
<error type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>This is an error response from juliet@capulet.com/balcony saying that an In-Band Bytestreams is not possible.</p>
]]></example>
<p>This is an error response from juliet@capulet.com/balcony saying that an In-Band Bytestreams is not possible.</p>
</section2>
<section2 topic='Sending data'>
<p>Data is sent using either &lt;message&gt; or &lt;iq&gt; stanzas. Either participant in the bytestream may send such packets. The data to be sent, prior to any encoding or wrapping in the stanza, must be no larger than the 'block-size' determined in the stream negotiation. All stanzas are to be addressed to the FULL JID of the bytestream peer. In order to keep track of stanzas sent and any errors received, the sender SHOULD include the 'id' attribute on stanzas sent to the recipient. When using &lt;message&gt; stanzas, &xep0079; SHOULD be used to ensure that the data packet is not spooled or sent to the wrong resource.</p>
<example caption='Sending data using message'><![CDATA[
<message from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' id='msg1'>
<data xmlns='http://jabber.org/protocol/ibb' sid='mySID' seq='0'>
qANQR1DBwU4DX7jmYZnncmUQB/9KuKBddzQH+tZ1ZywKK0yHKnq57kWq+RFtQdCJ
WpdWpR0uQsuJe7+vh3NWn59/gTc5MDlX8dS9p0ovStmNcyLhxVgmqS8ZKhsblVeu
IpQ0JgavABqibJolc3BKrVtVV1igKiX/N7Pi8RtY1K18toaMDhdEfhBRzO/XB0+P
AQhYlRjNacGcslkhXqNjK5Va4tuOAPy2n1Q8UUrHbUd0g+xJ9Bm0G0LZXyvCWyKH
kuNEHFQiLuCY6Iv0myq6iX6tjuHehZlFSh80b5BVV9tNLwNR5Eqz1klxMhoghJOA
</data>
<amp xmlns='http://jabber.org/protocol/amp'>
<rule condition='deliver' value='stored' action='error'/>
<rule condition='match-resource' value='exact' action='error'/>
</amp>
</message>
]]></example>
<example caption='Sending data using iq'><![CDATA[
<iq from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' type='set' id='ibb1'>
<data xmlns='http://jabber.org/protocol/ibb' sid='mySID' seq='0'>
qANQR1DBwU4DX7jmYZnncmUQB/9KuKBddzQH+tZ1ZywKK0yHKnq57kWq+RFtQdCJ
WpdWpR0uQsuJe7+vh3NWn59/gTc5MDlX8dS9p0ovStmNcyLhxVgmqS8ZKhsblVeu
IpQ0JgavABqibJolc3BKrVtVV1igKiX/N7Pi8RtY1K18toaMDhdEfhBRzO/XB0+P
AQhYlRjNacGcslkhXqNjK5Va4tuOAPy2n1Q8UUrHbUd0g+xJ9Bm0G0LZXyvCWyKH
kuNEHFQiLuCY6Iv0myq6iX6tjuHehZlFSh80b5BVV9tNLwNR5Eqz1klxMhoghJOA
</data>
</iq>
]]></example>
<p>The data to send is included as XML character data of the &lt;data/&gt; element after being encoded as Base64 as specified in Section 4 of &rfc4648;. The 'seq' attribute is a 16-bit unsigned integer counter starting at 0, and MUST be incremented for each packet sent. Thus, the next packet sent should have a 'seq' of 1, the one after that with a 'seq' of 2, and so on. The counter loops at maximum, so after value 65535, 'seq' MUST start again at 0.</p>
<p>Note that in the case of iq stanzas, the recipient must reply with an iq of type 'result'.</p>
<example caption='Acknowledging data using iq'><![CDATA[
<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' type='result' id='ibb1'/>
]]></example>
<p>The sender need not wait for these acknowledgements before sending further stanzas. However, it is RECOMMENDED that the sender does wait in order to minimize possible rate-limiting penalties.</p>
<p>It is possible that the stanza may fail to be delivered:</p>
<example caption='Failed delivery with message'><![CDATA[
<message from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='msg1' type='error'>
...
<error code='504' type='cancel'>
<remote-server-timeout xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</message>
]]></example>
<example caption='Failed delivery with iq'><![CDATA[
<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='ibb1' type='error'>
...
<error code='504' type='cancel'>
<remote-server-timeout xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>Upon delivery failure, the sender MUST consider the bytestream to be closed and invalid.</p>
</section2>
<section2 topic='Closing the bytestream'>
<p>To close the bytestream, send the following:</p>
<example caption='Closing the bytestream'><![CDATA[
<iq type='set'
from='romeo@montague.net/orchard'
<section2 topic='Sending Data'>
<p>Each chunk of data is contained in a &lt;data/&gt; element qualified by the 'http://jabber.org/protocol/ibb' namespace. The data element SHOULD be sent in an IQ stanza to enable proper tracking and throttling, but MAY be sent in a message stanza (although this is not encouraged). The data to be sent, prior to any encoding or wrapping in the stanza, must be no larger than the 'block-size' determined in the stream negotiation.</p>
<example caption='Sending data using IQ'><![CDATA[
<iq from='romeo@montague.net/orchard'
id='kr91n475'
to='juliet@capulet.com/balcony'
id='inband_2'>
<close xmlns='http://jabber.org/protocol/ibb' sid='mySID'/>
type='set'>
<data xmlns='http://jabber.org/protocol/ibb' sid='i781hf64' seq='0'>
qANQR1DBwU4DX7jmYZnncmUQB/9KuKBddzQH+tZ1ZywKK0yHKnq57kWq+RFtQdCJ
WpdWpR0uQsuJe7+vh3NWn59/gTc5MDlX8dS9p0ovStmNcyLhxVgmqS8ZKhsblVeu
IpQ0JgavABqibJolc3BKrVtVV1igKiX/N7Pi8RtY1K18toaMDhdEfhBRzO/XB0+P
AQhYlRjNacGcslkhXqNjK5Va4tuOAPy2n1Q8UUrHbUd0g+xJ9Bm0G0LZXyvCWyKH
kuNEHFQiLuCY6Iv0myq6iX6tjuHehZlFSh80b5BVV9tNLwNR5Eqz1klxMhoghJOA
</data>
</iq>
]]></example>
<example caption='Success response'><![CDATA[
<iq type='result'
from='juliet@capulet.com/balcony'
]]></example>
<p>The data to send is included as XML character data of the &lt;data/&gt; element after being encoded as Base64 as specified in Section 4 of &rfc4648;. The 'seq' attribute is a 16-bit unsigned integer counter starting at 0, and MUST be incremented for each packet sent. Thus, the next packet sent should have a 'seq' of 1, the one after that with a 'seq' of 2, and so on. The counter loops at maximum, so after value 65535, 'seq' MUST start again at 0.</p>
<p>In the case of IQ stanzas, the recipient MUST reply to each data packet with an IQ of type 'result'.</p>
<example caption='Acknowledging data using IQ'><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='kr91n475'
to='romeo@montague.net/orchard'
id='inband_2'/>
]]></example>
type='result'/>
]]></example>
<p>The sender need not wait for these acknowledgements before sending further stanzas. However, it is RECOMMENDED that the sender does wait in order to minimize possible rate-limiting penalties.</p>
<p>It is possible that delivery of the stanza might fail.</p>
<example caption='Failed delivery with iq'><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='hr81gs67'
to='romeo@montague.net/orchard'
type='error'>
<error type='cancel'>
<remote-server-timeout xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>Upon delivery failure, the sender MUST consider the bytestream to be closed and invalid.</p>
</section2>
<p>This is a success response from juliet@capulet.com/balcony, saying that the bytestream is now closed.</p>
<example caption='Possible error'><![CDATA[
<section2 topic='Closing the Bytestream'>
<p>To close the bytestream, either party can send an IQ-set containing a &lt;close/&gt; element.</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='i781hf64'/>
</iq>
]]></example>
<example caption='Success response'><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='us71g45j'
to='romeo@montague.net/orchard'
type='result'/>
]]></example>
<p>This is a success response from juliet@capulet.com/balcony, saying that the bytestream is now closed.</p>
<p>It is possible that the recipient of the close notification does not know about the bytestream, in which case it would return an item-not-found error.</p>
<example caption='Possible error'><![CDATA[
<iq type='error'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='inband_2'>
<error code='404' type='cancel'>
id='us71g45j'>
<error type='cancel'>
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>Upon error, the bytestream MUST be considered closed and invalid.</p>
</section2>
<section2 topic='Receiving packets'>
<p>Data packets MUST be processed in the order they are received. If an out-of-sequence packet is received for a particular bytestream (determined by checking the 'seq' attribute), then this indicates that a packet has been lost. The recipient MUST NOT process the data of such an out-of-sequence packet, nor any that follow it within the same bytestream, and at this point MUST consider the bytestream closed and invalid.</p>
]]></example>
<p>Upon error, the bytestream MUST be considered closed and invalid.</p>
</section2>
<section2 topic='Receiving Packets'>
<p>Data packets MUST be processed in the order they are received. If an out-of-sequence packet is received for a particular bytestream (determined by checking the 'seq' attribute), then this indicates that a packet has been lost. The recipient MUST NOT process the data of such an out-of-sequence packet, nor any that follow it within the same bytestream, and at this point MUST consider the bytestream closed and invalid.</p>
</section2>
</section1>
<section1 topic='Bidirectionality' anchor='bidi'>
<p>An in-band bytestream is bidirectional. Therefore, either party to the bytestream is allowed to send data. Each sender MUST initialize the 'seq' attribute to zero and increment the 'seq' value by one with each chunk of data it sends. Each recipient MUST track chunks based on the 'seq' values it receives. The 'seq' values in each direction are independent of the values in the other direction. Thus there are two data sequences for each SessionID. If enabled by the application that uses IBB, the parties MAY negotiate multiple SessionIDs for the same bytestream, however such methods are out of scope for this specification.</p>
</section1>
<section1 topic='Usage Guidelines'>
@ -260,7 +236,7 @@
<section1 topic='XMPP Registrar Considerations'>
<section2 topic='Protocol Namespaces'>
<p>The &REGISTRAR; shall register the 'http://jabber.org/protocol/ibb' namespace as a result of this document.</p>
<p>The &REGISTRAR; includes 'http://jabber.org/protocol/ibb' in its registry of XML namespaces &NAMESPACES;.</p>
</section2>
</section1>