moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-25 18:52:23 -05:00
Code Issues Releases Wiki Activity

0.29

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2912 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2009-03-20 22:06:07 +00:00
parent 0898916dbd
commit e3afb38a38
1 changed files with 48 additions and 166 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

214
xep-0167.xml
View File

@ -28,6 +28,12 @@
&seanegan; &seanegan;
&robmcqueen; &robmcqueen;
&diana; &diana;
<revision>
<version>0.29</version>
<date>2009-03-20</date>
<initials>psa</initials>
<remark><p>Simplified session flow for audio/video scenario; clarified handling of hold messages.</p></remark>
</revision>
<revision> <revision>
<version>0.28</version> <version>0.28</version>
<date>2009-03-11</date> <date>2009-03-11</date>
@ -630,33 +636,10 @@ delivery-method=inline; configuration=somebase16string;
</section1> </section1>
<section1 topic='Informational Messages' anchor='info'> <section1 topic='Informational Messages' anchor='info'>
<section2 topic='Format' anchor='info-format'> <p>Informational messages can be sent by either party within the context of Jingle to communicate the status of a Jingle RTP session, device, or principal. The informational message MUST be an IQ-set containing a &JINGLE; element of type "session-info", where the informational message is a payload element qualified by the 'urn:xmpp:jingle:apps:rtp:info:1' namespace. The following payload elements are defined. <note>A &lt;trying/&gt; element (equivalent to the SIP 100 Trying response code) is not necessary, since each session-level message is acknowledged via XMPP IQ semantics.</note></p>
<p>Informational messages can be sent by either party within the context of Jingle to communicate the status of a Jingle RTP session, device, or principal. The informational message MUST be an IQ-set containing a &JINGLE; element of type "session-info", where the informational message is a payload element qualified by the 'urn:xmpp:jingle:apps:rtp:info:1' namespace; the following payload elements are defined: <note>A &lt;trying/&gt; element (equivalent to the SIP 100 Trying response code) is not necessary, since each session-level message is acknowledged via XMPP IQ semantics.</note></p> <p>Note: Because an informational message is sent in an IQ-set, the receiving party MUST return either an IQ-result or an IQ-error (normally an IQ-result simply to acknowledge receipt).</p>
<table caption='Information Payload Elements'> <section2 topic='Active' anchor='info-active'>
<tr> <p>The &lt;active/&gt; payload indicates that the principal or device is again actively participating in the session after having been on mute or having put the other party on hold. The &lt;active/&gt; element MAY possess a 'name' attribute whose value specifies a particular session that is again active (e.g., activating the video aspect but not the audio aspect of a voice+video chat). If no 'name' attribute is included, the recipient MUST assume that all sessions are active.</p>
<th>Element</th>
<th>Meaning</th>
</tr>
<tr>
<td>&lt;active/&gt;</td>
<td>The principal or device is again actively participating in the session after having been on hold or on mute. The &lt;active/&gt; element MAY possess a 'name' attribute whose value specifies a particular session that is again active (e.g., activating the video aspect but not the audio aspect of a voice+video chat). If no 'name' attribute is included, the recipient MUST assume that all sessions are active.</td>
</tr>
<tr>
<td>&lt;hold/&gt;</td>
<td>The principal is temporarily pausing the chat (i.e., putting the other party on hold). This message is purely informational; to ensure that no media will be exchanged, it is necessary to change the value of the 'senders' attribute to "none" via a content-modify message.</td>
</tr>
<tr>
<td>&lt;mute/&gt;</td>
<td>The principal is temporarily stopping media output but continues to accept media input. The &lt;mute/&gt; element MAY possess a 'name' attribute whose value specifies a particular session to be muted (e.g., muting the audio aspect but not the video aspect of a voice+video chat). If no 'name' attribute is included, the recipient MUST assume that all sessions are to be muted.</td>
</tr>
<tr>
<td>&lt;ringing/&gt;</td>
<td>The device is ringing but the principal has not yet interacted with it to answer (this maps to the SIP 180 response code).</td>
</tr>
</table>
<p>Note: Because the informational message is sent in an IQ-set, the receiving party MUST return either an IQ-result or an IQ-error (normally only an IQ-result to acknowledge receipt; no error flows are defined or envisioned at this time).</p>
</section2>
<section2 topic='Examples' anchor='info-examples'>
<example caption="Responder sends active message"><![CDATA[ <example caption="Responder sends active message"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='juliet@capulet.lit/balcony'
id='yh3gr714' id='yh3gr714'
@ -671,6 +654,15 @@ delivery-method=inline; configuration=somebase16string;
</jingle> </jingle>
</iq> </iq>
]]></example> ]]></example>
</section2>
<section2 topic='Hold' anchor='info-hold'>
<p>The &lt;hold/&gt; payload indicates that the principal is temporarily pausing the chat (i.e., putting the other party on hold). It is RECOMMENDED for the parties to handle informational &lt;hold/&gt; messages as follows (where the holdee is the party that receives the hold message and the holder is the party that sends the hold message):</p>
<ul>
<li>The holdee SHOULD stop sending media.</li>
<li>The holdee MUST keep accepting media (this ensures that the holder can immediately start sending media again when switching back from hold to active, or can send hold music or other media).</li>
<li>The holder MAY continue to send media (e.g. hold music).</li>
<li>The holder MAY silently drop all media that it receives from the holdee.</li>
</ul>
<example caption="Responder sends hold message"><![CDATA[ <example caption="Responder sends hold message"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='juliet@capulet.lit/balcony'
id='xv39z423' id='xv39z423'
@ -684,6 +676,9 @@ delivery-method=inline; configuration=somebase16string;
</jingle> </jingle>
</iq> </iq>
]]></example> ]]></example>
</section2>
<section2 topic='Mute' anchor='info-mute'>
<p>The &lt;mute/&gt; payload indicates that the principal is temporarily stopping media output but continues to accept media input. The &lt;mute/&gt; element MAY possess a 'name' attribute whose value specifies a particular session to be muted (e.g., muting the audio aspect but not the video aspect of a voice+video chat). If no 'name' attribute is included, the recipient MUST assume that all sessions are to be muted.</p>
<example caption="Responder sends mute message"><![CDATA[ <example caption="Responder sends mute message"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='juliet@capulet.lit/balcony'
id='hg4891f5' id='hg4891f5'
@ -698,6 +693,9 @@ delivery-method=inline; configuration=somebase16string;
</jingle> </jingle>
</iq> </iq>
]]></example> ]]></example>
</section2>
<section2 topic='Ringing' anchor='info-ringing'>
<p>The &lt;ringing/&gt; payload indicates that the device is ringing but the principal has not yet interacted with it to answer (this maps to the SIP 180 response code).</p>
<example caption="Responder sends ringing message"><![CDATA[ <example caption="Responder sends ringing message"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='juliet@capulet.lit/balcony'
id='tgr515bt' id='tgr515bt'
@ -1489,7 +1487,7 @@ Romeo Gateway Juliet
</section2> </section2>
<section2 topic='Jingle Audio and Video via RTP, Negotiated with ICE-UDP' anchor='scenarios-audiovideo'> <section2 topic='Jingle Audio and Video via RTP, Negotiated with ICE-UDP' anchor='scenarios-audiovideo'>
<p>In this scenario, Romeo initiates an audio chat with Juliet using a transport method of ICE-UDP. Romeo wants to add video but Juliet refuses; later she offers to add video, which Romeo accepts. The parties also exchange various informational messages</p> <p>In this scenario, Romeo initiates an audio chat with Juliet using a transport method of ICE-UDP. After the chat is active, Romeo adds video. The parties also exchange various informational messages</p>
<p>The session flow is as follows (some of these messages are sent in parallel):</p> <p>The session flow is as follows (some of these messages are sent in parallel):</p>
<code><![CDATA[ <code><![CDATA[
Romeo Juliet Romeo Juliet
@ -1517,7 +1515,7 @@ Romeo Juliet
|---------------------------->| |---------------------------->|
| ack | | ack |
|<----------------------------| |<----------------------------|
| content-reject for video | | content-accept for video |
|<----------------------------| |<----------------------------|
| ack | | ack |
|---------------------------->| |---------------------------->|
@ -1525,28 +1523,10 @@ Romeo Juliet
|<----------------------------| |<----------------------------|
| ack | | ack |
|---------------------------->| |---------------------------->|
| content-modify for audio |
| (senders="none") |
|<----------------------------|
| ack |
|---------------------------->|
| session-info (active) | | session-info (active) |
|<----------------------------| |<----------------------------|
| ack | | ack |
|---------------------------->| |---------------------------->|
| content-modify for audio |
| (senders="both") |
|<----------------------------|
| ack |
|---------------------------->|
| content-add for video |
|<----------------------------|
| ack |
|---------------------------->|
| content-accept for video |
|---------------------------->|
| ack |
|---------------------------->|
| AUDIO + VIDEO (RTP) | | AUDIO + VIDEO (RTP) |
|<===========================>| |<===========================>|
| session-terminate | | session-terminate |
@ -1704,28 +1684,32 @@ Romeo Juliet
to='romeo@montague.lit/orchard' to='romeo@montague.lit/orchard'
type='result'/> type='result'/>
]]></example> ]]></example>
<p>However, Juliet doesn't want to do video because she is having a bad hair day, so she sends a content-reject message to Romeo.</p> <p>However, Juliet is having a bad hair day, so she sends a content-accept message to Romeo but puts him on hold while she gets her hair in order.</p>
<example caption="Responder rejects additional content-type"><![CDATA[ <example caption="Responder accepts additional content-type"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='juliet@capulet.lit/balcony'
id='ih481v7s' id='ih481v7s'
to='romeo@montague.lit/orchard' to='romeo@montague.lit/orchard'
type='set'> type='set'>
<jingle xmlns='urn:xmpp:jingle:1' <jingle xmlns='urn:xmpp:jingle:1'
action='content-reject' action='content-accept'
initiator='romeo@montague.lit/orchard' initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'> sid='a73sjjvkla37jfea'>
<content creator='initiator' name='webcam'/> <content creator='initiator' name='webcam'>
<description xmlns='urn:xmpp:jingle:apps:rtp:1' media='video'>
<payload-type id='98' name='theora' clockrate='90000'>
<parameter name='height' value='600'/>
<parameter name='width' value='800'/>
<parameter name='delivery-method' value='inline'/>
<parameter name='configuration' value='somebase16string'/>
<parameter name='sampling' value='YCbCr-4:2:2'/>
</payload-type>
<bandwidth type='AS'>128</bandwidth>
</description>
<transport xmlns='urn:xmpp:jingle:transports:ice-udp:0'/>
</content>
</jingle> </jingle>
</iq> </iq>
]]></example> ]]></example>
<p>Romeo then acknowledges the content-reject message.</p>
<example caption="Initiator acknowledges content-reject"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='ih481v7s'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<p>Juliet wants to get her hair in order, so she puts Romeo on hold while she will be away from her device for a while.</p>
<example caption="Responder sends hold message"><![CDATA[ <example caption="Responder sends hold message"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='juliet@capulet.lit/balcony'
id='rh49l1k4' id='rh49l1k4'
@ -1739,29 +1723,16 @@ Romeo Juliet
</jingle> </jingle>
</iq> </iq>
]]></example> ]]></example>
<example caption="Initiator acknowledges hold message"><![CDATA[ <p>Romeo then acknowledges the content-accept and session-info messages.</p>
<example caption="Initiator acknowledges content-accept"><![CDATA[
<iq from='romeo@montague.lit/orchard' <iq from='romeo@montague.lit/orchard'
id='rh49l1k4' id='ih481v7s'
to='juliet@capulet.lit/balcony' to='juliet@capulet.lit/balcony'
type='result'/> type='result'/>
]]></example> ]]></example>
<p>To ensure that the session is truly paused, Juliet's client sends a content-modify message, setting the 'senders' attribute to "none".</p> <example caption="Initiator acknowledges hold message"><![CDATA[
<example caption="Responder pauses the audio"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='dx93h15q'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='content-modify'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='voice' senders='none'/>
</jingle>
</iq>
]]></example>
<example caption="Initiator acknowledges session pause"><![CDATA[
<iq from='romeo@montague.lit/orchard' <iq from='romeo@montague.lit/orchard'
id='dx93h15q' id='rh49l1k4'
to='juliet@capulet.lit/balcony' to='juliet@capulet.lit/balcony'
type='result'/> type='result'/>
]]></example> ]]></example>
@ -1785,95 +1756,6 @@ Romeo Juliet
to='juliet@capulet.lit/balcony' to='juliet@capulet.lit/balcony'
type='result'/> type='result'/>
]]></example> ]]></example>
<p>Juliet's client also resumes the voice chat by setting the 'senders' attribute back to a value of "both".</p>
<example caption="Responder resumes the audio"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='rl2bf817'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='content-modify'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='voice' senders='both'/>
</jingle>
</iq>
]]></example>
<example caption="Initiator acknowledges session resumption"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='rl2bf817'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<p>The parties now continue the voice chat.</p>
<p>Finally Juliet decides that she is presentable for a video chat so she sends a content-add request to Romeo.</p>
<example caption="Responder sends a content-add"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='wk4h5b92'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='content-add'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='responder' name='webcam'>
<description xmlns='urn:xmpp:jingle:apps:rtp:1' media='video'>
<payload-type id='98' name='theora' clockrate='90000'>
<parameter name='height' value='600'/>
<parameter name='width' value='800'/>
<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'/>
<bandwidth type='AS'>128</bandwidth>
</description>
<transport xmlns='urn:xmpp:jingle:transports:ice-udp:0'/>
</content>
</jingle>
</iq>
]]></example>
<p>The entity receiving the content-add request then acknowledges the request and, if it is acceptable, returns a content-accept action:</p>
<example caption="Initiator acknowledges content-add"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='wk4h5b92'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<example caption="Initiator accepts new content definition"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='un3b8hn4'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='content-accept'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='responder' name='webcam'>
<description xmlns='urn:xmpp:jingle:apps:rtp:1' media='video'>
<payload-type id='98' name='theora' clockrate='90000'>
<parameter name='height' value='600'/>
<parameter name='width' value='800'/>
<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'/>
<bandwidth type='AS'>128</bandwidth>
</description>
<transport xmlns='urn:xmpp:jingle:transports:ice-udp:0'/>
</content>
</jingle>
</iq>
]]></example>
<p>Juliet then acknowledges the acceptance.</p>
<example caption="Responder acknowledges content-accept"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='un3b8hn4'
to='romeo@montague.lit/orchard'
type='result'/>
]]></example>
<p>The media session proceeds. Now they would exchange both audio and video, where the audio is exchanged via the Speex codec at a clockrate of 8000 and the video is exchanged using the Theora codec with a height of 600 pixels, a width of 800 pixels, a bandwidth limit of 128,000 kilobits per second, etc.</p> <p>The media session proceeds. Now they would exchange both audio and video, where the audio is exchanged via the Speex codec at a clockrate of 8000 and the video is exchanged using the Theora codec with a height of 600 pixels, a width of 800 pixels, a bandwidth limit of 128,000 kilobits per second, etc.</p>
<p>The parties can continue the session as long as desired.</p> <p>The parties can continue the session as long as desired.</p>
<p>Other events might occur throughout the life of the session. For example, one of the parties might want to tweak the video parameters using a description-info action.</p> <p>Other events might occur throughout the life of the session. For example, one of the parties might want to tweak the video parameters using a description-info action.</p>