moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-21 16:55:07 -05:00
Code Issues Releases Wiki Activity

0.20

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1382 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2007-11-15 23:58:17 +00:00
parent 5524cc1dfe
commit a113a1486a
1 changed files with 45 additions and 755 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

800
xep-0166.xml
View File

@ -26,6 +26,12 @@
&robmcqueen; &robmcqueen;
&seanegan; &seanegan;
&hildjj; &hildjj;
<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> <revision>
<version>0.19</version> <version>0.19</version>
<date>2007-11-13</date> <date>2007-11-13</date>
@ -229,7 +235,7 @@ Romeo Juliet
|---------------------------->| |---------------------------->|
| | | |
]]></code> ]]></code>
<p>Naturally, more complex scenarios are probably; see the <link url='#scenarios'>Scenarios</link> section of this document for details.</p> <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 happens as follows. The example is that of a voice chat (see <cite>XEP-0167</cite>) initiated by Romeo, where the transport is &xep0177;.</p> <p>The simplest flow might happens 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[ <example caption="Initiator sends session-initiate"><![CDATA[
<iq from='romeo@montague.lit/orchard' to='juliet@capulet.lit/balcony' id='jingle1' type='set'> <iq from='romeo@montague.lit/orchard' to='juliet@capulet.lit/balcony' id='jingle1' type='set'>
@ -312,14 +318,14 @@ Romeo Juliet
<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>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>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 signalling channel (XMPP) from the data channel.</li>
<li>Clearly separate the application types (e.g., video) from the transport methods (e.g., RTP).</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 media types and transport methods in relation to an existing session.</li> <li>Make it possible to add, modify, and remove both media 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>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> <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> </ol>
<p>This document defines the signalling protocol only. Additional documents specify the following:</p> <p>This document defines the signalling protocol only. Additional documents specify the following:</p>
<ul> <ul>
<li><p>Various application types (audio, video, etc.) and, where possible, mapping 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 application formats (audio, video, etc.) and, where possible, mapping 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>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> <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> </ul>
@ -332,25 +338,25 @@ Romeo Juliet
<th>Definition</th> <th>Definition</th>
</tr> </tr>
<tr> <tr>
<td>Session</td> <td>Application Format</td>
<td>A number of pairs of negotiated application types and transport methods connecting two entities. It is delimited in time by an initiate request and session ending events. During the lifetime of a session, pairs of application types and transport methods can be added or removed. A session consists of at least one content type at a time.</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>
<tr> <tr>
<td>Content Type</td> <td>Content Type</td>
<td>The combination of one application type and one transport method.</td> <td>A pair formed by the combination of one application format and one transport method.</td>
</tr> </tr>
<tr> <tr>
<td>Application Type</td> <td>Session</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 type is the namespace of the &DESCRIPTION; element.</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>
<tr> <tr>
<td>Transport Method</td> <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> <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> </tr>
<tr>
<td>Component</td>
<td>A component is a numbered stream of data which 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>
</table> </table>
</section2> </section2>
<section2 topic='Conventions' anchor='terms-conventions'> <section2 topic='Conventions' anchor='terms-conventions'>
@ -368,7 +374,7 @@ Romeo Juliet
<li>Application types (the "what")</li> <li>Application types (the "what")</li>
<li>Transport methods (the "how")</li> <li>Transport methods (the "how")</li>
</ol> </ol>
<p>This document defines the semantics and syntax for overall session management. It also provides pluggable "slots" for application types and transport methods, which are specified in separate documents; however, for the sake of completeness, this document also includes examples for all actions related to application types and transport methods.</p> <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; however, for the sake of completeness, this document also includes examples for all actions related to application formats and transport methods.</p>
<p>At the most basic level, the process for negotiating a Jingle session is as follows:</p> <p>At the most basic level, the process for negotiating a Jingle session is as follows:</p>
<ol> <ol>
<li>One user (the "initator") sends to another user (the "receiver") a session request with at least one content type.</li> <li>One user (the "initator") sends to another user (the "receiver") a session request with at least one content type.</li>
@ -465,18 +471,18 @@ PENDING o---------------------+ |
</section2> </section2>
</section1> </section1>
<section1 topic='Session Flow' anchor='session'> <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 <link url='#scenarios'>Scenarios</link> section of this document.</p> <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'> <section2 topic='Resource Determination' anchor='session-resource'>
<p>In order to initiate a Jingle session, the initiator must determine which of the receiver's XMPP resources is best for the desired application type. There are several possible scenarios:</p> <p>In order to initiate a Jingle session, the initiator must determine which of the receiver's XMPP resources is best for the desired application format. There are several possible scenarios:</p>
<ol> <ol>
<li><p>If the intended responder shares presence with the initiator (see &xmppim;) and has only one available resource, the initiator SHOULD attempt to negotiate a Jingle session with that resource unless the initiator knows via &xep0030; or &xep0115; that the resource does not support Jingle and the desired application type. <note>Naturally, instead of sending service discovery requests to every contact in a user's roster, it is more efficient to use <cite>Entity Capabilities</cite>, whereby support for Jingle and various Jingle application types and transport methods is determined for a client version in general (rather than on a per-JID basis) and then cached. Refer to <cite>XEP-0115</cite> for details.</note></p></li> <li><p>If the intended responder shares presence with the initiator (see &xmppim;) and has only one available resource, the initiator SHOULD attempt to negotiate a Jingle session with that resource unless the initiator knows via &xep0030; or &xep0115; that the resource does not support Jingle and the desired application format. <note>Naturally, instead of sending service discovery requests to every contact in a user's roster, it is more efficient to use <cite>Entity Capabilities</cite>, whereby support for Jingle and various Jingle application formats and transport methods is determined for a client version in general (rather than on a per-JID basis) and then cached. Refer to <cite>XEP-0115</cite> for details.</note></p></li>
<li><p>If the intended responder shares presence with the initiator and has more than one available resource but only one of the resources supports Jingle and the desired application type, the initiator SHOULD initiate the Jingle session with that resource.</p></li> <li><p>If the intended responder shares presence with the initiator and has more than one available resource but only one of the resources supports Jingle and the desired application format, the initiator SHOULD initiate the Jingle session with that resource.</p></li>
<li><p>If the intended responder shares presence with the initiator and has more than one available resource but more than one of the resources supports Jingle and the desired application type, the initiator SHOULD use &xep0168; in order to determine which is the best resource with which to initiate the desired Jingle session.</p></li> <li><p>If the intended responder shares presence with the initiator and has more than one available resource but more than one of the resources supports Jingle and the desired application format, the initiator SHOULD use &xep0168; in order to determine which is the best resource with which to initiate the desired Jingle session.</p></li>
<li><p>If the intended responder does not share presence with the initiator, the initiator SHOULD first send a &xep0155; request to the responder in order to initiate the exchange of XMPP stanzas. The request SHOULD include a RAP routing hint as specified in <cite>XEP-0168</cite> and the &MESSAGE; stanza containing the request SHOULD be of type "headline" so that (typically) it is not stored offline for later delivery. The stanza session negotiation SHOULD result in temporary sharing of presence between the parties via the "presence" field as described in <cite>XEP-0155</cite>.</p></li> <li><p>If the intended responder does not share presence with the initiator, the initiator SHOULD first send a &xep0155; request to the responder in order to initiate the exchange of XMPP stanzas. The request SHOULD include a RAP routing hint as specified in <cite>XEP-0168</cite> and the &MESSAGE; stanza containing the request SHOULD be of type "headline" so that (typically) it is not stored offline for later delivery. The stanza session negotiation SHOULD result in temporary sharing of presence between the parties via the "presence" field as described in <cite>XEP-0155</cite>.</p></li>
</ol> </ol>
</section2> </section2>
<section2 topic='Initiation' anchor='protocol-initiate'> <section2 topic='Initiation' anchor='protocol-initiate'>
<p>Once the initiator has discovered which of the receiver's XMPP resources is ideal for the desired application type, it sends a session initiation request to the receiver. This request is an IQ-set containing a &JINGLE; element qualified by the 'http://www.xmpp.org/extensions/xep-0166.html#ns' 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 type 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 type, it must send multiple &CONTENT; elements.</p> <p>Once the initiator has discovered which of the receiver's XMPP resources is ideal for the desired application format, it sends a session initiation request to the receiver. This request is an IQ-set containing a &JINGLE; element qualified by the 'http://www.xmpp.org/extensions/xep-0166.html#ns' 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: 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 receiver (i.e., the initiator MUST consider the session to be live even before receiving acknowledgement). Given in-order delivery, the receiver should receive such "transport-info" messages after receiving the "session-initiate" message (if not, it is appropriate for the receiver to return &lt;unknown-session/&gt; errors since it according to its state machine the session does not exist).</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 receiver (i.e., the initiator MUST consider the session to be live even before receiving acknowledgement). Given in-order delivery, the receiver should receive such "transport-info" messages after receiving the "session-initiate" message (if not, it is appropriate for the receiver to return &lt;unknown-session/&gt; errors since it according to its state machine the session does not exist).</p>
@ -490,7 +496,7 @@ PENDING o---------------------+ |
<li>The receiver does not support Jingle.</li> <li>The receiver does not support Jingle.</li>
<li>The receiver wishes to redirect the request to another address.</li> <li>The receiver wishes to redirect the request to another address.</li>
<li>The receiver is busy and therefore cannot participate in a session.</li> <li>The receiver is busy and therefore cannot participate in a session.</li>
<li>The receiver does not support any of the specified application types.</li> <li>The receiver does not support any of the specified application formats.</li>
<li>The receiver does not support any of the specified transport methods.</li> <li>The receiver does not support any of the specified transport methods.</li>
<li>The initiation request was malformed.</li> <li>The initiation request was malformed.</li>
</ul> </ul>
@ -527,7 +533,7 @@ PENDING o---------------------+ |
</error> </error>
</iq> </iq>
]]></example> ]]></example>
<p>If the receiver does not support any of the specified application types, it MUST return a &feature; error with a Jingle-specific error condition of &lt;unsupported-content/&gt;.</p> <p>If the receiver does not support any of the specified application formats, it MUST return a &feature; error with a Jingle-specific error condition of &lt;unsupported-content/&gt;.</p>
<example caption="Receiver Does Not Support Any Content Description Formats"><![CDATA[ <example caption="Receiver Does Not Support Any Content Description Formats"><![CDATA[
<iq type='error' from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='jingle1'> <iq type='error' from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='jingle1'>
<error type='cancel'> <error type='cancel'>
@ -558,7 +564,7 @@ PENDING o---------------------+ |
<p>In order to formally decline the session initiation request, the receiver MUST acknowledge receipt of the session initiation request, then terminate the session as described under <link url='#session-terminate'>Termination</link>.</p> <p>In order to formally decline the session initiation request, the receiver MUST acknowledge receipt of the session initiation request, then terminate the session as described under <link url='#session-terminate'>Termination</link>.</p>
</section2> </section2>
<section2 topic='Negotiation' anchor='session-negotiation'> <section2 topic='Negotiation' anchor='session-negotiation'>
<p>In general, negotiation will be necessary before the parties can agree on an acceptable set of content types, application types, and transport methods. The potential combinations of parameters to be negotiated are many, and not all are shown herein. Some are defined in the relevant specifications for various application types and transport methods, and illustrated in the <link url='#scenarios'>Scenarios</link> section of this document.</p> <p>In general, negotiation will be necessary before the parties can agree on an acceptable set of content types, 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> <p>The allowable negotiations (including content-level and transport-level negotiations) are as follows:</p>
<ul> <ul>
<li>Adding a content type via the content-add action (not allowed in the PENDING state).</li> <li>Adding a content type via the content-add action (not allowed in the PENDING state).</li>
@ -568,13 +574,13 @@ PENDING o---------------------+ |
</ul> </ul>
</section2> </section2>
<section2 topic='Acceptance' anchor='session-acceptance'> <section2 topic='Acceptance' anchor='session-acceptance'>
<p>If (after negotiation of transport methods and application types as well as checking of transport candidates) the receiver determines that it will be able to establish a connection, it sends a definitive acceptance to the initiator.</p> <p>If (after negotiation of transport methods and application formats as well as checking of transport candidates) the receiver determines that it will be able to establish a connection, it sends a definitive acceptance to the initiator.</p>
<p>Note: In the accept stanza, the &JINGLE; element MUST contain one or more &lt;content/&gt; elements, each of which MUST contain one &lt;description/&gt; element and one &lt;transport/&gt; element. The &JINGLE; element SHOULD possess a 'responder' attribute that explicitly specifies the full JID of the responding entity, and the initiator SHOULD send all future commmunications about this Jingle session to the JID provided in the 'responder' attribute.</p> <p>Note: In the accept stanza, the &JINGLE; element MUST contain one or more &lt;content/&gt; elements, each of which MUST contain one &lt;description/&gt; element and one &lt;transport/&gt; element. The &JINGLE; element SHOULD possess a 'responder' attribute that explicitly specifies the full JID of the responding entity, and the initiator SHOULD send all future commmunications about this Jingle session to the JID provided in the 'responder' attribute.</p>
<p>The initiator then acknowledges the receiver's definitive acceptance, after which the parties can exchange media over the negotiated connection.</p> <p>The initiator then acknowledges the receiver'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> <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>
<section2 topic='Modifying an Active Session' anchor='session-modify'> <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, or content-remove action. Examples of such modifications are shown in the <link url='#scenarios'>Scenarios</link> section of this document.</p> <p>Once a session is in the ACTIVE state, it may be modified via a content-add, content-modify, or content-remove action. Examples of such modifications are shown in the specifications for various application formats and transport methods.</p>
</section2> </section2>
<section2 topic='Termination' anchor='session-terminate'> <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 receiver or the initiator MUST send a "terminate" action to the other party.</p> <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 receiver or the initiator MUST send a "terminate" action to the other party.</p>
@ -583,7 +589,7 @@ PENDING o---------------------+ |
<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 a considered session-ending event. However, in this case there is nothing for the party to acknowledge.</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 a considered session-ending event. However, in this case there is nothing for the party to acknowledge.</p>
</section2> </section2>
<section2 topic='Informational Messages' anchor='session-info'> <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 or application type parameter, inform the other party that a device is ringing or that a scheduled event has occurred or will occur, etc.</p> <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 or application format parameter, 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 &lt;unsupported-info/&gt;.</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 &lt;unsupported-info/&gt;.</p>
<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>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 description format or transport method and therefore are described in specifications other than this one.</p> <p>Informational messages are specific to a particular description format or transport method and therefore are described in specifications other than this one.</p>
@ -690,7 +696,7 @@ PENDING o---------------------+ |
<tr> <tr>
<td>&lt;unsupported-content/&gt;</td> <td>&lt;unsupported-content/&gt;</td>
<td>&notacceptable;</td> <td>&notacceptable;</td>
<td>The recipient does not support any of the desired application types.</td> <td>The recipient does not support any of the desired application formats.</td>
</tr> </tr>
<tr> <tr>
<td>&lt;unsupported-info/&gt;</td> <td>&lt;unsupported-info/&gt;</td>
@ -706,7 +712,7 @@ PENDING o---------------------+ |
</section1> </section1>
<section1 topic='Determining Support' anchor='support'> <section1 topic='Determining Support' anchor='support'>
<p>If an entity supports Jingle, it MUST advertise that fact by returning a feature of "http://www.xmpp.org/extensions/xep-0166.html#ns" &NSNOTE; in response to a &xep0030; information request. The response MUST also include features for the application types and transport methods supported by the responding entity, as described in the specifications for those formats and methods.</p> <p>If an entity supports Jingle, it MUST advertise that fact by returning a feature of "http://www.xmpp.org/extensions/xep-0166.html#ns" &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 specifications for those formats and methods.</p>
<example caption="Service Discovery Information Request"><![CDATA[ <example caption="Service Discovery Information Request"><![CDATA[
<iq from='romeo@montague.lit/orchard' <iq from='romeo@montague.lit/orchard'
id='disco1' id='disco1'
@ -730,13 +736,13 @@ PENDING o---------------------+ |
</section1> </section1>
<section1 topic='Conformance by Using Protocols' anchor='conformance'> <section1 topic='Conformance by Using Protocols' anchor='conformance'>
<section2 topic='Application Types' anchor='conformance-apps'> <section2 topic='Application Formats' anchor='conformance-apps'>
<p>A document that specifies a Jingle application type (e.g., audio via RTP) MUST define:</p> <p>A document that specifies a Jingle application format (e.g., audio via RTP) MUST define:</p>
<ol> <ol>
<li>How successful application type negotiation occurs for encapsulation into Jingle.</li> <li>How successful application format negotiation occurs for encapsulation into Jingle.</li>
<li>A &DESCRIPTION; element and associated semantics for representing the application type.</li> <li>A &DESCRIPTION; element and associated semantics for representing the application format.</li>
<li>If and how the application type can be mapped to the Session Description Protocol.</li> <li>If and how the application format can be mapped to the Session Description Protocol.</li>
<li>Whether the media for the application type should be sent over a reliable or lossy transport type (or both).</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> <li>Exactly how the media is to be sent and received over a reliable or lossy transport.</li>
</ol> </ol>
</section2> </section2>
@ -744,7 +750,7 @@ PENDING o---------------------+ |
<p>A document that specifies a Jingle transport method (e.g., Raw UDP) MUST define:</p> <p>A document that specifies a Jingle transport method (e.g., Raw UDP) MUST define:</p>
<ol> <ol>
<li>How successful transport negotiation occurs for encapsulation into Jingle.</li> <li>How successful transport negotiation occurs for encapsulation into Jingle.</li>
<li>A &TRANSPORT; element and associated semantics for representing the transport type.</li> <li>A &TRANSPORT; element and associated semantics for representing the transport method.</li>
<li>Whether the transport is reliable or lossy.</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> <li>If and how the transport handles components as defined herein (e.g., for the Real Time Control Protocol).</li>
</ol> </ol>
@ -771,15 +777,15 @@ PENDING o---------------------+ |
<section2 topic='Protocol Namespaces' anchor='registrar-ns'> <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>Until this specification advances to a status of Draft, its associated namespaces shall be "http://www.xmpp.org/extensions/xep-0166.html#ns" and "http://www.xmpp.org/extensions/xep-0166.html#ns-errors"; upon advancement of this specification, the &REGISTRAR; shall issue permanent namespaces in accordance with the process defined in Section 4 of &xep0053;.</p> <p>Until this specification advances to a status of Draft, its associated namespaces shall be "http://www.xmpp.org/extensions/xep-0166.html#ns" and "http://www.xmpp.org/extensions/xep-0166.html#ns-errors"; upon advancement of this specification, the &REGISTRAR; shall issue permanent namespaces in accordance with the process defined in Section 4 of &xep0053;.</p>
</section2> </section2>
<section2 topic='Jingle Application Types Registry' anchor='registrar-apptypes'> <section2 topic='Jingle Application Formats Registry' anchor='registrar-apps'>
<p>The XMPP Registrar shall maintain a registry of Jingle application types. All application type 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:application:name" (where "name" is the registered name of the application type).</p> <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:application:name" (where "name" is the registered name of the application format).</p>
&REGPROCESS; &REGPROCESS;
<code><![CDATA[ <code><![CDATA[
<application> <application>
<name>the name of the application type</name> <name>the name of the application format</name>
<desc>a natural-language summary of the application type</desc> <desc>a natural-language summary of the application format</desc>
<transport>whether the media should be sent over a "reliable" or "lossy" transport</transport> <transport>whether the media should be sent over a "reliable" or "lossy" transport</transport>
<doc>the document in which this application type is specified</doc> <doc>the document in which this application format is specified</doc>
</application> </application>
]]></code> ]]></code>
</section2> </section2>
@ -935,722 +941,6 @@ PENDING o---------------------+ |
</section2> </section2>
</section1> </section1>
<section1 topic='Scenarios' anchor='scenarios'>
<p>The very simple scenario described in the <link url='#howitworks'>How It Works</link> section of this document is just that: very simple. Typically, the session flow is more complex. The following sections show some more complex scenarios, in relative order of complexity.</p>
<section2 topic='Receiver is Busy' anchor='scenarios-busy'>
<p>In this scenario, Romeo initiates a voice chat with Juliet but she is otherwise engaged.</p>
<p>The session flow is as follows:</p>
<code><![CDATA[
Romeo Juliet
| |
| session-initiate |
|---------------------------->|
| error |
| (recipient-unavailable) |
|<----------------------------|
]]></code>
<p>The protocol flow is as follows.</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='romeo@montague.lit/orchard' to='juliet@capulet.lit/balcony' id='jingle1' type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content' profile='RTP/AVP'>
<description xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns'>
<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='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'/>
</content>
</jingle>
</iq>
]]></example>
<example caption="Receiver returns recipient-unavailable error"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='accept1'
to='romeo@montague.lit/orchard'
type='error'>
<error type='wait'>
<recipient-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<busy xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns-errors'/>
</error>
</iq>
]]></example>
</section2>
<section2 topic='Jingle Audio via RTP/AVP, Negotiated with ICE-UDP' anchor='scenarios-voicechat'>
<p>In this scenario, Romeo initiates a voice chat with Juliet using a transport method of ICE-UDP. The parties also exchange informational messages.</p>
<p>The session flow is as follows:</p>
<code><![CDATA[
Romeo Juliet
| |
| session-initiate |
|---------------------------->|
| ack |
|<----------------------------|
| session-info (ringing) |
|<----------------------------|
| ack |
|---------------------------->|
| transport-info (X times) |
| (with acks) |
|<--------------------------->|
| session-accept |
|<----------------------------|
| ack |
|---------------------------->|
| AUDIO (RTP) |
|<===========================>|
| session-terminate |
|<----------------------------|
| ack |
|---------------------------->|
| |
]]></code>
<p>The protocol flow is as follows.</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='romeo@montague.lit/orchard' to='juliet@capulet.lit/balcony' id='jingle1' type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content' profile='RTP/AVP'>
<description xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns'>
<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='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'/>
</content>
</jingle>
</iq>
]]></example>
<example caption="Receiver sends provisional acceptance"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='accept1'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
<example caption="Receiver sends ringing message"><![CDATA[
<iq from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='ringing1'
type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-info'
initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'>
<ringing xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns-info'/>
</jingle>
</iq>
]]></example>
<example caption="Initiator acknowledges ringing message"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='ringing1'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<example caption="Initiator sends a candidate"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='info1'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='transport-info'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content' profile='RTP/AVP'>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'>
<candidate component='1'
foundation='1'
generation='0'
ip='10.0.1.1'
network='0'
port='8998'
priority='2114978302'
protocol='udp'
pwd='asd88fgpdd777uzjYhagZg'
type='host'
ufrag='8hhy'/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<example caption="Initiator sends a second candidate"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='info2'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='transport-info'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content' profile='RTP/AVP'>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'>
<candidate component='1'
foundation='1'
generation='0'
ip='192.0.2.3'
network='1'
port='45664'
priority='1678246398'
protocol='udp'
pwd='asd88fgpdd777uzjYhagZg'
type='srflx'
ufrag='8hhy'/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<example caption="Initiator sends a third candidate"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='info3'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='transport-info'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content' profile='RTP/AVP'>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'>
<candidate component='1'
foundation='1'
generation='0'
ip='208.245.212.67'
network='2'
port='53267'
priority='1677984254'
protocol='udp'
pwd='asd88fgpdd777uzjYhagZg'
type='srflx'
ufrag='8hhy'/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<p>For each candidate received, the other party acknowledges receipt or returns an error:</p>
<example caption="Responder acknowledges receipt"><![CDATA[
<iq from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='info1' type='result'/>
<iq from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='info2' type='result'/>
<iq from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='info3' type='result'/>
]]></example>
<p>At the same time (i.e., immediately after provisionally accepting the session, not waiting for the initiator to begin or finish sending candidates), the responder also begins sending candidates that may work for it. As above, the initiator acknowledges receipt of the candidates.</p>
<p>As the initiator and responder receive candidates, they probe the various candidate transports for connectivity. In performing these connectivity checks, the parties follow the procedure specified in Section 7 of <cite>draft-ietf-mmusic-ice</cite>.</p>
<p>If one of the candidate transports is found to work, the receiver accepts the session.</p>
<example caption="Receiver sends session-accept"><![CDATA[
<iq type='set' from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='accept1'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
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='http://www.xmpp.org/extensions/xep-0167.html#ns'>
<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='http://www.xmpp.org/extensions/xep-0176.html#ns'>
<candidate ip='208.245.212.67' port='9876' generation='0'/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<p>If the payload types and transport candidate can be successfully used by both parties, then the initiator acknowledges the session-accept.</p>
<example caption="Initiator acknowledges session-accept"><![CDATA[
<iq type='result' to='juliet@capulet.lit/balcony' from='romeo@montague.lit/orchard' id='accept1'/>
]]></example>
<p>The parties now 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='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
reason='Sorry, gotta go!'
sid='a73sjjvkla37jfea'/>
</iq>
]]></example>
<p>The other party then acknowledges 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>
</section2>
<section2 topic='Jingle Audio and Video via RTP/AVP, Negotiated with ICE-UDP' anchor='scenarios-voicechat'>
<p>In this scenario, Romeo initiates a combined audio and video chat with Juliet using a transport method of ICE. Juliet at first refuses the video portion, then later offers to add video, which Romeo accepts. The parties also exchange various informational messages</p>
<p>The session flow is as follows:</p>
<code><![CDATA[
Romeo Juliet
| |
| session-initiate |
|---------------------------->|
| ack |
|<----------------------------|
| session-info (ringing) |
|<----------------------------|
| ack |
|---------------------------->|
| content-remove |
|<----------------------------|
| ack |
|---------------------------->|
| content-accept |
|---------------------------->|
| ack |
|<----------------------------|
| transport-info (X times) |
| (with acks) |
|<--------------------------->|
| session-accept |
|<----------------------------|
| ack |
|---------------------------->|
| AUDIO (RTP) |
|<===========================>|
| session-info (hold) |
|<----------------------------|
| ack |
|---------------------------->|
| session-info (active) |
|<----------------------------|
| ack |
|---------------------------->|
| content-add |
|<----------------------------|
| ack |
|---------------------------->|
| content-accept |
|---------------------------->|
| ack |
|<----------------------------|
| AUDIO + VIDEO (RTP) |
|<===========================>|
| session-terminate |
|<----------------------------|
| ack |
|---------------------------->|
| |
]]></code>
<p>The protocol flow is as follows.</p>
<example caption="Initiation"><![CDATA[
<iq from='romeo@montague.lit/orchard' to='juliet@capulet.lit/balcony' id='jingle1' type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content' profile='RTP/AVP'>
<description xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns'>
<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='http://www.xmpp.org/extensions/xep-0176.html#ns'/>
</content>
<content creator='initiator' name='this-is-the-video-content' profile='RTP/AVP'>
<description xmlns='http://www.xmpp.org/extensions/xep-0180.html#ns'>
<payload-type id='96' name='theora' clockrate='90000' height='720' width='1280'>
<parameter name='delivery-method' value='inline'/>
<parameter name='configuration' value='somebase16string'/>
<parameter name='sampling' value='YCbCr-4:2:2'/>
</payload-type>
<payload-type id='28' name='nv' clockrate='90000'/>
<payload-type id='25' name='CelB' clockrate='90000'/>
<payload-type id='32' name='MPV' clockrate='90000'/>
</description>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns'/>
</content>
</jingle>
</iq>
]]></example>
<example caption="Receiver acknowledges receipt of initiation request"><![CDATA[
<iq type='result' from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='jingle1'/>
]]></example>
<example caption="Receiver sends ringing message"><![CDATA[
<iq from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='ringing1'
type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-info'
initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'>
<ringing xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns-info'/>
</jingle>
</iq>
]]></example>
<example caption="Initiator acknowledges ringing message"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='ringing1'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<p>However, Juliet doesn't want to do video because she is having a bad hair day, so she sends a "content-remove" request to Romeo.</p>
<example caption="Receiver requests content-remove"><![CDATA[
<iq from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='remove1' type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='content-remove'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-video-content' profile='RTP/AVP'/>
</jingle>
</iq>
]]></example>
<p>Romeo then acknowledges the content-remove request and, if it is acceptable, returns a content-accept:</p>
<example caption="Initiator acknowledges content-remove"><![CDATA[
<iq from='romeo@montague.lit/orchard' to='juliet@capulet.lit/balcony' id='remove1' type='result'/>
]]></example>
<example caption="Initiator accepts content definition"><![CDATA[
<iq from='romeo@montague.lit/orchard' to='juliet@capulet.lit/balcony' id='remove2' type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='content-accept'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='responder' name='this-is-the-video-content' profile='RTP/AVP'>
<description xmlns='http://www.xmpp.org/extensions/xep-0180.html#ns'/>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns'/>
</content>
</jingle>
</iq>
]]></example>
<p>The other party then acknowledges the acceptance.</p>
<example caption="Receiver acknowledges content-accept"><![CDATA[
<iq from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='remove2' type='result'/>
]]></example>
<p>As in the previous scenario, the parties exchange ICE candidates (see above for examples).</p>
<p>Once the parties find candidate transports that work, the receiver accepts the session.</p>
<example caption="Receiver sends session-accept"><![CDATA[
<iq type='set' from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='accept1'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
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='http://www.xmpp.org/extensions/xep-0167.html#ns'>
<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='http://www.xmpp.org/extensions/xep-0176.html#ns'>
<candidate ip='208.245.212.67' port='9876' generation='0'/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<p>As above, if the payload types and transport candidate can be successfully used by both parties, then the initiator acknowledges the session-accept.</p>
<example caption="Initiator acknowledges session-accept"><![CDATA[
<iq type='result' to='juliet@capulet.lit/balcony' from='romeo@montague.lit/orchard' id='accept1'/>
]]></example>
<p>The parties now 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>Juliet wants to get her hair in order so she puts Romeo on hold.</p>
<example caption="Receiver sends hold message"><![CDATA[
<iq from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='hold1'
type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-info'
initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'>
<hold xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns-info'/>
</jingle>
</iq>
]]></example>
<example caption="Initiator acknowledges hold message"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='hold1'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<p>Juliet returns so she informs Romeo that she is actively engaged in the call again.</p>
<example caption="Receiver sends active message"><![CDATA[
<iq from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='active1'
type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-info'
initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'>
<active xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns-info'/>
</jingle>
</iq>
]]></example>
<example caption="Initiator acknowledges active message"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='active1'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<p>The parties now continue the audio chat.</p>
<p>Finally Juliet decides that she is presentable for a video chat so she sends a content-add request to Romeo.</p>
<example caption="Receiver sends a content-add"><![CDATA[
<iq from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='add1' type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='content-add'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='responder' name='video-is-back' profile='RTP/AVP'>
<description xmlns='http://www.xmpp.org/extensions/xep-0180.html#ns'>
<payload-type id='96' name='theora' height='720' width='1280'>
<parameter name='delivery-method' value='inline'/>
<parameter name='configuration' value='somebase16string'/>
<parameter name='sampling' value='YCbCr-4:2:2'/>
</payload-type>
<payload-type id='32' name='MPV' clockrate='90000'/>
<payload-type id='33' name='MP2T' clockrate='90000'/>
</description>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns'>
</content>
</jingle>
</iq>
]]></example>
<p>The entity receiving the content-add request then acknowledges the request and, if it is acceptable, returns a content-accept:</p>
<example caption="Initiator acknowledges content-add"><![CDATA[
<iq from='romeo@montague.lit/orchard' to='juliet@capulet.lit/balcony' id='add1' type='result'/>
]]></example>
<example caption="Initiator accepts content type definition"><![CDATA[
<iq from='romeo@montague.lit/orchard' to='juliet@capulet.lit/balcony' id='add2' type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='content-accept'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='responder' name='video-is-back' profile='RTP/AVP'>
<description xmlns='http://www.xmpp.org/extensions/xep-0180.html#ns'>
<payload-type id='96' name='theora' height='720' width='1280'>
<parameter name='delivery-method' value='inline'/>
<parameter name='configuration' value='somebase16string'/>
<parameter name='sampling' value='YCbCr-4:2:2'/>
</payload-type>
<payload-type id='32' name='MPV' clockrate='90000'/>
<payload-type id='33' name='MP2T' clockrate='90000'/>
</description>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns'/>
</content>
</jingle>
</iq>
]]></example>
<p>The other party then acknowledges the acceptance.</p>
<example caption="Receiver acknowledges content-accept"><![CDATA[
<iq from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='add2' type='result'/>
]]></example>
<p>The media session proceeds. Now they would exchange both audio and video, where the audio is exchanged the Speex codec at a clockrate of 8000 and the video is exchanged using the Theora codec with a height of 720 pixels, a width of 1280 pixels, and so on.</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="Initiator sends session-terminate"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='term1'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
reason='I&apos;m outta here!'
sid='a73sjjvkla37jfea'/>
</iq>
]]></example>
<example caption="Receiver acknowledges session-terminate"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='term1'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
</section2>
<section2 topic='Secure Jingle Audio via UDP/TLS/RTP/AVP, Negotiated with ICE-UDP' anchor='scenarios-secure'>
<p>In this scenario, Romeo initiates a voice chat with Juliet using a transport method of ICE-UDP and an unencrypted profile of "RTP/AVP", but Juliet wants to chat securely so she requests the use of a secure transport as specified in &sdpdtls; (via a profile of "UDP/TLS/RTP/AVP").</p>
<p>The session flow is as follows:</p>
<code><![CDATA[
Romeo Juliet
| |
| session-initiate |
|---------------------------->|
| ack |
|<----------------------------|
| session-info (ringing) |
|<----------------------------|
| ack |
|---------------------------->|
| content-modify |
|<----------------------------|
| ack |
|---------------------------->|
| content-accept |
|---------------------------->|
| ack |
|<----------------------------|
| transport-info (X times) |
| (with acks) |
|<--------------------------->|
| session-accept |
|<----------------------------|
| ack |
|---------------------------->|
| AUDIO (RTP) |
|<===========================>|
| session-terminate |
|<----------------------------|
| ack |
|---------------------------->|
| |
]]></code>
<p>The protocol flow is as follows.</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='romeo@montague.lit/orchard' to='juliet@capulet.lit/balcony' id='jingle1' type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content' profile='RTP/AVP'>
<description xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns'>
<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='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'/>
</content>
</jingle>
</iq>
]]></example>
<example caption="Receiver sends provisional acceptance"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='accept1'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
<example caption="Receiver sends ringing message"><![CDATA[
<iq from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='ringing1'
type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-info'
initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'>
<ringing xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns-info'/>
</jingle>
</iq>
]]></example>
<example caption="Initiator acknowledges ringing message"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='ringing1'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<p>However, Juliet wants to make sure that the communications are encrypted, so she sends a "content-modify" request to Romeo.</p>
<example caption="Receiver requests content-modify"><![CDATA[
<iq from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='mod1' type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='content-modify'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content' profile='UDP/TLS/RTP/AVP'/>
</jingle>
</iq>
]]></example>
<p>Romeo then acknowledges the content-modify request and, if it is acceptable, returns a content-accept:</p>
<example caption="Initiator acknowledges content-modify"><![CDATA[
<iq from='romeo@montague.lit/orchard' to='juliet@capulet.lit/balcony' id='mod1' type='result'/>
]]></example>
<example caption="Initiator accepts content definition"><![CDATA[
<iq from='romeo@montague.lit/orchard' to='juliet@capulet.lit/balcony' id='mod2' type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='content-accept'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='responder' name='this-is-the-audio-content' profile='UDP/TLS/RTP/AVP'/>
</jingle>
</iq>
]]></example>
<p>The other party then acknowledges the acceptance.</p>
<example caption="Receiver acknowledges content-accept"><![CDATA[
<iq from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='mod2' type='result'/>
]]></example>
<p>As in the previous scenario, the parties exchange ICE candidates (see above for examples).</p>
<p>If one of the candidate transports is found to work, the receiver accepts the session.</p>
<example caption="Receiver sends session-accept"><![CDATA[
<iq type='set' from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='accept1'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
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='UDP/TLS/RTP/AVP'>
<description xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns'>
<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='http://www.xmpp.org/extensions/xep-0176.html#ns'>
<candidate ip='208.245.212.67' port='9876' generation='0'/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<p>If the payload types and transport candidate can be successfully used by both parties, then the initiator acknowledges the session-accept.</p>
<example caption="Initiator acknowledges session-accept"><![CDATA[
<iq type='result' to='juliet@capulet.lit/balcony' from='romeo@montague.lit/orchard' id='accept1'/>
]]></example>
<p>The parties now 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='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
reason='Sorry, gotta go!'
sid='a73sjjvkla37jfea'/>
</iq>
]]></example>
<p>The other party then acknowledges 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>
</section2>
</section1>
<section1 topic='History' anchor='history'> <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>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> <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>