mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-29 04:32:23 -05:00
80fde9ae41
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1627 4b5297f7-1745-476d-ba37-a9c6900126ab
1112 lines
63 KiB
XML
1112 lines
63 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>Jingle</title>
|
|
<abstract>This specification defines an XMPP protocol extension for initiating and managing peer-to-peer media sessions between two XMPP entities in a way that is interoperable with existing Internet standards. The protocol provides a pluggable model that enables the core session management semantics to be used for a wide variety of application types (e.g., voice chat, video chat, file sharing) and with a wide variety of transport methods (e.g., TCP, UDP, ICE, application-specific transports).</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0166</number>
|
|
<status>Proposed</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<approver>Council</approver>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>TO BE ASSIGNED</shortname>
|
|
&scottlu;
|
|
&joebeda;
|
|
&stpeter;
|
|
&robmcqueen;
|
|
&seanegan;
|
|
&hildjj;
|
|
<revision>
|
|
<version>0.23</version>
|
|
<date>2008-01-11</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Removed content-accept after content-remove; removed errors for unsupported-content and unsupported-transports since they are handled via session-terminate; clarified handling of responder attribute.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.22</version>
|
|
<date>2007-12-06</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Modified session flows for busy, unsupported application formats, and unsupported transport methods to enable separation between Jingle core and distinct modules for applications and transports; moved resource determination recommendations to XEP-208.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.21</version>
|
|
<date>2007-11-27</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Further editorial review.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.20</version>
|
|
<date>2007-11-15</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Editorial review and consistency check; moved voice chat scenarios to XEP-0167.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.19</version>
|
|
<date>2007-11-13</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Added scenario for handling of busy state, including Jingle-specific error code and modified error flow (no longer an instance of decline).</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.18</version>
|
|
<date>2007-11-08</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Added scenarios for various session flows; clarified handling of content-add, content-modify, and content-remove actions; clarified rules for codec priority.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.17</version>
|
|
<date>2007-06-20</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Added <unsupported-info/> error.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.16</version>
|
|
<date>2007-06-06</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Clarified resource determination process and updated text to reflect modifications to XEP-0168.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.15</version>
|
|
<date>2007-05-25</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Rewrote introduction and moved historical text to separate section.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.14</version>
|
|
<date>2007-04-17</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Clarified session lifetime; defined reason attribute and associated registry; further specified conformance requirements.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.13</version>
|
|
<date>2007-03-23</date>
|
|
<initials>psa/ram</initials>
|
|
<remark><p>Simplified signalling process and state chart; Removed session-redirect action (use redirect error instead); removed content-decline action; removed transport-* actions (except transport-info for ICE negotiation); removed description-* actions; simplified syntax to allow only one transport per content type; corrected syntax of creator attribute to be either initiator or responder (not JIDs); added profile attribute to content element in order to specify RTP profile in use.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.12</version>
|
|
<date>2006-12-21</date>
|
|
<initials>psa/ram</initials>
|
|
<remark><p>Added creator attribute to content element for prevention of race condition; modified spec to use provisional namespace before advancement to Draft (per XEP-0053).</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.11</version>
|
|
<date>2006-10-31</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Completed clarifications and corrections throughout; added section on Jingle Actions.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.10</version>
|
|
<date>2006-09-29</date>
|
|
<initials>ram/psa</initials>
|
|
<remark><p>Made several corrections to the state machines and examples.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.9</version>
|
|
<date>2006-09-08</date>
|
|
<initials>ram/psa</initials>
|
|
<remark><p>Further cleaned up state machines and state-related actions.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.8</version>
|
|
<date>2006-08-23</date>
|
|
<initials>ram/psa</initials>
|
|
<remark><p>Changed channels to components in line with ICE; changed various action names for consistency; added session-extend and session-reduce actions to add and remove description/transport pairs; added description-modify action; added sender attribute to specify directionality.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.7</version>
|
|
<date>2006-07-17</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Added implementation note about handling multiple content types.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.6</version>
|
|
<date>2006-07-12</date>
|
|
<initials>se/psa</initials>
|
|
<remark><p>Changed media type to content type.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.5</version>
|
|
<date>2006-03-20</date>
|
|
<initials>psa/jb</initials>
|
|
<remark><p>Further clarified state machine diagrams; specified that session accept must include agreed-upon media format and transport description; moved deployment notes to appropriate transport spec.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.4</version>
|
|
<date>2006-03-01</date>
|
|
<initials>psa/jb</initials>
|
|
<remark><p>Added glossary; clarified state machines; updated to reflect publication of XEP-0176 and XEP-0177.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.3</version>
|
|
<date>2006-02-24</date>
|
|
<initials>psa/jb</initials>
|
|
<remark><p>Provided more detail about modify scenarios; defined media-specific and transport-specific actions and adjusted state machine accordingly.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.2</version>
|
|
<date>2006-02-13</date>
|
|
<initials>psa/jb</initials>
|
|
<remark><p>Per agreement among the co-authors, moved transport definition to separate specification, simplified state machine, and made other associated changes to the text, examples, and schemas; also harmonized redirect, decline, and terminate processes.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.1</version>
|
|
<date>2005-12-15</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Initial version.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.10</version>
|
|
<date>2005-12-11</date>
|
|
<initials>psa</initials>
|
|
<remark><p>More fully documented burst mode, connectivity checks, error cases, etc.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.9</version>
|
|
<date>2005-12-08</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Restructured document flow; provided example of burst mode.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.8</version>
|
|
<date>2005-12-05</date>
|
|
<initials>psa/sl/jb</initials>
|
|
<remark><p>Distinguished between dribble mode and burst mode, including mode attribute, service discovery features, and implementation notes; provided detailed resource discovery examples; corrected state chart; specified session termination; specified error conditions; specified semantics of informational messages; began to define security considerations; added Joe Beda as co-author.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.7</version>
|
|
<date>2005-11-08</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Added more detail to basic session flow; harmonized candidate negotiation process with ICE.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.6</version>
|
|
<date>2005-10-27</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Added XMPP Registrar considerations; defined schema; completed slight syntax cleanup.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.5</version>
|
|
<date>2005-10-21</date>
|
|
<initials>psa/sl</initials>
|
|
<remark><p>Separated method description formats from signalling protocol.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.4</version>
|
|
<date>2005-10-19</date>
|
|
<initials>psa/sl</initials>
|
|
<remark><p>Harmonized basic session flow with Google Talk protocol; added Scott Ludwig as co-author.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.3</version>
|
|
<date>2005-10-10</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Added more detail to basic session flow.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.2</version>
|
|
<date>2005-10-07</date>
|
|
<initials>psa/jjh</initials>
|
|
<remark><p>Protocol cleanup.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.1</version>
|
|
<date>2005-10-06</date>
|
|
<initials>psa/jjh</initials>
|
|
<remark><p>First draft.</p></remark>
|
|
</revision>
|
|
</header>
|
|
<section1 topic='Introduction' anchor='intro'>
|
|
<p>The purpose of Jingle is to enable one-to-one, peer-to-peer media sessions between XMPP entities, where the negotiation occurs over the XMPP "channel" and the media is exchanged outside the XMPP channel using technologies such as the Real-time Transport Protocol (RTP; &rfc3550;), the User Datagram Protocol (UDP; &rfc0768;), and &ice;.</p>
|
|
<p>One target application for Jingle is simple voice chat (see &xep0167;). We stress the word "simple". The purpose of Jingle is not to build a full-fledged telephony application that supports call waiting, call forwarding, call transfer, hold music, IVR systems, find-me-follow-me functionality, conference calls, and the like. These features are of interest to some user populations, but adding support for them to the core Jingle layer would introduce unnecessary complexity into a technology that is designed for basic multimedia interaction.</p>
|
|
<p>The purpose of Jingle is not to supplant or replace technologies based on Session Initiation Protocol (SIP; &rfc3261;). Because dual-stack XMPP+SIP clients are difficult to build, Jingle was designed as a pure XMPP signalling protocol. However, Jingle is at the same time designed to interwork with SIP so that the millions of deployed XMPP clients can be added onto existing Voice over Internet Protocol (VoIP) networks, rather than limiting XMPP users to a separate and distinct network.</p>
|
|
<p>Jingle is designed in a modular way so that developers can easily add support for multimedia session types other than voice chat, such as video chat (see &xep0180;), application sharing, file sharing, collaborative editing, whiteboarding, and torrent broadcasting. The transport methods are also modular, so that Jingle implementations can use any appropriate media transport (including proprietary methods not standardized through the XMPP Standards Foundation).</p>
|
|
</section1>
|
|
<section1 topic='How It Works' anchor='howitworks'>
|
|
<p>This section provides a friendly introduction to Jingle.</p>
|
|
<p>In essence, Jingle enables two XMPP entities (e.g., romeo@montague.lit and juliet@capulet.lit) to set up, manage, and tear down a multimedia session. The negotiation takes place over XMPP, and the media transfer takes place outside of XMPP. The simplest session flow is as follows:</p>
|
|
<code><![CDATA[
|
|
Romeo Juliet
|
|
| |
|
|
| session-initiate |
|
|
|---------------------------->|
|
|
| ack |
|
|
|<----------------------------|
|
|
| session-accept |
|
|
|<----------------------------|
|
|
| ack |
|
|
|---------------------------->|
|
|
| MEDIA SESSION |
|
|
|<===========================>|
|
|
| session-terminate |
|
|
|<----------------------------|
|
|
| ack |
|
|
|---------------------------->|
|
|
| |
|
|
]]></code>
|
|
<p>Naturally, more complex scenarios are probable; such scenarios are described in other specifications, such as <cite>XEP-0167</cite> for voice chat.</p>
|
|
<p>The simplest flow might happen as follows. The example is that of a voice chat (see <cite>XEP-0167</cite>) initiated by Romeo, where the transport is &xep0177;.</p>
|
|
<example caption="Initiator sends session-initiate"><![CDATA[
|
|
<iq from='romeo@montague.lit/orchard'
|
|
id='jingle1'
|
|
to='juliet@capulet.lit/balcony'
|
|
type='set'>
|
|
<jingle xmlns='urn:xmpp:tmp:jingle'
|
|
action='session-initiate'
|
|
initiator='romeo@montague.lit/orchard'
|
|
sid='a73sjjvkla37jfea'>
|
|
<content creator='initiator' name='this-is-the-audio-content' profile='RTP/AVP'>
|
|
<description xmlns='urn:xmpp:tmp:jingle:apps:audio-rtp'>
|
|
<payload-type id='96' name='speex' clockrate='16000'/>
|
|
<payload-type id='97' name='speex' clockrate='8000'/>
|
|
<payload-type id='18' name='G729'/>
|
|
<payload-type id='103' name='L16' clockrate='16000' channels='2'/>
|
|
<payload-type id='98' name='x-ISAC' clockrate='8000'/>
|
|
</description>
|
|
<transport xmlns='urn:xmpp:tmp:jingle:transports:raw-udp'>
|
|
<candidate ip='10.1.1.104' port='13540' generation='0'/>
|
|
</transport>
|
|
</content>
|
|
</jingle>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Receiver acknowledges session-initiate"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='jingle1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='result'/>
|
|
]]></example>
|
|
<p>If the proposed session is acceptable, the responder definitively accepts it.</p>
|
|
<example caption="Receiver sends session-accept"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='accept1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='set'>
|
|
<jingle xmlns='urn:xmpp:tmp:jingle'
|
|
action='session-accept'
|
|
initiator='romeo@montague.lit/orchard'
|
|
responder='juliet@capulet.lit/balcony'
|
|
sid='a73sjjvkla37jfea'>
|
|
<content creator='initiator' name='this-is-the-audio-content' profile='RTP/AVP'>
|
|
<description xmlns='urn:xmpp:tmp:jingle:apps:audio-rtp'>
|
|
<payload-type id='97' name='speex' clockrate='8000'/>
|
|
<payload-type id='18' name='G729'/>
|
|
<payload-type id='0' name='PCMU' />
|
|
<payload-type id='102' name='iLBC'/>
|
|
<payload-type id='4' name='G723'/>
|
|
<payload-type id='8' name='PCMA'/>
|
|
<payload-type id='13' name='CN'/>
|
|
</description>
|
|
<transport xmlns='urn:xmpp:tmp:jingle:transports:raw-udp'>
|
|
<candidate ip='208.245.212.67' port='9876' generation='0'/>
|
|
</transport>
|
|
</content>
|
|
</jingle>
|
|
</iq>
|
|
]]></example>
|
|
<p>The initiator then acknowledges the session-accept action.</p>
|
|
<example caption="Initiator acknowledges session-accept"><![CDATA[
|
|
<iq from='romeo@montague.lit/orchard'
|
|
id='accept1'
|
|
to='juliet@capulet.lit/balcony'
|
|
type='result'/>
|
|
]]></example>
|
|
<p>The parties then begin to exchange media. In this case they would exchange audio using the Speex codec at a clockrate of 8000 since that is the highest-priority codec for the responder (as determined by the XML order of the &PAYLOADTYPE; children).</p>
|
|
<p>The parties may continue the session as long as desired.</p>
|
|
<p>Eventually, one of the parties terminates the session.</p>
|
|
<example caption="Receiver terminates the session"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='term1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='set'>
|
|
<jingle xmlns='urn:xmpp:tmp:jingle'
|
|
action='session-terminate'
|
|
initiator='romeo@montague.lit/orchard'
|
|
reasoncode='no-error'
|
|
reasontext='Sorry, gotta go!'
|
|
sid='a73sjjvkla37jfea'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>The other party MUST then acknowledge termination of the session.</p>
|
|
<example caption="Initiator acknowledges termination"><![CDATA[
|
|
<iq from='romeo@montague.lit/orchard'
|
|
id='term1'
|
|
to='juliet@capulet.lit/balcony'
|
|
type='result'/>
|
|
]]></example>
|
|
</section1>
|
|
|
|
<section1 topic='Requirements' anchor='reqs'>
|
|
<p>The protocol defined herein is designed to meet the following requirements:</p>
|
|
<ol>
|
|
<li>Make it possible to manage a wide variety of peer-to-peer sessions (including but not limited to voice and video) within XMPP.</li>
|
|
<li>When a peer-to-peer connection cannot be negotiated, make it possible to fall back to relayed communications.</li>
|
|
<li>Clearly separate the signalling channel (XMPP) from the data channel.</li>
|
|
<li>Clearly separate the application formats (e.g., video) from the transport methods (e.g., RTP).</li>
|
|
<li>Make it possible to add, modify, and remove both application types and transport methods in relation to an existing session.</li>
|
|
<li>Make it relatively easy to implement support for the protocol in standard Jabber/XMPP clients.</li>
|
|
<li>Where communication with non-XMPP entities is needed, push as much complexity as possible onto server-side gateways between the XMPP network and the non-XMPP network.</li>
|
|
</ol>
|
|
<p>This document defines the signalling protocol only. Additional documents specify the following:</p>
|
|
<ul>
|
|
<li><p>Various application formats (audio, video, etc.) and, where possible, mapping of those types to the Session Description Protocol (SDP; see &rfc4566;); examples include <cite>Jingle Audio via RTP</cite> and <cite>Jingle Video via RTP</cite>.</p></li>
|
|
<li><p>Various transport methods; examples include &xep0176; and <cite>Raw UDP Transport</cite>.</p></li>
|
|
<li><p>Procedures for mapping the Jingle signalling protocol to existing signalling standards such as the IETF's Session Initiation Protocol (SIP) and the ITU's H.323 protocol (see &h323;); these documents are forthcoming.</p></li>
|
|
</ul>
|
|
</section1>
|
|
<section1 topic='Terminology' anchor='terms'>
|
|
<section2 topic='Glossary' anchor='terms-glossary'>
|
|
<table caption='Glossary'>
|
|
<tr>
|
|
<th>Term</th>
|
|
<th>Definition</th>
|
|
</tr>
|
|
<tr>
|
|
<td>Application Format</td>
|
|
<td>The data format of the content type being established, which formally declares one purpose of the session (e.g., "voice" or "video"). This is the 'what' of the session (i.e., the bits to be transferred), such as the acceptable codecs when establishing a voice conversation. In Jingle XML syntax the application format is the namespace of the &DESCRIPTION; element.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Component</td>
|
|
<td>A numbered stream of data that needs to be transmitted between the endpoints for a given content type in the context of a given session. It is up to the transport to negotiate the details of each component. Depending on the content type, multiple components may be needed (e.g., two components might be needed, one to transmit an RTP stream and another to transmit RTCP timing information).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Content Type</td>
|
|
<td>A pair formed by the combination of one application format and one transport method.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Session</td>
|
|
<td>One or more content types negotiated between two entities. It is delimited in time by an initiate request and session ending events. During the lifetime of a session, content types can be added or removed. A session consists of at least one content type at a time.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Transport Method</td>
|
|
<td>The method for establishing data stream(s) between entities. Possible transports might include ICE-TCP, Raw UDP, inband data, etc. This is the 'how' of the session. In Jingle XML syntax this is the namespace of the &TRANSPORT; element. The transport method defines how to transfer bits from one host to another. Each transport method must specify whether it is lossy (thus suitable for applications where some packet loss is tolerable) or reliable (thus suitable for applications where packet loss is not tolerable).</td>
|
|
</tr>
|
|
</table>
|
|
</section2>
|
|
<section2 topic='Conventions' anchor='terms-conventions'>
|
|
<p>In diagrams, the following conventions are used:</p>
|
|
<ul>
|
|
<li>Dashed lines (---) represent Jingle stanzas that are sent via the XMPP signalling channel.</li>
|
|
<li>Double-dashed lines (===) represent media packets that are sent via the non-XMPP media channel.</li>
|
|
</ul>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Concepts and Approach' anchor='concepts'>
|
|
<p>Jingle consists of three parts, each with its own syntax and semantics:</p>
|
|
<ol>
|
|
<li>Overall session management</li>
|
|
<li>Application types (the "what")</li>
|
|
<li>Transport methods (the "how")</li>
|
|
</ol>
|
|
<p>This document defines the semantics and syntax for overall session management. It also provides pluggable "slots" for application formats and transport methods, which are specified in separate documents.</p>
|
|
<p>At the most basic level, the process for negotiating a Jingle session is as follows:</p>
|
|
<ol>
|
|
<li>One user (the "initator") sends to another user (the "responder") a session request with at least one content type.</li>
|
|
<li>If the responder wants to proceed, it acknowledges the session initiation request by sending an IQ result.</li>
|
|
<li>Both the initiator and responder start exchanging possible transport candidates as quickly as possible (these are sent in quick succession before further negotiation in order to minimize the time required before media data can flow).</li>
|
|
<li>These candidates are checked for connectivity.</li>
|
|
<li>As soon as the responder finds a candidate over which media can flow, the responder sends to the initiator a "session-accept" action.</li>
|
|
<li>The parties start sending media over the negotiated candidate.</li>
|
|
</ol>
|
|
<p>If the parties later discover a better candidate, they perform a "content-modify" negotiation and then switch to the better candidate. Naturally they can also modify various other parameters related to the session (e.g., adding video to a voice chat).</p>
|
|
<section2 topic='Overall Session Management' anchor='concepts-session'>
|
|
<p>The state machine for overall session management (i.e., the state per Session ID) is as follows:</p>
|
|
<code>
|
|
o
|
|
|
|
|
| session-initiate
|
|
|
|
|
| +-----------------------+
|
|
|/ |
|
|
PENDING o---------------------+ |
|
|
| | content-accept, | |
|
|
| | content-modify, | |
|
|
| | content-remove, | |
|
|
| | session-info, | |
|
|
| | transport-info | |
|
|
| +------------------+ |
|
|
| |
|
|
| session-accept |
|
|
| |
|
|
ACTIVE o---------------------+ |
|
|
| | content-accept, | |
|
|
| | content-add, | |
|
|
| | content-modify, | |
|
|
| | content-remove, | |
|
|
| | session-info, | |
|
|
| | transport-info | |
|
|
| +------------------+ |
|
|
| |
|
|
+-------------------------+
|
|
|
|
|
| session-terminate
|
|
|
|
|
o ENDED
|
|
</code>
|
|
<p>There are three overall session states:</p>
|
|
<ol>
|
|
<li>PENDING</li>
|
|
<li>ACTIVE</li>
|
|
<li>ENDED</li>
|
|
</ol>
|
|
<p>The actions related to management of the overall Jingle session are as follows:</p>
|
|
<table caption='Jingle Actions'>
|
|
<tr>
|
|
<th>Action</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>content-accept</td>
|
|
<td>Accept a content-add or content-modify action received from another party.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>content-add</td>
|
|
<td>Add one or more new content types to the session. The sender MUST specify only the added content-type(s), not the added content-type(s) plus the existing content-type(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definition. This action MUST NOT be sent while the session is in the PENDING state. When a party sends a content-add, it MUST ignore any actions received from the other party until it receives acknowledgement of the content-add. <note>In the event that a session contains two unidirectional streams of the same type because a content-add was issued simultaneously by both parties, it is RECOMMENDED that participants close the duplicate stream in favour of that created by the session initiator, which should be made bidirectional with a 'content-modify' action by the responder.</note></td>
|
|
</tr>
|
|
<tr>
|
|
<td>content-modify</td>
|
|
<td>Change an existing content type. The sender SHOULD specify only the aspects for which a modification is desired (e.g., if a party wishes to change only the profile then it would send an empty <content/> element with a modified value for the 'profile' attribute; if a party wishes to change only the transport, then it would send a <content/> element that contains only a <transport/> child; etc.). Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definition. The recipient MUST NOT reply to a content-modify action with another content-modify action. <note>If both parties send modify messages at the same time, the modify message from the session initiator MUST trump the modify message from the recipient and the initiator SHOULD return an &unexpected; error to the other party.</note></td>
|
|
</tr>
|
|
<tr>
|
|
<td>content-remove</td>
|
|
<td>Remove one or more content types from the session. The sender MUST specify only the removed content-type(s), not the removed content-type(s) plus the remaining content-type(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definition. <note>The recipient SHOULD NOT send a content-accept with the new content type definition after receiving a content-remove.</note> <note>A client MUST NOT return an error upon receipt of a 'content-remove' action for a content type that is received after a 'content-remove' action has been sent but before the action has been acknowledged by the peer.</note> <note>If the content-remove results in zero content types for the session, the entity that receives the content-remove SHOULD send a session-terminate action to the other party (since a session with no content types is void).</note></td>
|
|
</tr>
|
|
<tr>
|
|
<td>session-accept</td>
|
|
<td>Definitively accept a session negotiation (implicitly this action also serves as a content-accept).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>session-info</td>
|
|
<td>Send session-level information / messages, such as (for Jingle audio) a ringing message.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>session-initiate</td>
|
|
<td>Request negotiation of a new Jingle session.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>session-terminate</td>
|
|
<td>End an existing session.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>transport-info</td>
|
|
<td>Exchange transport candidates; it is mainly used in <cite>XEP-0176</cite> but may be used in other transport specifications.</td>
|
|
</tr>
|
|
</table>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Session Flow' anchor='session'>
|
|
<p>This section defines the high-level flow of a Jingle session. More detailed descriptions are provided in the specifications for Jingle application formats and transport methods.</p>
|
|
<section2 topic='Resource Determination' anchor='session-resource'>
|
|
<p>In order to initiate a Jingle session, the initiator must determine which of the responder's XMPP resources is best for the desired application format. Methods for doing so are out of scope for this specification. However, see the <link url='#support'>Determining Support</link> section of this document (and associated specifications) for relevant information.</p>
|
|
</section2>
|
|
<section2 topic='Initiation' anchor='protocol-initiate'>
|
|
<p>Once the initiator has discovered which of the responder's XMPP resources is ideal for the desired application format, it sends a session initiation request to the responder. This request is an IQ-set containing a &JINGLE; element qualified by the 'urn:xmpp:tmp:jingle' namespace &NSNOTE;, where the value of the 'action' attribute is "session-initiate" and where the &JINGLE; element contains one or more &CONTENT; elements. Each &CONTENT; element defines a content type to be transferred during the session, and each &CONTENT; element in turn contains one &DESCRIPTION; child element that specifies a desired application format and one &TRANSPORT; child element that specifies a potential transport method. If either party wishes to propose the use of multiple transport methods for the same application format, it must send multiple &CONTENT; elements.</p>
|
|
<p>Note: The syntax and semantics of the &DESCRIPTION; and &TRANSPORT; elements are out of scope for this specification, since they are defined in related specifications. The syntax and semantics of the &JINGLE; and &CONTENT; elements are specified in this document under <link url='#def'>Formal Definition</link>.</p>
|
|
<p>Note: In order to expedite session establishment, the initiator MAY send transport candidates (e.g., for negotiation of the ICE transport) immediately after sending the "session-initiate" message and before receiving acknowledgement from the responder (i.e., the initiator MUST consider the session to be PENDING even before receiving acknowledgement). Given in-order delivery, the responder should receive such "transport-info" messages after receiving the "session-initiate" message (if not, it is appropriate for the responder to return <unknown-session/> errors since according to its state machine the session does not exist).</p>
|
|
<example caption="Receiver returns unknown-session error"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='jingle1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='error'>
|
|
<error type='cancel'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unknown-session xmlns='urn:xmpp:tmp:jingle-errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
<section2 topic='Receiver Response' anchor='protocol-response'>
|
|
<section3 topic='Acknowledgement' anchor='protocol-response-ack'>
|
|
<p>Unless one of the following errors occurs, the responder SHOULD acknowledge receipt of the initiation request.</p>
|
|
<example caption="Receiver acknowledges session-initiate"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='jingle1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='result'/>
|
|
]]></example>
|
|
<p>However, after acknowledging the session initiation request, the responder may subsequently determine that it cannot proceed with negotiation of the session (e.g., because it does not support any of the offered application formats or transport methods, because a human user is busy or unable to accept the session, because a human user wishes to formally decline the session, etc.). In these cases, the responder SHOULD immediately acknowledge the session initiation request but then terminate the session with an appropriate reasoncode as described in the <link url='#session-terminate'>Termination</link> section of this document.</p>
|
|
<p>If the responder acknowledges receipt of the initation request, both parties must consider the session to be in the PENDING state.</p>
|
|
</section3>
|
|
<section3 topic='Errors' anchor='protocol-response-errors'>
|
|
<p>There are several reasons why the responder might immediately return an error instead of acknowledging receipt of the initiation request:</p>
|
|
<ul>
|
|
<li>The initiator is unknown to the responder and the responder does not communicate with unknown entities.</li>
|
|
<li>The responder does not support Jingle.</li>
|
|
<li>The responder wishes to redirect the request to another address.</li>
|
|
<li>The responder does not have sufficient resources to participate in a session.</li>
|
|
<li>The initiation request was malformed.</li>
|
|
</ul>
|
|
<p>If the initiator is unknown to the responder (e.g., via presence subscription as defined in &rfc3921; or stanza session negotiation as defined in &xep0155;) and the responder has a policy of not communicating via Jingle with unknown entities, it SHOULD return a &unavailable; error.</p>
|
|
<example caption="Initiator is unknown to responder"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='jingle1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='error'>
|
|
<error type='cancel'>
|
|
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the responder does not support Jingle, it MUST return a &unavailable; error.</p>
|
|
<example caption="Receiver does not support Jingle"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='jingle1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='error'>
|
|
<error type='cancel'>
|
|
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the responder wishes to redirect the request to another address, it SHOULD return a &redirect; error.</p>
|
|
<example caption="Receiver redirection"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='jingle1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='error'>
|
|
<error type='cancel'>
|
|
<redirect xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>
|
|
voicemail@capulet.lit
|
|
</redirect>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the responder does not have sufficient resources to participate in a session, it SHOULD return a &constraint; error.</p>
|
|
<example caption="Receiver has insufficent resources"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='jingle1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='error'>
|
|
<error type='wait'>
|
|
<resource-constraint xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the initiation request was malformed, the responder MUST return a &badrequest; error.</p>
|
|
<example caption="Initiation request malformed"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='jingle1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='error'>
|
|
<error type='cancel'>
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
</section3>
|
|
</section2>
|
|
<section2 topic='Negotiation' anchor='session-negotiation'>
|
|
<p>In general, negotiation will be necessary before the parties can agree on an acceptable set of application formats and transport methods. There are many potential parameter combinations, as defined in the relevant specifications for various application formats and transport methods.</p>
|
|
<p>The allowable negotiations (including content-level and transport-level negotiations) are as follows:</p>
|
|
<ul>
|
|
<li>Adding a content type via the content-add action (not allowed in the PENDING state).</li>
|
|
<li>Modifying a content type via the content-modify action.</li>
|
|
<li>Removing a content type via the content-remove action.</li>
|
|
<li>Exchanging transport methods via the transport-info action.</li>
|
|
</ul>
|
|
</section2>
|
|
<section2 topic='Acceptance' anchor='session-acceptance'>
|
|
<p>If (after negotiation of transport methods and application formats as well as checking of transport candidates) the responder determines that it will be able to establish a connection, it sends a definitive acceptance to the initiator.</p>
|
|
<p>Note: In the session-accept stanza, the &JINGLE; element MUST contain one or more <content/> elements, each of which MUST contain one <description/> element and one <transport/> element. The &JINGLE; element SHOULD possess a 'responder' attribute that explicitly specifies the full JID of the responding entity; after sending acknowledgement of the session-accept, the initiator SHOULD send all future commmunications about this Jingle session to the JID provided in the 'responder' attribute and note the new JID in the user interface.</p>
|
|
<p>The initiator then acknowledges the responder's definitive acceptance, after which the parties can exchange media over the negotiated connection.</p>
|
|
<p>If one of the parties cannot find a suitable transport method or candidate, it SHOULD terminate the session as described below.</p>
|
|
</section2>
|
|
<section2 topic='Modifying an Active Session' anchor='session-modify'>
|
|
<p>Once a session is in the ACTIVE state, it may be modified via a content-add, content-modify, content-remove, or transport-info action. Examples of such modifications are shown in the specifications for various application formats and transport methods.</p>
|
|
</section2>
|
|
<section2 topic='Termination' anchor='session-terminate'>
|
|
<p>In order to gracefully end the session (which MAY be done at any point after acknowledging receipt of the initiation request, including immediately thereafter in order to decline the request), either the responder or the initiator MUST send a "terminate" action to the other party.</p>
|
|
<p>The party that terminates the session SHOULD include a 'reasoncode' attribute that specifies why the session is being terminated. Examples follow.</p>
|
|
<p>One reason for terminating the session is that the terminating party is busy; in this case, the recommended reasoncode is "busy".</p>
|
|
<example caption="Terminating the session (busy)"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='term1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='set'>
|
|
<jingle xmlns='urn:xmpp:tmp:jingle'
|
|
action='session-terminate'
|
|
initiator='romeo@montague.lit/orchard'
|
|
reasoncode='busy'
|
|
sid='a73sjjvkla37jfea'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>Another reason for terminating the session is that the terminating party wishes to formally decline the session; in this case, the recommended reasoncode is "decline".</p>
|
|
<example caption="Terminating the session (session formally declined)"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='term1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='set'>
|
|
<jingle xmlns='urn:xmpp:tmp:jingle'
|
|
action='session-terminate'
|
|
initiator='romeo@montague.lit/orchard'
|
|
reasoncode='decline'
|
|
sid='a73sjjvkla37jfea'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>Another reason for terminating the session is that the terminating party already has an existing session with the other party and wishes to use that session rather than initiate a new session; in this case, the recommended reasoncode is "alternative-session" and the terminating party should include the session ID of the atlernative session in the 'reasontext' attribute.</p>
|
|
<example caption="Terminating the session (existing session)"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='term1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='set'>
|
|
<jingle xmlns='urn:xmpp:tmp:jingle'
|
|
action='session-terminate'
|
|
initiator='romeo@montague.lit/orchard'
|
|
reasoncode='alternative-session'
|
|
reasontext='b84tkkwlmb48kgfb'/>
|
|
sid='a73sjjvkla37jfea'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>Another reason for terminating the session is that the terminating party does not support any of the offered application formats; in this case, the recommended reasoncode is "unsupported-applications".</p>
|
|
<example caption="Terminating the session (no offered application format supported)"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='term1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='set'>
|
|
<jingle xmlns='urn:xmpp:tmp:jingle'
|
|
action='session-terminate'
|
|
initiator='romeo@montague.lit/orchard'
|
|
reasoncode='unsupported-applications'
|
|
sid='a73sjjvkla37jfea'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>Another reason for terminating the session is that the terminating party does not support any of the offered transport methods; in this case, the recommended reasoncode is "unsupported-transports".</p>
|
|
<example caption="Terminating the session (no offered transport method supported)"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='term1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='set'>
|
|
<jingle xmlns='urn:xmpp:tmp:jingle'
|
|
action='session-terminate'
|
|
initiator='romeo@montague.lit/orchard'
|
|
reasoncode='unsupported-transports'
|
|
sid='a73sjjvkla37jfea'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>Upon receiving an action of "session-terminate", the other party MUST then acknowledge termination of the session:</p>
|
|
<example caption="Acknowledging termination"><![CDATA[
|
|
<iq from='romeo@montague.lit/orchard'
|
|
id='term1'
|
|
to='juliet@capulet.lit/balcony'
|
|
type='result'/>
|
|
]]></example>
|
|
<p>Note: As soon as an entity sends a "session-terminate" action, it MUST consider the session to be in the ENDED state (even before receiving acknowledgement from the other party). If the terminating entity receives additional Jingle-related IQ-sets from the other party after sending the "session-terminate" action, it MUST reply with an <unknown-session/> error.</p>
|
|
<p>Unfortunately, not all sessions end gracefully. In applications of Jingle that also involve the exchange of presence information, receipt of &UNAVAILABLE; from the other party MAY be considered a session-ending event. However, in this case there is nothing for the party to acknowledge.</p>
|
|
</section2>
|
|
<section2 topic='Informational Messages' anchor='session-info'>
|
|
<p>At any point after initiation of a Jingle session, either entity MAY send an informational message to the other party, for example to change a transport method, inform the other party that a device is ringing or that a scheduled event has occurred or will occur, etc.</p>
|
|
<p>An informational message MUST be an IQ-set containing a &JINGLE; element whose 'action' attribute is set to a value of "session-info" or "transport-info"; the &JINGLE; element MUST further contain a payload child element (specific to the session or to a transport method) that specifies the information being communicated. If the party that receives an informational message does not understand the payload, it MUST return a &feature; error with a Jingle-specific error condition of <unsupported-info/>.</p>
|
|
<example caption="Receiver returns unsupported-info error"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='info1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='error'>
|
|
<error type='modify'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<unsupported-info xmlns='urn:xmpp:tmp:jingle-errors'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If either party receives an empty "session-info" message for an active session, it MUST send an empty IQ result; this way, an empty "session-info" message may be used as a "ping" to determine session vitality.</p>
|
|
<p>Informational messages are specific to a particular application type or transport method and therefore are described in specifications other than this one.</p>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Formal Definition' anchor='def'>
|
|
<section2 topic='Jingle Element' anchor='def-jingle'>
|
|
<p>The &JINGLE; element MAY be empty or contain one or more &CONTENT; elements (for which see <link url='#def-content'>Content Element</link>).</p>
|
|
<p>The attributes of the &JINGLE; element are as follows.</p>
|
|
<table caption='Attributes of Jingle Element'>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Definition</th>
|
|
<th>Inclusion</th>
|
|
</tr>
|
|
<tr>
|
|
<td>action</td>
|
|
<td>A Jingle action as listed in this document (e.g., "session-terminate").</td>
|
|
<td>REQUIRED</td>
|
|
</tr>
|
|
<tr>
|
|
<td>initiator</td>
|
|
<td>The full JID of the entity that has initiated the session flow (which may be different from the 'from' address on the IQ-set).</td>
|
|
<td>REQUIRED</td>
|
|
</tr>
|
|
<tr>
|
|
<td>reasoncode</td>
|
|
<td>A machine-readable purpose for the action being sent (e.g., "connectivity-error" for a session-terminate action).</td>
|
|
<td>OPTIONAL</td>
|
|
</tr>
|
|
<tr>
|
|
<td>reasontext</td>
|
|
<td>A human-readable purpose for the action being sent (e.g., "Sorry, gotta go!" for a session-terminate action).</td>
|
|
<td>OPTIONAL</td>
|
|
</tr>
|
|
<tr>
|
|
<td>responder</td>
|
|
<td>The full JID of the entity that has replied to the initiation, which may be different from the 'to' address on the IQ-set.</td>
|
|
<td>RECOMMENDED</td>
|
|
</tr>
|
|
<tr>
|
|
<td>sid</td>
|
|
<td>A random session identifier generated by the initiator, which effectively maps to the local-part of a SIP "Call-ID" parameter; this SHOULD match the XML Nmtoken production <note>See <<link url='http://www.w3.org/TR/2000/WD-xml-2e-20000814#NT-Nmtoken'>http://www.w3.org/TR/2000/WD-xml-2e-20000814#NT-Nmtoken</link>></note> so that XML character escaping is not needed for characters such as '&'.</td>
|
|
<td>REQUIRED</td>
|
|
</tr>
|
|
</table>
|
|
</section2>
|
|
<section2 topic='Content Element' anchor='def-content'>
|
|
<p>The attributes of the &CONTENT; element are as follows.</p>
|
|
<table caption='Attributes of Content Element'>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Definition</th>
|
|
<th>Inclusion</th>
|
|
</tr>
|
|
<tr>
|
|
<td>creator</td>
|
|
<td>Which party originally generated the content type (used to prevent race conditions regarding modifications).</td>
|
|
<td>REQUIRED</td>
|
|
</tr>
|
|
<tr>
|
|
<td>name</td>
|
|
<td>A unique name or identifier for the content type (this identifier is opaque and does not have semantic meaning).</td>
|
|
<td>REQUIRED</td>
|
|
</tr>
|
|
<tr>
|
|
<td>profile</td>
|
|
<td>The profile in use (e.g., "RTP/AVP" in the context of the Real-time Transport Protocol).</td>
|
|
<td>RECOMMENDED</td>
|
|
</tr>
|
|
<tr>
|
|
<td>senders</td>
|
|
<td>Which parties in the session will be generating content; the allowable values are "initiator", "responder", or "both" (where "both" is the default).</td>
|
|
<td>RECOMMENDED</td>
|
|
</tr>
|
|
</table>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Error Handling' anchor='errors'>
|
|
<p>The Jingle-specific error conditions are as follows. These condition elements are qualified by the 'urn:xmpp:tmp:jingle-errors' namespace &NSNOTE;.</p>
|
|
<table caption='Error Conditions'>
|
|
<tr>
|
|
<th>Jingle Condition</th>
|
|
<th>XMPP Condition</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><out-of-order/></td>
|
|
<td>&unexpected;</td>
|
|
<td>The request cannot occur at this point in the state machine (e.g., session-initiate after session-accept).</td>
|
|
</tr>
|
|
<tr>
|
|
<td><unknown-session/></td>
|
|
<td>&badrequest;</td>
|
|
<td>The 'sid' attribute specifies a session that is unknown to the recipient (e.g., no longer live according to the recipient's state machine because the recipient previously terminated the session).</td>
|
|
</tr>
|
|
<tr>
|
|
<td><unsupported-info/></td>
|
|
<td>&feature;</td>
|
|
<td>The recipient does not support the informational payload of a session-info message.</td>
|
|
</tr>
|
|
</table>
|
|
</section1>
|
|
|
|
<section1 topic='Determining Support' anchor='support'>
|
|
<p>If an entity supports Jingle, it MUST advertise that fact by returning a feature of "urn:xmpp:tmp:jingle" &NSNOTE; in response to a &xep0030; information request. The response MUST also include features for the application formats and transport methods supported by the responding entity, as described in the relevant specifications.</p>
|
|
<example caption="Service Discovery Information Request"><![CDATA[
|
|
<iq from='romeo@montague.lit/orchard'
|
|
id='disco1'
|
|
to='juliet@capulet.lit/balcony'
|
|
type='get'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Service Discovery Information Response"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='disco1'
|
|
to='romeo@montague.lit/orchard'
|
|
type='result'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
...
|
|
<feature var='urn:xmpp:tmp:jingle'/>
|
|
...
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>Naturally, support MAY also be determined via the dynamic, presence-based profile of Service Discovery defined in <cite>XEP-0115</cite>.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Conformance by Using Protocols' anchor='conformance'>
|
|
<section2 topic='Application Formats' anchor='conformance-apps'>
|
|
<p>A document that specifies a Jingle application format (e.g., audio via RTP) MUST define:</p>
|
|
<ol>
|
|
<li>How successful application format negotiation occurs for encapsulation into Jingle.</li>
|
|
<li>A &DESCRIPTION; element and associated semantics for representing the application format.</li>
|
|
<li>If and how the application format can be mapped to the Session Description Protocol, including the appropriate SDP media type (see Section 8.2.1 of <cite>RFC 4566</cite>).</li>
|
|
<li>Whether the media for the application format should be sent over a reliable transport method or a lossy transport method (or, if both, which is preferred).</li>
|
|
<li>Exactly how the media is to be sent and received over a reliable or lossy transport.</li>
|
|
</ol>
|
|
</section2>
|
|
<section2 topic='Transport Methods' anchor='conformance-transports'>
|
|
<p>A document that specifies a Jingle transport method (e.g., Raw UDP) MUST define:</p>
|
|
<ol>
|
|
<li>How successful transport negotiation occurs for encapsulation into Jingle.</li>
|
|
<li>A &TRANSPORT; element and associated semantics for representing the transport method.</li>
|
|
<li>Whether the transport is reliable or lossy.</li>
|
|
<li>If and how the transport handles components as defined herein (e.g., for the Real Time Control Protocol).</li>
|
|
</ol>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Security Considerations' anchor='security'>
|
|
<section2 topic='Denial of Service' anchor='security-dos'>
|
|
<p>Jingle sessions may be resource-intensive. Therefore, it is possible to launch a denial-of-service attack against an entity by burdening it with too many Jingle sessions. Care must be taken to accept sessions only from known entities and only if the entity's device is able to process such sessions.</p>
|
|
</section2>
|
|
<section2 topic='Communication Through Gateways' anchor='security-gateways'>
|
|
<p>Jingle communications may be enabled through gateways to non-XMPP networks, whose security characteristics may be quite different from those of XMPP networks. (For example, on some SIP networks authentication is optional and "from" addresses can be easily forged.) Care must be taken in communicating through such gateways.</p>
|
|
</section2>
|
|
<section2 topic='Information Exposure' anchor='security-info'>
|
|
<p>Mere negotiation of a Jingle session may expose sensitive information about the parties (e.g., IP addresses). Care must be taken in communicating such information, and end-to-end encryption should be used if the parties do not trust the intermediate servers or gateways.</p>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='IANA Considerations' anchor='iana'>
|
|
<p>This document requires no interaction with &IANA;.</p>
|
|
</section1>
|
|
|
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
|
<section2 topic='Protocol Namespaces' anchor='ns'>
|
|
<p>Until this specification advances to a status of Draft, its associated namespaces shall be:</p>
|
|
<ul>
|
|
<li>urn:xmpp:tmp:jingle</li>
|
|
<li>urn:xmpp:tmp:jingle-errors</li>
|
|
</ul>
|
|
<p>Upon advancement of this specification, the ®ISTRAR; shall issue permanent namespaces in accordance with the process defined in Section 4 of &xep0053;.</p>
|
|
<p>The following namespaces are requested, and are thought to be unique per the XMPP Registrar's requirements:</p>
|
|
<ul>
|
|
<li>urn:xmpp:jingle</li>
|
|
<li>urn:xmpp:jingle:errors</li>
|
|
</ul>
|
|
</section2>
|
|
<section2 topic='Jingle Application Formats Registry' anchor='registrar-apps'>
|
|
<p>The XMPP Registrar shall maintain a registry of Jingle application formats. All application format registrations shall be defined in separate specifications (not in this document). Application types defined within the XEP series MUST be registered with the XMPP Registrar, resulting in protocol URNs of the form "urn:xmpp:jingle:app:name" (where "name" is the registered name of the application format).</p>
|
|
®PROCESS;
|
|
<code><![CDATA[
|
|
<application>
|
|
<name>the name of the application format</name>
|
|
<desc>a natural-language summary of the application format</desc>
|
|
<transport>
|
|
whether the media can be sent over a "reliable" transport, a "lossy" transport, or "both"
|
|
</transport>
|
|
<doc>the document in which this application format is specified</doc>
|
|
</application>
|
|
]]></code>
|
|
</section2>
|
|
<section2 topic='Jingle Transport Methods Registry' anchor='registrar-transports'>
|
|
<p>The XMPP Registrar shall maintain a registry of Jingle transport methods. All transport method registrations shall be defined in separate specifications (not in this document). Transport methods defined within the XEP series MUST be registered with the XMPP Registrar, resulting in protocol URNs of the form "urn:xmpp:jingle:transport:name" (where "name" is the registered name of the transport method).</p>
|
|
®PROCESS;
|
|
<code><![CDATA[
|
|
<transport>
|
|
<name>the name of the transport method</name>
|
|
<desc>a natural-language summary of the transport method</desc>
|
|
<type>whether the transport method can be "reliable", "lossy", or "both"</type>
|
|
<doc>the document in which this transport method is specified</doc>
|
|
</transport>
|
|
]]></code>
|
|
</section2>
|
|
<section2 topic='Jingle Reason Codes Registry' anchor='registrar-reasoncodes'>
|
|
<section3 topic='Process' anchor='registrar-reasoncodes-process'>
|
|
<p>The XMPP Registrar shall maintain a registry of reason codes related to Jingle actions.</p>
|
|
®PROCESS;
|
|
<code><![CDATA[
|
|
<reason>
|
|
<code>the value of the 'reasoncode' attribute</name>
|
|
<desc>a natural-language summary of the reason code</desc>
|
|
<doc>the document in which this reason code is specified</doc>
|
|
</reason>
|
|
]]></code>
|
|
</section3>
|
|
<section3 topic='Initial Registration' anchor='registrar-reasoncodes-reg'>
|
|
<p>The following submission registers reasoncodes currently in use. Refer to the registry itself for a complete and current list of reasoncodes.</p>
|
|
<code><![CDATA[
|
|
<reason>
|
|
<code>alternative-session</code>
|
|
<desc>
|
|
the party prefers to use an existing session with the peer
|
|
rather than initiate a new session; the session ID of the
|
|
alternative session should be provided in the reasontext
|
|
attribute
|
|
</desc>
|
|
<doc>XEP-0166</doc>
|
|
</reason>
|
|
|
|
<reason>
|
|
<code>busy</code>
|
|
<desc>the party is busy</desc>
|
|
<doc>XEP-0166</doc>
|
|
</reason>
|
|
|
|
<reason>
|
|
<code>decline</code>
|
|
<desc>the party wishes to formally decline the session</desc>
|
|
<doc>XEP-0166</doc>
|
|
</reason>
|
|
|
|
<reason>
|
|
<code>connectivity-error</code>
|
|
<desc>the action is related to connectivity problems</desc>
|
|
<doc>XEP-0166</doc>
|
|
</reason>
|
|
|
|
<reason>
|
|
<code>general-error</code>
|
|
<desc>the action is related to a non-specific application error</desc>
|
|
<doc>XEP-0166</doc>
|
|
</reason>
|
|
|
|
<reason>
|
|
<code>media-error</code>
|
|
<desc>the action is related to media processing problems</desc>
|
|
<doc>XEP-0166</doc>
|
|
</reason>
|
|
|
|
<reason>
|
|
<code>no-error</code>
|
|
<desc>the action is generated during the normal course of state management</desc>
|
|
<doc>XEP-0166</doc>
|
|
</reason>
|
|
|
|
<reason>
|
|
<code>unsupported-applications</code>
|
|
<desc>the party supports none of the offered application formats</desc>
|
|
<doc>XEP-0166</doc>
|
|
</reason>
|
|
|
|
<reason>
|
|
<code>unsupported-transports</code>
|
|
<desc>the party supports none of the offered transport methods</desc>
|
|
<doc>XEP-0166</doc>
|
|
</reason>
|
|
]]></code>
|
|
</section3>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='XML Schemas' anchor='schema'>
|
|
<section2 topic='Jingle' anchor='schema-jingle'>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='urn:xmpp:tmp:jingle'
|
|
xmlns='urn:xmpp:tmp:jingle'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:element name='jingle'>
|
|
<xs:complexType>
|
|
<xs:sequence minOccurs='1' maxOccurs='unlimited'>
|
|
<xs:element ref='content'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='action' use='required'>
|
|
<xs:simpleType>
|
|
<xs:restriction base='xs:NCName'>
|
|
<xs:enumeration value='content-accept'/>
|
|
<xs:enumeration value='content-add'/>
|
|
<xs:enumeration value='content-modify'/>
|
|
<xs:enumeration value='content-remove'/>
|
|
<xs:enumeration value='session-accept'/>
|
|
<xs:enumeration value='session-info'/>
|
|
<xs:enumeration value='session-initiate'/>
|
|
<xs:enumeration value='session-terminate'/>
|
|
<xs:enumeration value='transport-info'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:attribute>
|
|
<xs:attribute name='initiator' type='xs:string' use='required'/>
|
|
<xs:attribute name='reasoncode' type='xs:string' use='optional'/>
|
|
<xs:attribute name='reasontext' type='xs:string' use='optional'/>
|
|
<xs:attribute name='responder' type='xs:string' use='optional'/>
|
|
<xs:attribute name='sid' type='xs:NMTOKEN' use='required'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='content'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='creator' use='required'>
|
|
<xs:simpleType>
|
|
<xs:restriction base='xs:NCName'>
|
|
<xs:enumeration value='initiator'>
|
|
<xs:enumeration value='responder'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:attribute>
|
|
<xs:attribute name='name' use='required' type='xs:string'/>
|
|
<xs:attribute name='profile' use='optional' type='xs:string'/>
|
|
<xs:attribute name='senders' use='optional' default='both'>
|
|
<xs:simpleType>
|
|
<xs:restriction base='xs:NCName'>
|
|
<xs:enumeration value='both'>
|
|
<xs:enumeration value='initiator'>
|
|
<xs:enumeration value='responder'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:attribute>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section2>
|
|
<section2 topic='Jingle Errors' anchor='schema-errors'>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='urn:xmpp:tmp:jingle-errors'
|
|
xmlns='urn:xmpp:tmp:jingle-errors'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:element name='out-of-order' type='empty'/>
|
|
<xs:element name='unknown-session' type='empty'/>
|
|
<xs:element name='unsupported-info' type='empty'/>
|
|
|
|
<xs:simpleType name='empty'>
|
|
<xs:restriction base='xs:string'>
|
|
<xs:enumeration value=''/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='History' anchor='history'>
|
|
<p>Until Jingle was developed, there existed no widely-adopted standard for initiating and managing peer-to-peer interactions between XMPP entities. Although several large service providers and Jabber client teams had written and implemented their own proprietary XMPP extensions for peer-to-peer signalling (usually only for voice), those technologies were not open and did not always take into account requirements to interoperate with SIP-based technologies. The only existing open protocol was &xep0111;, which made it possible to initiate and manage peer-to-peer sessions, but which did not provide enough of the key signalling semantics to be easily implemented in Jabber/XMPP clients. <note>It is true that TINS made it relatively easy to implement an XMPP-to-SIP gateway; however, in line with the long-time Jabber philosophy of "simple clients, complex servers", it would be better to force complexity onto the server-side gateway and to keep the client as simple as possible.</note></p>
|
|
<p>The result was an unfortunate fragmentation within the XMPP community regarding signalling protocols. Essentially, there were two possible approaches to solving the problem:</p>
|
|
<ol>
|
|
<li>Recommend that all client developers implement a dual-stack (XMPP + SIP) solution.</li>
|
|
<li>Define a full-featured protocol for XMPP signalling.</li>
|
|
</ol>
|
|
<p>Implementation experience indicates that a dual-stack approach may not be feasible on all the computing platforms for which Jabber clients have been written, or even desirable on platforms where it is feasible. <note>For example, one large ISP decided to switch to a pure XMPP approach after having implemented and deployed a dual-stack client for several years.</note> Therefore, it seemed reasonable to define an XMPP signalling protocol that could provide the necessary session management semantics while also making it relatively straightforward to interoperate with existing Internet standards.</p>
|
|
<p>As a result of feedback received on <cite>XEP-0111</cite>, the original authors of this document (Joe Hildebrand and Peter Saint-Andre) began to define such a signalling protocol, code-named Jingle. Upon communication with members of the Google Talk team, <note>Google Talk is a messaging and voice chat service and client provided by Google; see <<link url='http://www.google.com/talk/'>http://www.google.com/talk/</link>>.</note> it was discovered that the emerging Jingle approach was conceptually (and even syntactically) quite similar to the signalling protocol used in the Google Talk application. Therefore, in the interest of interoperability and adoption, we decided to harmonize the two approaches. The signalling protocol specified herein is, therefore, substantially equivalent to the original Google Talk protocol, with several adjustments based on feedback received from implementors as well as for publication by the XMPP Standards Foundation.</p>
|
|
</section1>
|
|
<section1 topic='Acknowledgements' anchor='ack'>
|
|
<p>The authors would like to thank Rohan Mahy for his valuable input on early versions of this document. Thiago Camargo, Dafydd Harries, Antti Ijäs, Lauri Kaila, Justin Karneges, Jussi Laako, Anthony Minessale, Matt O'Gorman, Rob Taylor, Matt Tucker, Saku Vainio, Brian West, and others have also provided helpful input. Thanks also to those who have commented on the &SSIG; and (earlier) Jingle <note>Before this specification was formally accepted by the XMPP Standards Foundation as an XMPP Extension Protocol, it was discussed on the semi-private <jingle@jabber.org> mailing list; although that list is no longer used since the standards@xmpp.org list is the preferred discussion venue, for historical purposes it is publicly archived at <<link url='http://mail.jabber.org/pipermail/jingle/'>http://mail.jabber.org/pipermail/jingle/</link>>.</note> mailing lists.</p>
|
|
</section1>
|
|
</xep>
|