moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-21 23:28:51 -05:00
Code Issues Releases Wiki Activity

0.18

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1364 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2007-11-08 22:36:51 +00:00
parent 10f45766e7
commit 50180e35a7
1 changed files with 184 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

216
xep-0166.xml
View File

@ -27,10 +27,10 @@
&seanegan;
&hildjj;
<revision>
<version>0.18pre1</version>
<date>in progress, last updated 2007-11-02</date>
<version>0.18</version>
<date>2007-11-08</date>
<initials>psa</initials>
<remark><p>Added scenarios containing more examples.</p></remark>
<remark><p>Added scenarios for various session flows; clarified handling of content-add, content-modify, and content-remove actions; clarified rules for codec priority.</p></remark>
</revision>
<revision>
<version>0.17</version>
@ -231,7 +231,7 @@ Romeo Juliet
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content'>
<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'/>
@ -259,7 +259,7 @@ Romeo Juliet
initiator='romeo@montague.lit/orchard'
responder='juliet@capulet.lit/balcony'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content'>
<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'/>
@ -276,8 +276,9 @@ Romeo Juliet
</jingle>
</iq>
]]></example>
<p>If the foregoing payload types and transport candidates can be successfully used, then the parties would begin to exchange media (in this case audio).</p>
<p>The parties may continue the session as long as desired. Either party may terminate the session.</p>
<p>If the foregoing payload types and transport candidates can be successfully used, then the parties would 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'
@ -414,19 +415,19 @@ PENDING o---------------------+ |
</tr>
<tr>
<td>content-add</td>
<td>Add one or more new content types to the session. This action MUST NOT be sent while the session is in the PENDING state. When a party sends a content-add, it MUST ignore any actions received from the other party until it receives acknowledgement of the content-add. <note>In the event that a session contains two unidirectional streams of the same type because a content-add was issued simultaneously by both parties, it is RECOMMENDED that participants close the duplicate stream in favour of that created by the session initiator, which should be made bidirectional with a 'content-modify' action by the responder.</note></td>
<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 content definition. This action MUST NOT be sent while the session is in the PENDING state. When a party sends a content-add, it MUST ignore any actions received from the other party until it receives acknowledgement of the content-add. <note>In the event that a session contains two unidirectional streams of the same type because a content-add was issued simultaneously by both parties, it is RECOMMENDED that participants close the duplicate stream in favour of that created by the session initiator, which should be made bidirectional with a 'content-modify' action by the responder.</note></td>
</tr>
<tr>
<td>content-modify</td>
<td>Change an existing content type. The recipient MUST NOT reply to a content-modify action with another content-modify action. <note>If both parties send modify messages at the same time, the modify message from the session initiator MUST trump the modify message from the recipient and the initiator SHOULD return an &unexpected; error to the other party.</note></td>
<td>Change an existing content type. The sender SHOULD specify only the aspects for which a modification is desired (e.g., if the sender wishes to change only the profile then it would send an empty &lt;content/&gt; element with a modified value for the 'profile' attribute; if the wishes to change only the transport, then it would send a &lt;content/&gt; element that contains only a &lt;transport/&gt; child; etc.). Therefore it is the responsibility of the recipient to maintain a local copy of the content definition. The recipient MUST NOT reply to a content-modify action with another content-modify action. <note>If both parties send modify messages at the same time, the modify message from the session initiator MUST trump the modify message from the recipient and the initiator SHOULD return an &unexpected; error to the other party.</note></td>
</tr>
<tr>
<td>content-remove</td>
<td>Remove one or more content types from the session. <note>A client MUST NOT return an error upon receipt of a 'content-remove' action for a content description 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 no more 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>
<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 content definition. <note>A client MUST NOT return an error upon receipt of a 'content-remove' action for a content description 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 no more content types for the session, the entity that receives the content-remove SHOULD send a session-terminate action to the other party (since a session with no content types is void).</note></td>
</tr>
<tr>
<td>session-accept</td>
<td>Definitively accept a session negotiation. Implicitly this action also serves as a content-accept (which in turn serves as a description-accept and transport-accept).</td>
<td>Definitively accept a session negotiation (implicitly this action also serves as a content-accept).</td>
</tr>
<tr>
<td>session-info</td>
@ -565,7 +566,7 @@ PENDING o---------------------+ |
<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 order of complexity.</p>
<section2 topic='Jingle Audio via RTP, Negotiated with ICE-UDP' anchor='scenarios-voicechat'>
<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.</p>
<p>The session flow is as follows:</p>
<code><![CDATA[
@ -597,7 +598,7 @@ Romeo Juliet
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content'>
<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'/>
@ -625,7 +626,7 @@ Romeo Juliet
action='transport-info'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content'>
<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'
@ -652,7 +653,7 @@ Romeo Juliet
action='transport-info'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content'>
<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'
@ -679,7 +680,7 @@ Romeo Juliet
action='transport-info'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content'>
<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'
@ -715,7 +716,7 @@ Romeo Juliet
initiator='romeo@montague.lit/orchard'
responder='juliet@capulet.lit/balcony'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content'>
<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'/>
@ -732,12 +733,14 @@ Romeo Juliet
</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 and the parties begin to exchange media (in this case audio).</p>
<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 may continue the session as long as desired. Either party may terminate the session.</p>
<example caption="Receiver terminates the session"><![CDATA[
<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'
@ -757,7 +760,7 @@ Romeo Juliet
type='result'/>
]]></example>
</section2>
<section2 topic='Jingle Audio and Video via RTP, Negotiated with ICE-UDP' anchor='scenarios-voicechat'>
<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.</p>
<p>The session flow is as follows:</p>
<code><![CDATA[
@ -807,7 +810,7 @@ Romeo Juliet
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content'>
<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'/>
@ -817,7 +820,7 @@ Romeo Juliet
</description>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns'/>
</content>
<content creator='initiator' name='this-is-the-video-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'/>
@ -837,13 +840,13 @@ Romeo Juliet
<iq type='result' from='juliet@capulet.lit/balcony' to='romeo@montague.lit/orchard' id='jingle1'/>
]]></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 request content-remove"><![CDATA[
<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'/>
<content creator='initiator' name='this-is-the-video-content' profile='RTP/AVP'/>
</jingle>
</iq>
]]></example>
@ -857,7 +860,7 @@ Romeo Juliet
action='content-accept'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='responder' name='this-is-the-video-content'>
<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>
@ -877,7 +880,7 @@ Romeo Juliet
initiator='romeo@montague.lit/orchard'
responder='juliet@capulet.lit/balcony'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content'>
<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'/>
@ -894,10 +897,11 @@ Romeo Juliet
</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 and the parties begin to exchange media (in this case audio).</p>
<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>Once Juliet gets her hair in order, she 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'>
@ -905,7 +909,7 @@ Romeo Juliet
action='content-add'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='responder' name='video-is-back'>
<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'/>
@ -930,9 +934,15 @@ Romeo Juliet
action='content-accept'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='responder' name='video-is-back'>
<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>
@ -943,7 +953,8 @@ Romeo Juliet
<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, this time with both audio and video.</p>
<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'
@ -964,6 +975,147 @@ Romeo Juliet
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 |
|<----------------------------|
| 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>
<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 Scenario #1, 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 MUST then acknowledge termination of the session:</p>
<example caption="Initiator Acknowledges Termination"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='term1'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
</section2>
</section1>
<section1 topic='Formal Definition' anchor='def'>