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.29

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2111 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2008-08-01 03:47:14 +00:00
parent 72c717365a
commit 66fd54e33e
1 changed files with 301 additions and 193 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

390
xep-0166.xml
View File

@ -10,7 +10,7 @@
<abstract>This specification defines an XMPP protocol extension for initiating and managing peer-to-peer media sessions between two XMPP entities in a way that is interoperable with existing Internet standards. The protocol provides a pluggable model that enables the core session management semantics to be used for a wide variety of application types (e.g., voice chat, video chat, file sharing) and with a wide variety of transport methods (e.g., TCP, UDP, ICE, application-specific transports).</abstract>
&LEGALNOTICE;
<number>0166</number>
<status>Proposed</status>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
@ -26,6 +26,23 @@
&robmcqueen;
&seanegan;
&hildjj;
<revision>
<version>0.29</version>
<date>2008-07-31</date>
<initials>psa/ram</initials>
<remark>
<ul>
<li>Changed "reliable" vs. "lossy" to "stream" vs. "datagram", since reliability or dependability is orthogonal to the streaming nature of the transport.</li>
<li>Deleted the "content-remove" action.</li>
<li>Added "transport-replace" action (answered by "transport-accept").</li>
<li>Removed &lt;condition/&gt; element as container for Jingle condition elements inside &lt;reason/&gt;, since it introduced an unnecessary layer of indirection.</li>
<li>Modified state machine to allow content removal during PENDING state.</li>
<li>Noted that a session can have more than one content instance of the same type.</li>
<li>Noted that the 'name' attribute is unique to a creator.</li>
<li>Changed examples to once again use voice chat instead of file transfer.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.28</version>
<date>2008-06-16</date>
@ -286,61 +303,98 @@ Romeo Juliet
<p>Naturally, more complex scenarios are probable; such scenarios are described in other specifications, such as <cite>XEP-0167</cite> for voice chat.</p>
<p>The simplest flow might happen as follows. The example is that of a file transfer offer, where the transport method is &xep0065;.</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
<iq from='romeo@montague.net/orchard'
id='jingle1'
to='laertes@shakespeare.lit/castle'
to='juliet@capulet.com/balcony'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
<jingle xmlns='urn:xmpp:tmp:jingle'>
action='session-initiate'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
size='1022'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
</file>
</offer>
initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='voice'>
<description xmlns='urn:xmpp:tmp:jingle:apps:rtp' media='audio'>
<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='0' name='PCMU' />
<payload-type id='103' name='L16' clockrate='16000' channels='2'/>
<payload-type id='98' name='x-ISAC' clockrate='8000'/>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
<transport xmlns='urn:xmpp:tmp:jingle:transports:ice-udp'/>
</content>
</jingle>
</iq>
]]></example>
<p>The responder immediately acknowledges receipt of the session-initiate.</p>
<p>Upon receiving the session-initiate stanza, the responder determines whether it can proceed with the negotiation. If there is no error, the responder acknowledges the session initiation request.</p>
<example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
<iq from='juliet@capulet.com/balcony'
id='jingle1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.net/orchard'
type='result'/>
]]></example>
<p>The parties would then attempt to negotiate use of the SOCKS5 Bytestreams transport method, as described in <cite>XEP-0065</cite>.</p>
<p>Once the file transfer succeeds, one of the parties terminates the session.</p>
<p>After successful transport negotiation (not shown here), the responder accepts the session by sending a session-accept action to the initiator.</p>
<example caption="Responder definitively accepts the session"><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='accept1'
to='romeo@montague.net/orchard'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-accept'
initiator='romeo@montague.net/orchard'
responder='juliet@capulet.com/balcony'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='voice'>
<description xmlns='urn:xmpp:tmp:jingle:apps:rtp' media='audio'>
<payload-type id='97' name='speex' clockrate='8000'/>
<payload-type id='18' name='G729'/>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:ice-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>
<p>And the initiator acknowledges session acceptance:</p>
<example caption="Initiator acknowledges session acceptance"><![CDATA[
<iq from='romeo@montague.net/orchard'
id='accept1'
to='juliet@capulet.com/balcony'
type='result'/>
]]></example>
<p>The initiator and responder would then exchange media using any of the acceptable codecs.</p>
<p>Eventually, one of the parties (here the responder) can terminate the sessio.</p>
<example caption="Responder terminates the session"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
<iq from='juliet@capulet.lit/balcony'
id='term1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-terminate'
initiator='kingclaudius@shakespeare.lit/castle'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason>
<condition>
<success/>
</condition>
<no-error/>
<text>Sorry, gotta go!</text>
</reason>
</jingle>
</iq>
]]></example>
<p>The other party then acknowledges termination of the session.</p>
<p>The other party then acknowledges termination of the session:</p>
<example caption="Initiator acknowledges termination"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
<iq from='romeo@montague.lit/orchard'
id='term1'
to='laertes@shakespeare.lit/castle'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
</section1>
@ -388,7 +442,7 @@ Romeo Juliet
</tr>
<tr>
<td>Transport Method</td>
<td>The method for establishing data stream(s) between entities. Possible transports might include ICE-TCP, Raw UDP, inband data, etc. This is the 'how' of the session. In Jingle XML syntax this is the namespace of the &TRANSPORT; element. The transport method defines how to transfer bits from one host to another. Each transport method must specify whether it is lossy (thus suitable for applications where some packet loss is tolerable) or reliable (thus suitable for applications where packet loss is not tolerable).</td>
<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 datagram (thus suitable for applications where some packet loss is tolerable) or stream (thus suitable for applications where packet loss is not tolerable).</td>
</tr>
</table>
</section2>
@ -410,15 +464,15 @@ Romeo Juliet
<p>This document defines the semantics and syntax for overall session management. It also provides pluggable "slots" for application formats and transport methods, which are specified in separate documents.</p>
<p>At the most basic level, the process for initial negotiation of a Jingle session is as follows (i.e., the actions that can be generated during the PENDING state):</p>
<ol>
<li>One user (the "initator") sends to another user (the "responder") a session request with at least one content type.</li>
<li>One user (the "initator") sends to another user (the "responder") a session request with at least one content definition.</li>
<li>If the responder wants to proceed, it acknowledges the session initiation request by sending an IQ result.</li>
<li>The parties attempt to set up data transmission over the designated transport method as defined in the relevant specification (e.g., this may involve sending multiple transport-info actions).</li>
<li>Optionally, the responder may remove content types via the content-remove action or change the direction of the media flow via the content-modify action.</li>
<li>Optionally, either party may send session-info actions (to inform the other party that it is attempting transport negotiation, that its device is ringing, etc.).</li>
<li>The parties attempt to set up data transmission over the designated transport method as defined in the relevant specification (e.g., this can involve sending multiple transport-info actions).</li>
<li>Optionally, the responder can remove content definitions via the content-remove action or change the direction of the media flow via the content-modify action.</li>
<li>Optionally, either party can send session-info actions (to inform the other party that it is attempting transport negotiation, that its device is ringing, etc.).</li>
<li>As soon as the responder determines that data can flow over the designated transport, it sends to the initiator a session-accept action.</li>
<li>The parties start sending data over the transport.</li>
</ol>
<p>After the initial session negotiation has been completed and the session is in the ACTIVE state, the parties can adjust the session definition. This may involve sending the content-modify and content-remove actions (which are allowed while in the PENDING state), but it may also involve sending the content-add and content-replace actions, which are acknowledged via the content-accept action. In addition, certain transport methods allow continued sending of transport-info actions while in the ACTIVE state. And naturally the parties may send session-info actions at any time.</p>
<p>After the initial session negotiation has been completed and the session is in the ACTIVE state, the parties can adjust the session definition. This can involve sending the content-modify, content-remove, content-add, and transport-replace actions. In addition, certain transport methods allow continued sending of transport-info actions while in the ACTIVE state. And naturally the parties may send session-info actions at any time.</p>
<section2 topic='Overall Session Management' anchor='concepts-session'>
<p>The state machine for overall session management (i.e., the state per Session ID) is as follows:</p>
<code>
@ -426,30 +480,32 @@ Romeo Juliet
|
| session-initiate
|
| +-----------------------+
| +------------------------+
|/ |
PENDING o---------------------+ |
PENDING o----------------------+ |
| | content-accept, | |
| | content-modify, | |
| | content-remove, | |
| | content-replace, | |
| | session-info, | |
| | transport-accept | |
| | transport-info | |
| +------------------+ |
| | transport-replace | |
| +-------------------+ |
| |
| session-accept |
| |
ACTIVE o---------------------+ |
ACTIVE o----------------------+ |
| | content-accept, | |
| | content-add, | |
| | content-modify, | |
| | content-remove, | |
| | content-replace, | |
| | session-info, | |
| | transport-accept | |
| | transport-info | |
| +------------------+ |
| | transport-replace | |
| +-------------------+ |
| |
+-------------------------+
+--------------------------+
|
| session-terminate
|
@ -469,23 +525,19 @@ PENDING o---------------------+ |
</tr>
<tr>
<td>content-accept</td>
<td>Accept a content-add or content-replace action received from another party.</td>
<td>Accept a content-add action received from another party.</td>
</tr>
<tr>
<td>content-add</td>
<td>Add one or more new content types to the session. The sender MUST specify only the added content-type(s), not the added content-type(s) plus the existing content-type(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definition. This action MUST NOT be sent while the session is in the PENDING state. When a party sends a content-add, it MUST ignore any actions received from the other party until it receives acknowledgement of the content-add. If the recipient wishes to include the new content type in the session, it MUST send a content-accept action to the other party. <note>In the event that a session contains two unidirectional streams of the same type because a content-add was issued simultaneously by both parties, it is RECOMMENDED that participants close the duplicate stream in favor of that created by the session initiator, which should be made bidirectional via a content-modify action sent by the responder.</note></td>
<td>Add one or more new content definitions to the session. The sender MUST specify only the added content definition(s), not the added content definition(s) plus the existing content definition(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content definition(s). This action MUST NOT be sent while the session is in the PENDING state. If the recipient wishes to include the new content definition in the session, it MUST send a content-accept action to the other party. <note>In the event that a session contains two unidirectional streams of the same definition because a content-add was issued simultaneously by both parties, it is RECOMMENDED that participants close the duplicate stream in favor of that created by the session initiator, which should be made bidirectional via a content-modify action sent by the responder.</note></td>
</tr>
<tr>
<td>content-modify</td>
<td>Change the direction of an existing content type thorugh modification of the 'senders' attribute. The recipient MUST NOT reply to a content-modify action with another content-modify action and MUST NOT send a content-accept action in response to the content-modify (but MAY terminate the session if the new directionality is unacceptable, or MAY simply refuse to send or accept application data in the new direction). <note>If both parties send content-modify actions at the same time, the content-modify from the session initiator MUST trump the content-modify from the recipient and the initiator SHOULD return an &unexpected; error to the other party.</note></td>
<td>Change the direction of an existing content definition thorugh modification of the 'senders' attribute. If the recipient deems the directionality of a content-modify action to be unacceptable, it MAY reply with a contrary content-modify action, terminate the session, or simply refuse to send or accept application data in the new direction. In any case, the recipient MUST NOT send a content-accept action in response to the content-modify. <note>If both parties send content-modify actions at the same time, the content-modify from the session initiator MUST trump the content-modify from the recipient and the initiator SHOULD return an &unexpected; error to the other party.</note></td>
</tr>
<tr>
<td>content-remove</td>
<td>Remove one or more content types from the session. The sender MUST specify only the removed content-type(s), not the removed content-type(s) plus the remaining content-type(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definition. Upon receiving a content-remove from the other party, the recipient MUST NOT send a content-accept and MUST NOT continue to negotiate the transport method related to that content type or send application data related to that content type. The recipient MUST NOT send a content-accept in response to a content-remove. <note>A client MUST NOT return an error upon receipt of a 'content-remove' action for a content type that is received after a 'content-remove' action has been sent but before the action has been acknowledged by the peer.</note> <note>If the content-remove results in zero content types for the session, the entity that receives the content-remove SHOULD send a session-terminate action to the other party (since a session with no content types is void).</note></td>
</tr>
<tr>
<td>content-replace</td>
<td>Replace the definition of a content type with a new definition; essentially this functions as a simultaneous content-remove and content-add. The application type MUST NOT change but the definition of the application type MAY be modified (e.g., a file offer may be modified to a file request). In order to handle fallback scenarios, the transport method MAY be changed (e.g., from &xep0065; to &xep0047;) or the definition of the existing method MAY be modified. The sender MUST specify only one replaced content-type, not any existing content-type that shall not been replaced. Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definitions. When a party sends a content-replace, it MUST ignore any content-replace action it may receive from the other party with regard to the same content type until it receives acknowledgement of the content-replace. If the recipient wishes to include the replaced content type in the session, it MUST send a content-accept action to the other party. <note>If both parties send content-replace actions at the same time with regard to the same content type, the content-replace from the session initiator MUST trump the content-replace from the recipient and the initiator SHOULD return an &unexpected; error to the other party.</note></td>
<td>Remove one or more content definitions from the session. The sender MUST specify only the removed content definition(s), not the removed content definition(s) plus the remaining content definition(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content definition(s). Upon receiving a content-remove from the other party, the recipient MUST NOT send a content-accept and MUST NOT continue to negotiate the transport method related to that content definition or send application data related to that content definition. The recipient MUST NOT send a content-accept in response to a content-remove. <note>A client MUST NOT return an error upon receipt of a 'content-remove' action for a content definition that is received after a 'content-remove' action has been sent but before the action has been acknowledged by the peer.</note> <note>If the content-remove results in zero content definitions for the session, the entity that receives the content-remove SHOULD send a session-terminate action to the other party (since a session with no content definitions is void).</note></td>
</tr>
<tr>
<td>session-accept</td>
@ -503,10 +555,22 @@ PENDING o---------------------+ |
<td>session-terminate</td>
<td>End an existing session.</td>
</tr>
<tr>
<td>transport-accept</td>
<td>
</tr>
<tr>
<td>transport-accept</td>
<td>Accept a transport-replace action received from another party.</td>
</tr>
<tr>
<td>transport-info</td>
<td>Exchange transport candidates; it is mainly used in <cite>XEP-0176</cite> but may be used in other transport specifications.</td>
</tr>
<tr>
<td>transport-replace</td>
<td>Redefine a transport method.</td>
</tr>
</table>
</section2>
</section1>
@ -518,27 +582,24 @@ PENDING o---------------------+ |
<section2 topic='Initiation' anchor='protocol-initiate'>
<p>Once the initiator has discovered which of the responder's XMPP resources is ideal for the desired application format, it sends a session initiation request to the responder. This request is an IQ-set containing a &JINGLE; element qualified by the 'urn:xmpp:tmp:jingle' namespace &NSNOTE;, where the value of the 'action' attribute is "session-initiate" and where the &JINGLE; element contains one or more &CONTENT; elements. Each &CONTENT; element defines a content type to be transferred during the session, and each &CONTENT; element in turn contains one &DESCRIPTION; child element that specifies a desired application format and one &TRANSPORT; child element that specifies a potential transport method. If either party wishes to propose the use of multiple transport methods for the same application format, it must send multiple &CONTENT; elements.</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
<iq from='romeo@montague.net/orchard'
id='jingle1'
to='laertes@shakespeare.lit/castle'
to='juliet@capulet.com/balcony'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
<jingle xmlns='urn:xmpp:tmp:jingle'>
action='session-initiate'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
size='1022'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
</file>
</offer>
initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='voice'>
<description xmlns='urn:xmpp:tmp:jingle:apps:rtp' media='audio'>
<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='0' name='PCMU' />
<payload-type id='103' name='L16' clockrate='16000' channels='2'/>
<payload-type id='98' name='x-ISAC' clockrate='8000'/>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
<transport xmlns='urn:xmpp:tmp:jingle:transports:ice-udp'/>
</content>
</jingle>
</iq>
@ -546,9 +607,9 @@ PENDING o---------------------+ |
<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 action and before receiving acknowledgement from the responder (i.e., the initiator MUST consider the session to be PENDING even before receiving acknowledgement). Given in-order delivery, the responder should receive such transport-info actions after receiving the session-initiate action (if not, it is appropriate for the responder to return &lt;unknown-session/&gt; errors since according to its state machine the session does not exist).</p>
<example caption="Responder returns unknown-session error"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
<iq from='juliet@capulet.com/balcony'
id='jingle1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.net/orchard'
type='error'>
<error type='cancel'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@ -561,9 +622,9 @@ PENDING o---------------------+ |
<section3 topic='Acknowledgement' anchor='protocol-response-ack'>
<p>Unless one of the following errors occurs, the responder SHOULD acknowledge receipt of the initiation request.</p>
<example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
<iq from='juliet@capulet.com/balcony'
id='jingle1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.net/orchard'
type='result'/>
]]></example>
<p>However, after acknowledging the session initiation request, the responder may subsequently determine that it cannot proceed with negotiation of the session (e.g., because it does not support any of the offered application formats or transport methods, because a human user is busy or unable to accept the session, because a human user wishes to formally decline the session, etc.). In these cases, the responder SHOULD immediately acknowledge the session initiation request but then terminate the session with an appropriate reason as described in the <link url='#session-terminate'>Termination</link> section of this document.</p>
@ -580,9 +641,9 @@ PENDING o---------------------+ |
</ul>
<p>If the initiator is unknown to the responder (e.g., via presence subscription as defined in &rfc3921; or stanza session negotiation as defined in &xep0155;) and the responder has a policy of not communicating via Jingle with unknown entities, it SHOULD return a &unavailable; error.</p>
<example caption="Initiator is unknown to responder"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
<iq from='juliet@capulet.com/balcony'
id='jingle1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.net/orchard'
type='error'>
<error type='cancel'>
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@ -591,9 +652,9 @@ PENDING o---------------------+ |
]]></example>
<p>If the responder does not support Jingle, it MUST return a &unavailable; error.</p>
<example caption="Responder does not support Jingle"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
<iq from='juliet@capulet.com/balcony'
id='jingle1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.net/orchard'
type='error'>
<error type='cancel'>
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@ -602,9 +663,9 @@ PENDING o---------------------+ |
]]></example>
<p>If the responder wishes to redirect the request to another address, it SHOULD return a &redirect; error.</p>
<example caption="Responder redirection"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
<iq from='juliet@capulet.com/balcony'
id='jingle1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.net/orchard'
type='error'>
<error type='cancel'>
<redirect xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>
@ -615,9 +676,9 @@ PENDING o---------------------+ |
]]></example>
<p>If the responder does not have sufficient resources to participate in a session, it SHOULD return a &constraint; error.</p>
<example caption="Responder has insufficent resources"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
<iq from='juliet@capulet.com/balcony'
id='jingle1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.net/orchard'
type='error'>
<error type='wait'>
<resource-constraint xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@ -626,9 +687,9 @@ PENDING o---------------------+ |
]]></example>
<p>If the initiation request was malformed, the responder MUST return a &badrequest; error.</p>
<example caption="Initiation request malformed"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
<iq from='juliet@capulet.com/balcony'
id='jingle1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.net/orchard'
type='error'>
<error type='cancel'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@ -643,7 +704,7 @@ PENDING o---------------------+ |
<ul>
<li>Exchanging particular transport candidates via the transport-info action.</li>
<li>Modifying the communication direction for a content type via the content-modify action.</li>
<li>Changing the definition of a content type via the content-replace action (e.g., to fall back to a more suitable transport).</li>
<li>Changing the definition of a content type via the transport-replace action (typically to fall back to a more suitable transport).</li>
<li>Adding a content type via the content-add action (not allowed in the PENDING state).</li>
<li>Removing a content type via the content-remove action (not allowed in the PENDING state).</li>
</ul>
@ -662,86 +723,128 @@ PENDING o---------------------+ |
<p>The party that terminates the session SHOULD include a &lt;reason/&gt; element that specifies why the session is being terminated. Examples follow.</p>
<p>One reason for terminating the session is that the terminating party is busy; in this case, the recommended condition is "busy".</p>
<example caption="Terminating the session (busy)"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='accept1'
to='romeo@montague.net/orchard'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-accept'
initiator='romeo@montague.net/orchard'
responder='juliet@capulet.com/balcony'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='voice'>
<description xmlns='urn:xmpp:tmp:jingle:apps:rtp' media='audio'>
<payload-type id='97' name='speex' clockrate='8000'/>
<payload-type id='18' name='G729'/>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:ice-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>
<p>And the initiator acknowledges session acceptance:</p>
<example caption="Initiator acknowledges session acceptance"><![CDATA[
<iq from='romeo@montague.net/orchard'
id='accept1'
to='juliet@capulet.com/balcony'
type='result'/>
]]></example>
<p>The initiator and responder would then exchange media using any of the acceptable codecs.</p>
<p>Eventually, one of the parties (here the responder) can terminate the sessio.</p>
<example caption="Responder terminates the session"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='term1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-terminate'
initiator='kingclaudius@shakespeare.lit/castle'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason>
<condition><busy/></condition>
<busy/>
</reason>
</jingle>
</iq>
]]></example>
<p>Another reason for terminating the session is that the terminating party wishes to formally decline the session; in this case, the recommended condition is "decline".</p>
<example caption="Terminating the session (session formally declined)"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
<iq from='juliet@capulet.lit/balcony'
id='term1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-terminate'
initiator='kingclaudius@shakespeare.lit/castle'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason>
<condition><decline/></condition>
<decline/>
</reason>
</iq>
]]></example>
<p>Another reason for terminating the session is that the terminating party already has an existing session with the other party and wishes to use that session rather than initiate a new session; in this case, the recommended condition is "alternative-session" and the terminating party SHOULD include the session ID of the atlernative session in the &lt;sid/&gt; element.</p>
<example caption="Terminating the session (existing session)"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
<iq from='juliet@capulet.lit/balcony'
id='term1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-terminate'
initiator='kingclaudius@shakespeare.lit/castle'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason>
<condition><alternative-session/></condition>
<alternative-session>
<sid>b84tkkwlmb48kgfb</sid>
</alternative-session>
</reason>
</iq>
]]></example>
<p>Another reason for terminating the session is that the terminating party does not support any of the offered application formats; in this case, the recommended condition is "unsupported-applications".</p>
<example caption="Terminating the session (no offered application format supported)"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
<iq from='juliet@capulet.lit/balcony'
id='term1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-terminate'
initiator='kingclaudius@shakespeare.lit/castle'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason>
<condition><unsupported-applications/></condition>
<unsupported-applications/>
</reason>
</iq>
]]></example>
<p>Another reason for terminating the session is that the terminating party does not support any of the offered transport methods; in this case, the recommended condition is "unsupported-transports".</p>
<example caption="Terminating the session (no offered transport method supported)"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
<iq from='juliet@capulet.lit/balcony'
id='term1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-terminate'
initiator='kingclaudius@shakespeare.lit/castle'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason>
<condition><unsupported-transports/></condition>
<unsupported-transports/>
</reason>
</iq>
]]></example>
<p>Upon receiving an action of "session-terminate", the other party MUST then acknowledge termination of the session:</p>
<example caption="Acknowledging termination"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
<iq from='romeo@montague.lit/orchard'
id='term1'
to='laertes@shakespeare.lit/castle'
type='result'/>
to='juliet@capulet.lit/balcony'
type='result'>
]]></example>
<p>Note: As soon as an entity sends a session-terminate action, it MUST consider the session to be in the ENDED state (even before receiving acknowledgement from the other party). If the terminating entity receives additional Jingle-related IQ-sets from the other party after sending the session-terminate action, it MUST reply with an &lt;unknown-session/&gt; error.</p>
<p>Unfortunately, not all sessions end gracefully. In applications of Jingle that also involve the exchange of presence information, receipt of &UNAVAILABLE; from the other party MAY be considered a session-ending event. However, in this case there is nothing for the party to acknowledge.</p>
@ -763,9 +866,9 @@ PENDING o---------------------+ |
]]></example>
<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>
<example caption="Responder returns unsupported-info error"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
<iq from='juliet@capulet.lit/balcony'
id='info1'
to='kingclaudius@shakespeare.lit/castle'
to='romeo@montague.lit/orchard'
type='error'>
<error type='modify'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@ -825,7 +928,7 @@ PENDING o---------------------+ |
</tr>
<tr>
<td>name</td>
<td>A unique name or identifier for the content type, which MAY have semantic meaning in order to differentiate this content type from other content types (e.g., two content types containing video media could differentiate between "room-pan" and "slides").</td>
<td>A unique name or identifier for the content type according to the creator, which MAY have semantic meaning in order to differentiate this content type from other content types (e.g., two content types containing video media could differentiate between "room-pan" and "slides").</td>
<td>REQUIRED</td>
</tr>
<tr>
@ -838,20 +941,19 @@ PENDING o---------------------+ |
<section2 topic='Reason Element' anchor='def-reason'>
<p>The structure of the &lt;reason/&gt; element is as follows.</p>
<ul>
<li>The &lt;reason/&gt; element MUST contain a &lt;condition/&gt; element that provides machine-readable information about the reason for the action.</li>
<li>The &lt;reason/&gt; element MAY contain a &lt;sid/&gt; element that specifies a Jingle SessionID (e.g., to point to an alternative session).</li>
<li>The &lt;reason/&gt; element MUST contain an element that provides machine-readable information about the condition that prompted the action.</li>
<li>The &lt;reason/&gt; element MAY contain a &lt;text/&gt; element that provides human-readable information about the reason for the action.</li>
<li>The &lt;reason/&gt; element MAY contain an element qualified by some other namespace that provides more detailed machine-readable information about the reason for the action.</li>
</ul>
<p>The defined conditions are described in the folloiwing table.</p>
<table caption='Defined Children of Condition Element'>
<table caption='Defined Conditions'>
<tr>
<th>Element</th>
<th>Description</th>
</tr>
<tr>
<td>&lt;alternative-session/&gt;</td>
<td>The party prefers to use an existing session with the peer rather than initiate a new session; the session ID of the alternative session should be provided in the reasontext attribute.</td>
<td>The party prefers to use an existing session with the peer rather than initiate a new session; the Jingle session ID of the alternative session SHOULD be provided as the XML character data of the &lt;sid/&gt; child.</td>
</tr>
<tr>
<td>&lt;busy/&gt;</td>
@ -951,8 +1053,8 @@ PENDING o---------------------+ |
<li>How successful application format negotiation occurs for encapsulation into Jingle.</li>
<li>A &DESCRIPTION; element and associated semantics for representing the application format.</li>
<li>If and how the application format can be mapped to the Session Description Protocol, including the appropriate SDP media type (see Section 8.2.1 of <cite>RFC 4566</cite>).</li>
<li>Whether the media for the application format should be sent over a reliable transport method or a lossy transport method (or, if both, which is preferred).</li>
<li>Exactly how the media is to be sent and received over a reliable or lossy transport.</li>
<li>Whether the media for the application format should be sent over a stream transport method or a datagram transport method (or, if both, which is preferred).</li>
<li>Exactly how the media is to be sent and received over a stream or datagram transport.</li>
</ol>
</section2>
<section2 topic='Transport Methods' anchor='conformance-transports'>
@ -960,7 +1062,7 @@ PENDING o---------------------+ |
<ol>
<li>How successful transport negotiation occurs for encapsulation into Jingle.</li>
<li>A &TRANSPORT; element and associated semantics for representing the transport method.</li>
<li>Whether the transport is reliable or lossy.</li>
<li>Whether the transport is stream or datagram.</li>
<li>If and how the transport handles components as defined herein (e.g., for the Real Time Control Protocol).</li>
</ol>
</section2>
@ -1004,7 +1106,7 @@ PENDING o---------------------+ |
<name>the name of the application format</name>
<desc>a natural-language summary of the application format</desc>
<transport>
whether the media can be sent over a "reliable" transport, a "lossy" transport, or "both"
whether the media can be sent over a "stream" transport, a "datagram" transport, or "both"
</transport>
<doc>the document in which this application format is specified</doc>
</application>
@ -1017,7 +1119,7 @@ PENDING o---------------------+ |
<transport>
<name>the name of the transport method</name>
<desc>a natural-language summary of the transport method</desc>
<type>whether the transport method can be "reliable", "lossy", or "both"</type>
<type>whether the transport method can be "stream", "datagram", or "both"</type>
<doc>the document in which this transport method is specified</doc>
</transport>
]]></code>
@ -1037,8 +1139,15 @@ PENDING o---------------------+ |
<xs:element name='jingle'>
<xs:complexType>
<xs:sequence>
<xs:element ref='content' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='reason' minOccurs='0' maxOccurs='1'/>
<xs:element ref='content'
type='contentElementType'
minOccurs='0'
maxOccurs='unbounded'/>
<xs:element ref='reason'
type='reasonElementType'
minOccurs='0'
maxOccurs='1'/>
<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
<xs:attribute name='action' use='required'>
<xs:simpleType>
@ -1047,12 +1156,13 @@ PENDING o---------------------+ |
<xs:enumeration value='content-add'/>
<xs:enumeration value='content-modify'/>
<xs:enumeration value='content-remove'/>
<xs:enumeration value='content-replace'/>
<xs:enumeration value='session-accept'/>
<xs:enumeration value='session-info'/>
<xs:enumeration value='session-initiate'/>
<xs:enumeration value='session-terminate'/>
<xs:enumeration value='transport-add'/>
<xs:enumeration value='transport-info'/>
<xs:enumeration value='transport-replace'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
@ -1062,8 +1172,7 @@ PENDING o---------------------+ |
</xs:complexType>
</xs:element>
<xs:element name='content'>
<xs:complexType>
<xs:complexType name='contentElementType'>
<xs:sequence>
<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
@ -1086,34 +1195,33 @@ PENDING o---------------------+ |
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name='reason'>
<xs:complexType>
<xs:complexType name='reasonElementType'>
<xs:sequence>
<xs:element ref='condition' minOccurs='0' maxOccurs='1'/>
<xs:element name='sid' type='xs:NCName' minOccurs='0' maxOccurs='1'/>
<xs:element name='text' type='xs:string' minOccurs='0' maxOccurs='1'/>
<xs:any namespace='##other' minOccurs='0' maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='condition'>
<xs:complexType>
<xs:choice>
<xs:element name='alternative-session' type='alternativeSessionElementType/>
<xs:element name='busy' type='empty'/>
<xs:element name='connectivity-error' type='empty'/>
<xs:element name='decline' type='empty'/>
<xs:element name='general-error' type='empty'/>
<xs:element name='invalid-credentials' type='empty'/>
<xs:element name='media-error' type='empty'/>
<xs:element name='no-error' type='empty'/>
<xs:element name='success' type='empty'/>
<xs:element name='unsupported-applications' type='empty'/>
<xs:element name='unsupported-transports' type='empty'/>
</xs:choice>
<xs:element name='sid' type='xs:NCName' minOccurs='0' maxOccurs='1'/>
<xs:element name='text' type='xs:string' minOccurs='0' maxOccurs='1'/>
<xs:any namespace='##other' minOccurs='0' maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
<xs:complexType name='alternativeSessionElementType'>
<xs:sequence>
<xs:element name='sid' type='xs:string'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
@ -1160,6 +1268,6 @@ PENDING o---------------------+ |
<p>As a result of feedback received on <cite>XEP-0111</cite>, the original authors of this document (Joe Hildebrand and Peter Saint-Andre) began to define such a signalling protocol, code-named Jingle. Upon communication with members of the Google Talk team, <note>Google Talk is a messaging and voice chat service and client provided by Google; see &lt;<link url='http://www.google.com/talk/'>http://www.google.com/talk/</link>&gt;.</note> it was discovered that the emerging Jingle approach was conceptually (and even syntactically) quite similar to the signalling protocol used in the Google Talk application. Therefore, in the interest of interoperability and adoption, we decided to harmonize the two approaches. The signalling protocol specified herein is, therefore, substantially equivalent to the original Google Talk protocol, with several adjustments based on feedback received from implementors as well as for publication by the XMPP Standards Foundation.</p>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>The authors would like to thank Rohan Mahy for his valuable input on early versions of the Jingle specifications. Thiago Camargo, Diana Cionoiu, Olivier Cr&#234;te, Dafydd Harries, Antti Ij&#228;s, Tim Julien, Lauri Kaila, Justin Karneges, Jussi Laako, Anthony Minessale, Matt O'Gorman, Rob Taylor, Matt Tucker, Saku Vainio, Brian West, and others have also provided helpful input. Thanks also to those who have commented on the &SSIG; and (earlier) Jingle <note>Before this specification was formally accepted by the XMPP Standards Foundation as an XMPP Extension Protocol, it was discussed on the semi-private &lt;jingle@jabber.org&gt; mailing list; although that list is no longer used since the standards@xmpp.org list is the preferred discussion venue, for historical purposes it is publicly archived at &lt;<link url='http://mail.jabber.org/pipermail/jingle/'>http://mail.jabber.org/pipermail/jingle/</link>&gt;.</note> mailing lists.</p>
<p>The authors would like to thank Rohan Mahy for his valuable input on early versions of the Jingle specifications. Thiago Camargo, Diana Cionoiu, Olivier Cr&#234;te, Dafydd Harries, Antti Ij&#228;s, Tim Julien, Lauri Kaila, Justin Karneges, Jussi Laako, Steffen Larsen, Anthony Minessale, Akito Nozaki, Matt O'Gorman, Rob Taylor, Matt Tucker, Justin Uberti, Saku Vainio, Brian West, Jeff Williams, and others have also provided helpful input. Thanks also to those who have commented on the &SSIG; and (earlier) Jingle <note>Before this specification was formally accepted by the XMPP Standards Foundation as an XMPP Extension Protocol, it was discussed on the semi-private &lt;jingle@jabber.org&gt; mailing list; although that list is no longer used since the standards@xmpp.org list is the preferred discussion venue, for historical purposes it is publicly archived at &lt;<link url='http://mail.jabber.org/pipermail/jingle/'>http://mail.jabber.org/pipermail/jingle/</link>&gt;.</note> mailing lists.</p>
</section1>
</xep>