git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@288 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2006-12-21 21:23:55 +00:00
parent e825713fc1
commit 1aa8cde63a
1 changed files with 61 additions and 70 deletions

View File

@ -7,10 +7,10 @@
<xep> <xep>
<header> <header>
<title>Jingle</title> <title>Jingle</title>
<abstract>This document defines a framework for initiating and managing peer-to-peer sessions (e.g., voice and video exchanges) between Jabber/XMPP clients in a way that is interoperable with existing Internet standards.</abstract> <abstract>This document defines a framework for initiating and managing peer-to-peer multimedia sessions (e.g., voice and video exchanges) between Jabber/XMPP clients in a way that is interoperable with existing Internet standards.</abstract>
&LEGALNOTICE; &LEGALNOTICE;
<number>0166</number> <number>0166</number>
<status>Proposed</status> <status>Experimenal</status>
<type>Standards Track</type> <type>Standards Track</type>
<jig>Standards JIG</jig> <jig>Standards JIG</jig>
<approver>Council</approver> <approver>Council</approver>
@ -19,13 +19,19 @@
</dependencies> </dependencies>
<supersedes/> <supersedes/>
<supersededby/> <supersededby/>
<shortname>jingle</shortname> <shortname>TO BE ASSIGNED</shortname>
&scottlu; &scottlu;
&joebeda; &joebeda;
&stpeter; &stpeter;
&hildjj; &hildjj;
&seanegan; &seanegan;
&robmcqueen; &robmcqueen;
<revision>
<version>0.11</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> <revision>
<version>0.11</version> <version>0.11</version>
<date>2006-10-31</date> <date>2006-10-31</date>
@ -202,7 +208,7 @@
</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 &xep0176;, &xep0177;, inband data, etc. This is the 'how' of the session. In Jingle XML syntax this is the namespace of the &TRANSPORT; element. The content transport method defines how to transfer bits from one host to another.</td> <td>The method for establishing data stream(s) between entities. Possible transports might include ICE, 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 content transport method defines how to transfer bits from one host to another.</td>
</tr> </tr>
<tr> <tr>
<td>Component</td> <td>Component</td>
@ -395,35 +401,31 @@ PENDING o---------------------+ |
<p>If a contact has more than one XMPP resource that supports Jingle and the desired content description format, it is RECOMMENDED for a client to use &xep0168; in order to determine which is the best resource with which to initiate the desired Jingle session.</p> <p>If a contact has more than one XMPP resource that supports Jingle and the desired content description format, it is RECOMMENDED for a client to use &xep0168; in order to determine which is the best resource with which to initiate the desired Jingle session.</p>
</section2> </section2>
<section2 topic='Initiation' anchor='protocol-initiate'> <section2 topic='Initiation' anchor='protocol-initiate'>
<p>Once the initiating entity has discovered which of the receiver's XMPP resources is ideal for the desired content description format, it sends a session initiation request to the receiver. This request is an IQ-set containing a &JINGLE; element qualified by the 'http://jabber.org/protocol/jingle' namespace. The &JINGLE; element MUST possess the 'action', 'initiator', and 'sid' attributes (the latter two uniquely identify the session). For initiation, the 'action' attribute MUST have a value of "session-initiate" and the &JINGLE; element MUST contain one or more &CONTENT; elements, each of which defines a content type to be transferred during the session; each &CONTENT; element in turn contains one &DESCRIPTION; child element that specifies a desired content description format and one or more &TRANSPORT; child elements that specify potential content transport methods.</p> <p>Once the initiating entity has discovered which of the receiver's XMPP resources is ideal for the desired content description 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. The &JINGLE; element MUST possess the 'action', 'initiator', and 'sid' attributes (the latter two uniquely identify the session). For initiation, the 'action' attribute MUST have a value of "session-initiate" and the &JINGLE; element MUST contain one or more &CONTENT; elements, each of which defines a content type to be transferred during the session; each &CONTENT; element in turn contains one &DESCRIPTION; child element that specifies a desired content description format and one or more &TRANSPORT; child elements that specify potential content transport methods.</p>
<p>The following example shows a Jingle session initiation request for a session that contains both audio and video content:</p> <p>The following example shows a Jingle session initiation request for a session that contains both audio and video content:</p>
<example caption="Initiation Example"><![CDATA[ <example caption="Initiation Example"><![CDATA[
<iq to='juliet@capulet.com/balcony' from='romeo@montague.net/orchard' id='jingle1' type='set'> <iq from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' id='jingle1' type='set'>
<jingle xmlns='http://jabber.org/protocol/jingle' <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-initiate' action='session-initiate'
initiator='romeo@montague.net/orchard' initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'> sid='a73sjjvkla37jfea'>
<content name='this-is-the-audio-content'> <content creator='romeo@montague.net' name='this-is-the-audio-content'>
<description xmlns='http://jabber.org/protocol/jingle/description/audio'> <description xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns'>
... ...
</description> </description>
<transport xmlns='http://jabber.org/protocol/jingle/transport/ice'> <transport xmlns='http://www.xmpp.org/extensions/xep-0177.html#ns'>
... <candidate .../>
</transport>
<transport xmlns='http://jabber.org/protocol/jingle/transport/raw-udp'>
...
</transport> </transport>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns'/>
</content> </content>
<content name='this-is-the-video-content'> <content creator='romeo@montague.net' name='this-is-the-video-content'>
<description xmlns='http://jabber.org/protocol/jingle/description/video'> <description xmlns='http://www.xmpp.org/extensions/xep-0180.html#ns'>
... ...
</description> </description>
<transport xmlns='http://jabber.org/protocol/jingle/transport/ice'> <transport xmlns='http://www.xmpp.org/extensions/xep-0177.html#ns'>
... <candidate .../>
</transport>
<transport xmlns='http://jabber.org/protocol/jingle/transport/raw-udp'>
...
</transport> </transport>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns'/>
</content> </content>
</jingle> </jingle>
</iq> </iq>
@ -438,8 +440,9 @@ PENDING o---------------------+ |
</ul> </ul>
<p>The attributes of the &CONTENT; element are as follows:</p> <p>The attributes of the &CONTENT; element are as follows:</p>
<ul> <ul>
<li>The 'creator' attribute is REQUIRED; it specifies which party originally generated the content description (used to prevent race conditions regarding modifications).</li>
<li>The 'name' attribute is REQUIRED; it specifies a unique name or identifier for the content type (this identifier is opaque and does not have semantic meaning).</li> <li>The 'name' attribute is REQUIRED; it specifies a unique name or identifier for the content type (this identifier is opaque and does not have semantic meaning).</li>
<li>The 'senders' attribute specifies which entities in the session will be generating content; the allowable values are "initiator", "recipient", or "both" (where "both" is the default).</li> <li>The 'senders' attribute is RECOMMENDED; it specifies which entities in the session will be generating content; the allowable values are "initiator", "recipient", or "both" (where "both" is the default).</li>
</ul> </ul>
</section2> </section2>
<section2 topic='Receiver Response' anchor='protocol-response'> <section2 topic='Receiver Response' anchor='protocol-response'>
@ -477,7 +480,7 @@ PENDING o---------------------+ |
<iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'> <iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'>
<error type='cancel'> <error type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<unsupported-content xmlns='http://jabber.org/protocol/jingle#errors'/> <unsupported-content xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns-errors'/>
</error> </error>
</iq> </iq>
]]></example> ]]></example>
@ -486,7 +489,7 @@ PENDING o---------------------+ |
<iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'> <iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'>
<error type='cancel'> <error type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<unsupported-transports xmlns='http://jabber.org/protocol/jingle#errors'/> <unsupported-transports xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns-errors'/>
</error> </error>
</iq> </iq>
]]></example> ]]></example>
@ -506,7 +509,7 @@ PENDING o---------------------+ |
id='jingle2' id='jingle2'
to='romeo@montague.net/orchard' to='romeo@montague.net/orchard'
type='set'> type='set'>
<jingle xmlns='http://jabber.org/protocol/jingle' <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-redirect' action='session-redirect'
initiator='romeo@montague.net/orchard' initiator='romeo@montague.net/orchard'
responder='juliet@capulet.com/balcony' responder='juliet@capulet.com/balcony'
@ -532,11 +535,11 @@ PENDING o---------------------+ |
<p>One session-level negotiation is to <em>remove</em> a content types. For example, let us imagine that Juliet is having a bad hair day. She certainly does not want to include video in her Jingle session with Romeo, so she sends a "content-remove" request to Romeo:</p> <p>One session-level negotiation is to <em>remove</em> a content types. For example, let us imagine that Juliet is having a bad hair day. She certainly does not want to include video in her Jingle session with Romeo, so she sends a "content-remove" request to Romeo:</p>
<example caption="Content Type Removal"><![CDATA[ <example caption="Content Type Removal"><![CDATA[
<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='reduce1' type='set'> <iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='reduce1' type='set'>
<jingle xmlns='http://jabber.org/protocol/jingle' <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='content-remove' action='content-remove'
initiator='romeo@montague.net/orchard' initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'> sid='a73sjjvkla37jfea'>
<content name='this-is-the-video-content'/> <content creator='romeo@montague.net' name='this-is-the-video-content'/>
</jingle> </jingle>
</iq> </iq>
]]></example> ]]></example>
@ -551,32 +554,20 @@ PENDING o---------------------+ |
<p>If (after negotiation of content transport methods and content description formats) the receiver determines that it will be able to establish a connection, it sends a definitive acceptance to the initiating entity:</p> <p>If (after negotiation of content transport methods and content description formats) the receiver determines that it will be able to establish a connection, it sends a definitive acceptance to the initiating entity:</p>
<example caption="Receiver Definitively Accepts the Call"><![CDATA[ <example caption="Receiver Definitively Accepts the Call"><![CDATA[
<iq type='set' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='accept1'> <iq type='set' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='accept1'>
<jingle xmlns='http://jabber.org/protocol/jingle' <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-accept' action='session-accept'
initiator='romeo@montague.net/orchard' initiator='romeo@montague.net/orchard'
responder='juliet@capulet.com/balcony' responder='juliet@capulet.com/balcony'
sid='a73sjjvkla37jfea'> sid='a73sjjvkla37jfea'>
<content name='some-opaque-name'> <content creator='romeo@montague.net' name='this-is-the-audio-content'>
<description xmlns='http://jabber.org/protocol/jingle/description/audio'> <description xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns'>
... ...
</description> </description>
<transport xmlns='http://jabber.org/protocol/jingle/transport/ice'> <transport xmlns='http://www.xmpp.org/extensions/xep-0177.html#ns'>
... <candidate .../>
</transport>
<transport xmlns='http://jabber.org/protocol/jingle/transport/raw-udp'>
...
</transport> </transport>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns'/>
</content> </content>
<content name='another-opaque-name'>
<description xmlns='http://jabber.org/protocol/jingle/description/video'>
...
</description>
<transport xmlns='http://jabber.org/protocol/jingle/transport/ice'>
...
</transport>
<transport xmlns='http://jabber.org/protocol/jingle/transport/raw-udp'>
...
</transport>
</jingle> </jingle>
</iq> </iq>
]]></example> ]]></example>
@ -594,20 +585,18 @@ PENDING o---------------------+ |
<p>One example of modifying an active session is to <em>add</em> a content type. For example, let us imagine that Juliet gets her hair in order and now wants to add video. She now sends a "content-add" request to Romeo:</p> <p>One example of modifying an active session is to <em>add</em> a content type. For example, let us imagine that Juliet gets her hair in order and now wants to add video. She now sends a "content-add" request to Romeo:</p>
<example caption="Adding a Content Type"><![CDATA[ <example caption="Adding a Content Type"><![CDATA[
<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='add1' type='set'> <iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='add1' type='set'>
<jingle xmlns='http://jabber.org/protocol/jingle' <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='content-add' action='content-add'
initiator='romeo@montague.net/orchard' initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'> sid='a73sjjvkla37jfea'>
<content name='video-is-back'> <content creator='juliet@capulet.com' name='video-is-back'>
<description xmlns='http://jabber.org/protocol/jingle/description/video'> <description xmlns='http://www.xmpp.org/extensions/xep-0180.html#ns'>
... ...
</description> </description>
<transport xmlns='http://jabber.org/protocol/jingle/transport/ice'> <transport xmlns='http://www.xmpp.org/extensions/xep-0177.html#ns'>
... <candidate .../>
</transport>
<transport xmlns='http://jabber.org/protocol/jingle/transport/raw-udp'>
...
</transport> </transport>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns'/>
</content> </content>
</jingle> </jingle>
</iq> </iq>
@ -617,21 +606,19 @@ PENDING o---------------------+ |
<iq from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' id='add1' type='result'/> <iq from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' id='add1' type='result'/>
]]></example> ]]></example>
<example caption="Content Acceptance"><![CDATA[ <example caption="Content Acceptance"><![CDATA[
<iq from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' id='add2' type='set'/> <iq from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' id='add2' type='set'>
<jingle xmlns='http://jabber.org/protocol/jingle' <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='content-add' action='content-add'
initiator='romeo@montague.net/orchard' initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'> sid='a73sjjvkla37jfea'>
<content name='video-is-back'> <content creator='juliet@capulet.com' name='video-is-back'>
<description xmlns='http://jabber.org/protocol/jingle/description/video'> <description xmlns='http://www.xmpp.org/extensions/xep-0180.html#ns'>
... ...
</description> </description>
<transport xmlns='http://jabber.org/protocol/jingle/transport/ice'> <transport xmlns='http://www.xmpp.org/extensions/xep-0177.html#ns'>
... <candidate .../>
</transport>
<transport xmlns='http://jabber.org/protocol/jingle/transport/raw-udp'>
...
</transport> </transport>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns'/>
</content> </content>
</jingle> </jingle>
</iq> </iq>
@ -648,7 +635,7 @@ PENDING o---------------------+ |
id='term1' id='term1'
to='romeo@montague.net/orchard' to='romeo@montague.net/orchard'
type='set'> type='set'>
<jingle xmlns='http://jabber.org/protocol/jingle' <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-terminate' action='session-terminate'
initiator='romeo@montague.net/orchard' initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'/> sid='a73sjjvkla37jfea'/>
@ -681,6 +668,7 @@ PENDING o---------------------+ |
</section2> </section2>
<section2 topic='content-add' anchor='actions-content-add'> <section2 topic='content-add' anchor='actions-content-add'>
<p>This action enables a party to add one or more new content types to the session. This action MUST NOT be sent while the session is in the PENDING state.</p> <p>This action enables a party to add one or more new content types to the session. This action MUST NOT be sent while the session is in the PENDING state.</p>
<p>In the event that a session contains two unidirectional streams of the same type, due to content-add being issued simultaneously by both participants of the session, 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.</p>
</section2> </section2>
<section2 topic='content-decline' anchor='actions-content-decline'> <section2 topic='content-decline' anchor='actions-content-decline'>
<p>This action enables a party to reject a content-add or content-modify action received from another party.</p> <p>This action enables a party to reject a content-add or content-modify action received from another party.</p>
@ -690,6 +678,7 @@ PENDING o---------------------+ |
</section2> </section2>
<section2 topic='content-remove' anchor='actions-content-remove'> <section2 topic='content-remove' anchor='actions-content-remove'>
<p>This action enables a party to remove one or more content types from the session.</p> <p>This action enables a party to remove one or more content types from the session.</p>
<p>Clients MUST NOT return an error upon recipt of a 'content-remove' action for a content description which is received after a 'content-remove' action has been sent, but before the action has been acknowledged by the peer.</p>
</section2> </section2>
<section2 topic='description-accept' anchor='actions-description-accept'> <section2 topic='description-accept' anchor='actions-description-accept'>
<p>This action enables a party to accept a description-modify action received from another party.</p> <p>This action enables a party to accept a description-modify action received from another party.</p>
@ -783,10 +772,10 @@ PENDING o---------------------+ |
<section1 topic='XMPP Registrar Considerations' anchor='registrar'> <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'> <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The &REGISTRAR; shall include 'http://jabber.org/protocol/jingle' and 'http://jabber.org/protocol/jingle#errors' in its registry of protocol namespaces.</p> <p>The &REGISTRAR; shall include 'http://www.xmpp.org/extensions/xep-0166.html#ns' and 'http://www.xmpp.org/extensions/xep-0166.html#ns-errors' in its registry of protocol namespaces.</p>
</section2> </section2>
<section2 topic='Jingle Content Description Formats Registry' anchor='registrar-content'> <section2 topic='Jingle Content Description Formats Registry' anchor='registrar-content'>
<p>The XMPP Registrar shall maintain a registry of Jingle content description formats. All content description format registrations shall be defined in separate specifications (not in this document). Content description formats defined within the XEP series MUST be registered with the XMPP Registrar, resulting in protocol URIs of the form "http://jabber.org/protocol/jingle/description/name" (where "name" is the registered name of the content description format).</p> <p>The XMPP Registrar shall maintain a registry of Jingle content description formats. All content description format registrations shall be defined in separate specifications (not in this document). Content description formats defined within the XEP series MUST be registered with the XMPP Registrar, resulting in protocol URIs of the form "http://www.xmpp.org/extensions/xep-0166.html#ns/description/name" (where "name" is the registered name of the content description format).</p>
&REGPROCESS; &REGPROCESS;
<code><![CDATA[ <code><![CDATA[
<content> <content>
@ -797,7 +786,7 @@ PENDING o---------------------+ |
]]></code> ]]></code>
</section2> </section2>
<section2 topic='Jingle Content Transport Methods Registry' anchor='registrar-transports'> <section2 topic='Jingle Content Transport Methods Registry' anchor='registrar-transports'>
<p>The XMPP Registrar shall maintain a registry of Jingle content transport methods. All content transport method registrations shall be defined in separate specifications (not in this document). Content transport methods defined within the XEP series MUST be registered with the XMPP Registrar, resulting in protocol URIs of the form "http://jabber.org/protocol/jingle/transport/name" (where "name" is the registered name of the content transport method).</p> <p>The XMPP Registrar shall maintain a registry of Jingle content transport methods. All content transport method registrations shall be defined in separate specifications (not in this document). Content transport methods defined within the XEP series MUST be registered with the XMPP Registrar, resulting in protocol URIs of the form "http://www.xmpp.org/extensions/xep-0166.html#ns/transport/name" (where "name" is the registered name of the content transport method).</p>
&REGPROCESS; &REGPROCESS;
<code><![CDATA[ <code><![CDATA[
<transport> <transport>
@ -815,8 +804,8 @@ PENDING o---------------------+ |
<xs:schema <xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema' xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/jingle' targetNamespace='http://www.xmpp.org/extensions/xep-0166.html#ns'
xmlns='http://jabber.org/protocol/jingle' xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
elementFormDefault='qualified'> elementFormDefault='qualified'>
<xs:element name='jingle'> <xs:element name='jingle'>
@ -861,6 +850,8 @@ PENDING o---------------------+ |
<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/> <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence> </xs:sequence>
</xs:choice> </xs:choice>
<xs:attribute name='creator' use='required' type='xs:string'/>
<xs:attribute name='name' use='required' type='xs:string'/>
<xs:attribute name='senders' use='optional' default='both'> <xs:attribute name='senders' use='optional' default='both'>
<xs:simpleType> <xs:simpleType>
<xs:restriction base='xs:NCName'> <xs:restriction base='xs:NCName'>
@ -882,8 +873,8 @@ PENDING o---------------------+ |
<xs:schema <xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema' xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/jingle#errors' targetNamespace='http://www.xmpp.org/extensions/xep-0166.html#ns-errors'
xmlns='http://jabber.org/protocol/jingle#errors' xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns-errors'
elementFormDefault='qualified'> elementFormDefault='qualified'>
<xs:element name='out-of-order' type='empty'/> <xs:element name='out-of-order' type='empty'/>