summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorGuillaume Desmottes <guillaume.desmottes@collabora.co.uk>2008-12-11 12:43:09 +0000
committerGuillaume Desmottes <guillaume.desmottes@collabora.co.uk>2008-12-11 12:43:09 +0000
commit00a875cb27c34e71faed29f304a5a9ae8597255f (patch)
tree7c3ec7a22817eca3ca142020082f4165889423a2 /docs
parent57458dd0c16dc69ba7b38e7d84cc96d3a402b4fa (diff)
document si-multiple protocol
Diffstat (limited to 'docs')
-rw-r--r--docs/Makefile.am1
-rw-r--r--docs/si-multiple.xml105
2 files changed, 106 insertions, 0 deletions
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 61c8cc2f0..934779996 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -7,6 +7,7 @@ man_MANS = telepathy-gabble.8
html_DATA = \
olpc.html \
muc-bytestream.html \
+ si-multiple.html \
tubes.html
EXTRA_DIST = \
diff --git a/docs/si-multiple.xml b/docs/si-multiple.xml
new file mode 100644
index 000000000..03a914afb
--- /dev/null
+++ b/docs/si-multiple.xml
@@ -0,0 +1,105 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE xep [
+ <!ENTITY NS_SI_MULTIPLE "http://telepathy.freedesktop.org/xmpp/si-multiple" >
+]>
+<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
+<xep>
+<header>
+ <title>Stream initiation multi-bytestreams extension</title>
+ <abstract>Extension of <spec>XEP-0095</spec> allowing to negotiate more
+ than one bytestream to be used as a fallback.</abstract>
+ <legal>Copyright (c) 2008 Collabora Limited. This document may be
+ distributed under the same terms as the Telepathy specification.</legal>
+ <number>si-multiple</number>
+ <status>ProtoXEP</status>
+ <type>Extension</type>
+ <sig>Standards</sig>
+ <approver>Telepathy project</approver>
+ <dependencies>
+ <spec>XMPP Core</spec>
+ <spec>XEP-0095</spec>
+ </dependencies>
+ <supersedes/>
+ <supersededby/>
+ <shortname>NOT YET ASSIGNED</shortname>
+ <author>
+ <firstname>Guillaume</firstname>
+ <surname>Desmottes</surname>
+ <email>guillaume.desmottes@collabora.co.uk</email>
+ <jid>guillaume.desmottes@collabora.co.uk</jid>
+ </author>
+ <revision>
+ <version>0.0.1</version>
+ <date>2008-12-11</date>
+ <initials>cassidy</initials>
+ <remark><p>First draft.</p></remark>
+ </revision>
+</header>
+<section1 topic='Introduction' anchor='intro'>
+ <p>This document describes an extension of the Stream Initiation (SI)
+ protocol. With current SI protocol, the receiver has to choose which
+ bytestream method he wants to use for the data streaming.
+ If he chooses an efficient method as SOCKS5 (<spec>XEP-0065</spec>)
+ and this method fails because of network topology, the SI fails and
+ data can't be transferred. The protocol described in this document
+ aims to solve this problem by allowing users to fallback to another
+ bytestream method if the first one failed.</p>
+</section1>
+
+<section1 topic='Use Cases' anchor='usecases'>
+ <p>When sending a SI request, the sender informs the receiver that he
+ supports multi-bytestreams by adding the si-multiple node.</p>
+
+ <example caption='Romeo sends a SI offer to Juliet'>
+ <![CDATA[
+ <iq to='juliet@capulet.lit/Balcony' type='reply' id='H_1' from='romeo@montague.lit/Home'>
+ <si xmlns='http://jabber.org/protocol/si' profile='http://telepathy.freedesktop.org/xmpp/tubes' id='alpha'>
+ <feature xmlns='http://jabber.org/protocol/feature-neg'>
+ <x xmlns='jabber:x:data' type='form'>
+ <field var='stream-method' type='list-single'>
+ <option><value>http://jabber.org/protocol/bytestreams</value></option>
+ <option><value>http://jabber.org/protocol/ibb</value></option>
+ </field>
+ </x>
+ </feature>
+ <stream xmlns='http://telepathy.freedesktop.org/xmpp/tubes' tube='370459677'/>
+ <si-multiple xmlns='http://telepathy.freedesktop.org/xmpp/si-multiple'/>
+ </si>
+ </iq>
+ ]]>
+ </example>
+
+ <p>If the receiver support multi-bytestreams as well, he sends a list of the methods supported
+ instead of the normal SI reply. Bytestreams will be try by the sender in that order.</p>
+ <example caption='Juliet replies to SI offer'>
+ <![CDATA[
+ <iq to='juliet@capulet.lit/Balcony' type='set' id='H_1' from='romeo@montague.lit/Home'>
+ <si xmlns='http://jabber.org/protocol/si'>
+ <si-multiple xmlns='http://telepathy.freedesktop.org/xmpp/si-multiple>
+ <value>http://jabber.org/protocol/bytestreams</value>
+ <value>http://jabber.org/protocol/ibb</value>
+ </si-multiple>
+ </si>
+ </iq>
+ ]]>
+
+ <p>At this point Romeo starts to initiate the bytestream using the first method (<spec>XEP-0065</spec>).
+If that fails, he'll try the second one (<spec>XEP-0047</spec>). Each bytestream is negotiated
+according the protocol described in its XEP. Once a bytestream has been sucessfully established,
+all the data are send using it and the other methods are not used.</p>
+ </example>
+
+</section1>
+<section1 topic='Security Considerations' anchor='security'>
+ <p>None.</p>
+</section1>
+<section1 topic='IANA Considerations' anchor='iana'>
+ <p>None.</p>
+</section1>
+<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
+ <p>None.</p>
+</section1>
+<section1 topic='XML Schema' anchor='schema'>
+ TODO
+</section1>
+</xep>