mirror of https://github.com/moparisthebest/xeps
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.
428 lines
14 KiB
428 lines
14 KiB
<?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>
|
|
|