mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-05 00:45:05 -05:00
429 lines
14 KiB
XML
429 lines
14 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
|
<!ENTITY % ents SYSTEM "xep.ent">
|
|
%ents;
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
|
<xep>
|
|
<header>
|
|
<title>Stream Initiation</title>
|
|
<abstract>A common method to initiate a stream with meta information</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0087</number>
|
|
<status>Retracted</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<dependencies><spec>XEP-0030</spec></dependencies>
|
|
<supersedes/>
|
|
<supersededby><spec>XEP-0095</spec></supersededby>
|
|
<shortname>si</shortname>
|
|
<author>
|
|
<firstname>Thomas</firstname>
|
|
<surname>Muldowney</surname>
|
|
<email>temas@jabber.org</email>
|
|
<jid>temas@jabber.org</jid>
|
|
</author>
|
|
<revision>
|
|
<version>0.1</version>
|
|
<date>2003-05-22</date>
|
|
<initials>tjm</initials>
|
|
<remark>Initial version.</remark>
|
|
</revision>
|
|
</header>
|
|
<section1 topic='Introduction'>
|
|
<p>
|
|
As more people begin to make use of streams in Jabber, there becomes a need
|
|
for more descriptive negotiation of which stream to use. This document provides
|
|
a method to negotiate a stream and provide some meta-information about the
|
|
streams usage.
|
|
</p>
|
|
</section1>
|
|
<section1 topic='Requirements'>
|
|
<ul>
|
|
<li>
|
|
The defined protocol will allow for negotiation of a common stream.
|
|
</li>
|
|
<li>
|
|
The defined protocol will allow for meta-information to be sent about the
|
|
stream usage.
|
|
</li>
|
|
<li>
|
|
The defined protocol will not be required for stream usage.
|
|
</li>
|
|
</ul>
|
|
<section2 topic='Use Case'>
|
|
<p>
|
|
Sender wishes to interact with another user, using a method that requires
|
|
streams.
|
|
</p>
|
|
<p>
|
|
Primary Flow:
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
Sender discovers if Receiver implements the desired profile. [E1]
|
|
</li>
|
|
<li>
|
|
Sender offers a stream initiation. [E2]
|
|
</li>
|
|
<li>
|
|
Receiver accepts stream initiation.
|
|
</li>
|
|
<li>
|
|
Sender uses the negotiated stream and profile to send the information.
|
|
</li>
|
|
</ol>
|
|
<p>
|
|
Error Conditions:
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
The Receiver does not support the desired profile, EUC
|
|
</li>
|
|
<li>
|
|
Receiver rejects the stream initiation, EUC
|
|
</li>
|
|
</ol>
|
|
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Basic Usage'>
|
|
<p>
|
|
Before a Stream Initiation is attempted the Sender should be sure that the
|
|
Receiver supports both Stream Initiation and the specific profile that they
|
|
wish to use. This is discovered by using &xep0030;:
|
|
</p>
|
|
<example caption='Requesting Disco Information From Receiver'>
|
|
<![CDATA[
|
|
<iq
|
|
type='get'
|
|
to='receiver@jabber.org/resource'
|
|
from='sender@jabber.org/resource'
|
|
id='info1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
]]>
|
|
</example>
|
|
<p>
|
|
The Receiver will advertise the "http://jabber.org/protocol/si" namespace as
|
|
a feature to represent they implement this document. The specific profiles can
|
|
be found by looking for
|
|
"http://jabber.org/protocol/si/profile/profile-name". Shown in the result
|
|
is a potential file transfer profile:
|
|
</p>
|
|
<example caption='Receiver Disco Information Result'>
|
|
<![CDATA[
|
|
<iq
|
|
type='result'
|
|
to='sender@jabber.org/resource'
|
|
from='receiver@jabber.org/resource'
|
|
id='info1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
<feature var='http://jabber.org/protocol/si'/>
|
|
<feature var='htpt://jabber.org/protocol/si/profile/filexfer'/>
|
|
</query>
|
|
</iq>
|
|
]]>
|
|
</example>
|
|
<p>
|
|
Now that the Sender is sure that the Receiver support Stream Initiation they
|
|
send the offer:
|
|
</p>
|
|
<example caption='Offer Stream Initiation'>
|
|
<![CDATA[
|
|
<iq type='set' id='offer1' to='receiver@jabber.org/resource'>
|
|
<si
|
|
xmlns='http://jabber.org/protocol/si'
|
|
id='a0'
|
|
mime-type='application/octet-stream'
|
|
profile='http://jabber.org/protocol/si/profile/profile-name'>
|
|
<header name='key'>value</header>
|
|
<feature xmlns='http://jabber.org/protocol/feature-neg'>
|
|
<x xmlns='jabber:x:data'>
|
|
<field var='file-transfer-method' type='list-single'>
|
|
<option><value>s5b</value></option>
|
|
<option><value>jabber:iq:oob</value></option>
|
|
<option><value>ibb</value></option>
|
|
</field>
|
|
</x>
|
|
</feature>
|
|
</si>
|
|
</iq>
|
|
]]>
|
|
</example>
|
|
<!--
|
|
<example caption='Offer Stream Initiation (Profile in NS)'>
|
|
<![CDATA[
|
|
<iq type='set' id='offer1' to='receiver@jabber.org/resource'>
|
|
<si
|
|
xmlns='http://jabber.org/protocol/si'
|
|
id='a0'
|
|
mime-type='application/octet-stream'>
|
|
<profile xmlns='http://jabber.org/protocol/si/profile/profile-name'>
|
|
<foo>
|
|
<bar>baz</bar>
|
|
</foo>
|
|
</profile>
|
|
<feature xmlns='http://jabber.org/protocol/feature-neg'>
|
|
<x xmlns='jabber:x:data'>
|
|
<field var='file-transfer-method' type='list-single'>
|
|
<option><value>s5b</value></option>
|
|
<option><value>jabber:iq:oob</value></option>
|
|
<option><value>ibb</value></option>
|
|
</field>
|
|
</x>
|
|
</feature>
|
|
</si>
|
|
</iq>
|
|
]]>
|
|
</example>
|
|
-->
|
|
<!--
|
|
<example caption='Offer Regular File Transfer (Alternate Stream Negotiation)'>
|
|
<![CDATA[
|
|
<si
|
|
xmlns='http://jabber.org/protocol/si'
|
|
id='a0'
|
|
mime-type='application/octet-stream'
|
|
profile='filexfer'>
|
|
<header name='size'>37678</header>
|
|
<header name='hash'>a9234abbff332</header>
|
|
<header name='name'>filename.txt</header>
|
|
<stream>s5b</stream>
|
|
<stream>jabber:iq:oob</stream>
|
|
<stream>ibb</stream>
|
|
</si>
|
|
]]>
|
|
</example>
|
|
-->
|
|
<p>
|
|
At this point the Receiver can view the headers and other information to
|
|
decide if they wish to accept the Stream Initiation. If they accept they
|
|
MUST select one of the presented stream types to use. If none of the stream
|
|
types are acceptable the Receiver MUST reply with an error:
|
|
</p>
|
|
<example caption='Accept Stream Initiation'>
|
|
<![CDATA[
|
|
<iq type='result' to='sender@jabber.org/resource' id='offer1'>
|
|
<si
|
|
xmlns='http://jabber.org/si'
|
|
id='a0'>
|
|
<feature xmlns='http://jabber.org/protocol/feature-neg'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='file-transfer-method'>
|
|
<value>s5b</value>
|
|
</field>
|
|
</x>
|
|
</feature>
|
|
</si>
|
|
</iq>
|
|
]]>
|
|
</example>
|
|
<example caption='Rejecting Stream Initiation'>
|
|
<![CDATA[
|
|
<iq type='error' to='sender@jabber.org/resource' id='offer1'>
|
|
<error code='403'>Offer Declined</error>
|
|
</iq>
|
|
]]>
|
|
</example>
|
|
<example caption='No Valid Streams'>
|
|
<![CDATA[
|
|
<iq type='error' to='sender@jabber.org/resource' id='offer1'>
|
|
<error code='406'>No Valid Streams</error>
|
|
</iq>
|
|
]]>
|
|
</example>
|
|
<p>
|
|
If the Receiver has accepted the Stream Initiation the Sender may then used
|
|
the semantics defined by the selected stream and start the usage.
|
|
</p>
|
|
<!--
|
|
<example caption='Accept File Transfer (Alternate Stream Negotiation)'>
|
|
<![CDATA[
|
|
<si
|
|
xmlns='http://jabber.org/protocol/si'
|
|
id='a0'>
|
|
<stream>s5b</stream>
|
|
</si>
|
|
]]>
|
|
</example>
|
|
<example caption='Offer to Start a MP3 Stream'>
|
|
<![CDATA[
|
|
<si
|
|
xmlns='http://jabber.org/protocol/si'
|
|
id='s0'
|
|
mime-type='audio/x-mp3'
|
|
profile='streaming-audio'>
|
|
<feature xmlns='http://jabber.org/protocol/feature-neg'>
|
|
<x xmlns='jabber:x:data'>
|
|
<field var='file-transfer-method' type='list-single'>
|
|
<option><value>s5b</value></option>
|
|
<option><value>ibb</value></option>
|
|
</field>
|
|
</x>
|
|
</feature>
|
|
</si>
|
|
]]>
|
|
</example>
|
|
<example caption='Offer to Start a MP3 Stream (Alternate Stream Negotiation)'>
|
|
<![CDATA[
|
|
<si
|
|
xmlns='http://jabber.org/protocol/si'
|
|
id='s0'
|
|
mime-type='audio/x-mp3'
|
|
profile='streaming-audio'>
|
|
<stream>s5b</stream>
|
|
<stream>ibb</stream>
|
|
</si>
|
|
]]>
|
|
</example>
|
|
-->
|
|
</section1>
|
|
<section1 topic='Detailed Usage'>
|
|
<section2 topic='Profiles'>
|
|
<p>
|
|
While Stream Initiation itself is helpful, it makes much more sense when
|
|
what is being transported over the stream is known. Knowing this
|
|
allows the Receiver to make a more educated choice about whether or not to
|
|
accept the stream. This information is transported in Stream Initiation
|
|
through a <em>profile</em>. A profile is a series of required and
|
|
optional headers that describe the stream data or how the stream is to be
|
|
used. Each Stream Initiation MUST have only one profile, so the stream
|
|
usage is kept clear.
|
|
</p>
|
|
<p>
|
|
Creating a profile is fairly simple. First, a name is chosen, the
|
|
complete name is formatted like:</p>
|
|
<code>
|
|
http://jabber.org/protocol/si/profile/profile-name
|
|
</code>
|
|
<p>
|
|
The complete name is what is presented in information discovery requests
|
|
in order to show that the profile is supported. It is also used for the
|
|
<si> profile attribute. Next, the information for the headers is
|
|
decided upon. Each piece of information will be transported in a
|
|
<header> tag. The name attribute is a descriptive key that can be
|
|
looked up at the XMPP Registrar or XEP describing the profile. The
|
|
actual data in the <header> is the fact related to the name
|
|
attribute. It must also be stated whether the header is required or
|
|
optional.
|
|
</p>
|
|
<p>
|
|
This document does not define any profiles, nor does it place any restrictions
|
|
on what type of information a profile should detail. This document also does
|
|
not place restrictions on what may be placed in a <header>. Other
|
|
XEPs will define profiles to be used with Stream Initiation.
|
|
</p>
|
|
</section2>
|
|
<section2 topic='Stream Interaction'>
|
|
<p>
|
|
While Stream Initiation is not directly required for stream usage, it does
|
|
provide many benefits. In order to fully appreciate these benefits,
|
|
streams must link the Stream Initiation to the stream. The id
|
|
attribute of the <si> node is intended to provide this link. It is
|
|
out of scope of this document to define how streams will make use of this
|
|
facility, but it does suggest some methods:</p>
|
|
<ul>
|
|
<li>
|
|
Transport the Stream Initiation id with the stream negotitation as a
|
|
namespaced attribute, such as:
|
|
<code>
|
|
<![CDATA[
|
|
<stream id='0' xmlns:si='http://jabber.org/protocol/si' si:id='si0'>
|
|
<start/>
|
|
</stream>
|
|
]]>
|
|
</code>
|
|
</li>
|
|
<li>
|
|
Transport the Stream Initiation id in a namespaced tag, such as:
|
|
<code>
|
|
<![CDATA[
|
|
<stream id='0'>
|
|
<start/>
|
|
<si xmlns='http://jabber.org/protocol/si' id='si0'/>
|
|
</stream>
|
|
]]>
|
|
</code>
|
|
</li>
|
|
</ul>
|
|
</section2>
|
|
<section2 topic='<si> Explanation'>
|
|
<p>
|
|
The attributes and data of <si> are fairly simple:</p>
|
|
<ul>
|
|
<li>
|
|
<em>id</em> - An opaque identifier generated by the Sender.
|
|
</li>
|
|
<li>
|
|
<em>mime-type</em> - The mime-type of the data being negotiated,
|
|
selected by Sender.
|
|
</li>
|
|
<li>
|
|
<em>profile</em> - The profile's fulle name, selected by Sender.
|
|
</li>
|
|
</ul>
|
|
<p>The data of the node is a mixture of a feature negotiation for the stream
|
|
and the profiles headers.
|
|
</p>
|
|
<p>
|
|
When the Sender is offering a Stream Initiation all of the attributes must
|
|
be present. The data MUST contain the required profile headers and the
|
|
feature negotiation for the stream MUST be present with at least one
|
|
option. The optional profile headers MAY also be in the node data.
|
|
</p>
|
|
<p>
|
|
When the Receiver accepts a Stream Initiation the id attribute MUST be
|
|
present, all other attributes MUST NOT be present. The selected stream
|
|
MUST be in the feature negotiation for the stream. There MUST only be one
|
|
selected stream.
|
|
</p>
|
|
</section2>
|
|
<section2 topic='Error Codes'>
|
|
<p>
|
|
There are two error codes that are used. Following are the conditions,
|
|
meanings and data:</p>
|
|
<ul>
|
|
<li>
|
|
<em>Declining Transfer (403)</em>: During the Stream Initiation
|
|
the Receiver may decline the transfer by sending the 403 error. The
|
|
<error/> CDATA MAY contain a descriptive reason why, but is not
|
|
necessary.
|
|
</li>
|
|
<li>
|
|
<em>No Available Methods (406)</em>: When the Sender presents the
|
|
available stream methods, and the Receiver can not use any of them,
|
|
they send a 406 error. The <error/> CDATA is not important.
|
|
</li>
|
|
</ul>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Security Considerations'>
|
|
<p>
|
|
Data security concerns are left to the profiles to define. Wire security
|
|
concerns are left to the stream definitions.
|
|
</p>
|
|
</section1>
|
|
<section1 topic='IANA Considerations'>
|
|
<p>
|
|
This document uses the MIME types as recorded by IANA, but no other direct
|
|
interaction is necessary.
|
|
</p>
|
|
</section1>
|
|
<section1 topic='XMPP Registrar Considerations'>
|
|
<p>
|
|
The "http://jabber.org/protocol/si" namespace will be registered.
|
|
The registrar will track header profiles for different stream initiation
|
|
uses.
|
|
</p>
|
|
</section1>
|
|
<section1 topic='Formal Definition'>
|
|
<section2 topic='Schema'>
|
|
<p>To follow.</p>
|
|
</section2>
|
|
<section2 topic='DTD'>
|
|
<p>To follow.</p>
|
|
</section2>
|
|
</section1>
|
|
</xep>
|