<remark>Per a vote of the Jabber Council, advanced status to Draft.</remark>
</revision>
<revision>
<version>0.6</version>
<date>2003-07-15</date>
<initials>rwe</initials>
<remark>Stream ids not needed on return results. Moved s5b, ibb, and url-data to the actual namespaces of the stream protocols.</remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-07-06</date>
<initials>lw</initials>
<remark>Removed signalling; Strengthened the profile definition requirements; Allowed for optional feature negotiation under certain circumstances</remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-06-30</date>
<initials>lw</initials>
<remark>Actually added XML schemas; Added clarifications/requirements for stream interaction.; Fixed various typos and inconsistencies</remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-06-30</date>
<initials>lw</initials>
<remark>
Added XML schemas; Added XMPP-style error conditions; Added signal/notification support; Moderate reorganization to accommodate changes
</remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-06-23</date>
<initials>tjm</initials>
<remark>
Added linuxwolf as an author (should have been there from the start), form
uses stream-method as the field var, clarified the stream interaction.
<p>As the Jabber protocols are extended beyond basic messaging and presence, the need has arisen for a generic protocol that can be used to negotiate content streams between any two entities. Such streams might be in-band, but more likely will be out-of-band, binary streams used in applications such as file transfer, voice chat, and video conferencing. This document provides a method for negotiating such streams, including meta-information about the intended usage of the stream.</p>
<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 typically accomplished using &xep0030;:</p>
<p>The Receiver advertises the "http://jabber.org/protocol/si" namespace as a feature to represent that they implement this document. The specific profiles are also announced this way; they 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>
<p>Once support is determined, the Sender starts the negotiation with the Receiver by sending an &IQ; stanza of type "set", such as in the following example from &xep0096;:</p>
<p>At this point the Receiver can view the profile and other information to decide if they wish to accept the Stream Initiation. If acceptable the Receiver MUST select one of the presented stream types to use.</p>
<p>At this point, the Sender and Receiver make any preparations necessary for the stream to be used. The exact process is specific to each protocol, and is beyond the scope of this document. This step now marks the end of SI's responsibilities.</p>
<p>The <si/> element is the root element for this protocol. It is an identifiable container for all the information necessary for negotiation and signalling. It contains attributes for the identifier, intended MIME-type, and profile. The contents convey stream-negotation and profile information.</p>
<p>The "id" attribute is an opaque identifier. This attribute MUST be present on type='set', and MUST be a valid string. This SHOULD NOT be sent back on type='result', since the <iq/> "id" attribute provides the only context needed. This value is generated by the Sender, and the same value MUST be used throughout a session when talking to the Receiver.</p>
<p>The "mime-type" attribute identifies the MIME-type for the data across the stream. This attribute MUST be a valid MIME-type as registered with &IANA; (specifically, as listed at <<linkurl='http://www.iana.org/assignments/media-types'>http://www.iana.org/assignments/media-types</link>>). During negotiation, this attribute SHOULD be present, and is otherwise not required. If not included during negotiation, its value is assumed to be "binary/octect-stream".</p>
<p>The "profile" attribute defines the SI profile in use. This value MUST be present during negotiation, and is the namespace of the profile to use.</p>
<p>When the Sender first negotiates a Stream Initiation, all of the attributes SHOULD be present, and the id" and "profile" MUST be present. The contents MUST contain one profile, in the namespace declared in the "profile" attribute, and the feature negotiation for the stream. The feature negotiation MUST contain at least one option and use the field var "stream-method".</p>
<p>When the Receiver accepts a Stream Initiation, the <si/> element SHOULD NOT possess any attributes. The selected stream MUST be in the feature negotiation for the stream. There MUST only be one selected stream.</p>
</section2>
<section2topic='Error Codes'anchor='def-error'>
<p>To simplify the discussion on error conditions, this document uses the following mapping between namespace URIs and namespace prefixes<note>This mapping is provided for the purpose of simplifying this discussion, and is not intended to be used in the actual protocol.</note>.</p>
<tablecaption='Namespace Mappings'>
<tr>
<th>Prefix</th>
<th>URI</th>
</tr>
<tr>
<td>xmpp</td>
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
</tr>
<tr>
<td>si</td>
<td>http://jabber.org/protocol/si</td>
</tr>
</table>
<p>Below are the most common errors that can result.</p>
<tablecaption='Error Conditions/Codes'>
<tr>
<th>Error Code</th>
<th>Error Type</th>
<th>General Condition</th>
<th>Specific Condition</th>
<th>Description</th>
</tr>
<tr>
<td>400</td>
<td>cancel</td>
<td><xmpp:bad-request/></td>
<td><si:no-valid-streams/></td>
<td>None of the available streams are acceptable.</td>
</tr>
<tr>
<td>400</td>
<td>modify</td>
<td><xmpp:bad-request/></td>
<td><si:bad-profile/></td>
<td>The profile is not understood or invalid. The profile MAY supply a profile-specific error condition.</td>
<p>Stream Initiation on its own is of limited use; the Receiver almost always requires some reason for SI. Knowing this allows the Receiver to make a more educated choice about whether or not to accept the stream. This information is provided in Stream Initiation via a <em>profile</em>. A profile is a collection of information that describes the reason for and structure of the stream data, including what the data represents and what stream protocols are expected to be supported.</p>
<p>The initial request for Stream Initiation MUST have only one profile, and this profile is in its own namespace. The profile is indicated not only by the presence of a "root" element in that particular namespace, but also be the "profile" attribute in <si/> The SUGGESTED format for profile namespaces is:</p>
<p>The information that the profile presents SHOULD be defined in an official XEP. The XEP defining the profile SHOULD contain explanations of what the profile consists of and MUST define the profile in a complete manner using DTD, Schema or another appropiate definition language.</p>
<p>A profile SHOULD define what stream protocols MUST be supported, and MUST define what stream protocols MAY be supported. If a profile specifies only a single stream protocol that MUST be supported (even if others MAY also be supported), the "fneg" for the stream protocol may be omitted from the initial <si/>; the receiving entity then assumes the stream protocol that MUST be supported is the one to use.</p>
<p>This document does not define any profiles, nor does it place any restrictions on what type of information a profile should detail. Other specifications will define profiles to be used with Stream Initiation.</p>
<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 transported on the <si/> element is intended to do this. Once a session is fully negotiated, the value of the <si/> "id" attribute is used during the actual stream negotiation as the protocol's stream identifier attribute.</p>
<p>To be compatible to this document, a stream protocol MUST define a stream identifier (typically "sid"), which MUST have a unique string representation. The stream protocol MUST be able to use any string identifier chosen during Stream Initiation, as long as the sending party does not use the same identifier more than once.</p>
<p>The XMPP Registrar shall maintain a registry of stream initiation profiles, located at <<linkurl='http://www.jabber.org/registrar/si-profiles.html'>http://www.jabber.org/registrar/si-profiles.html</link>>. Any such profile defined in a Jabber Enhancement Proposal MUST be submitted to the XMPP Registrar; profiles defined in non-standard protocol extensions SHOULD be submitted to the XMPP Registrar.</p>
