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

0.24

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1706 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2008-02-29 03:17:16 +00:00
parent 0e73f89e7c
commit 828ca33f2d
1 changed files with 218 additions and 217 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

435
xep-0166.xml
View File

@ -26,6 +26,12 @@
&robmcqueen; &robmcqueen;
&seanegan; &seanegan;
&hildjj; &hildjj;
<revision>
<version>0.24</version>
<date>2008-02-28</date>
<initials>ram/psa</initials>
<remark><p>Added content-replace action; modified reasoncode and reasontext to use elements instead of attributes; added sid element to handle alternative-session condition; modified examples to use file transfer instead of voice chat; moved profile element to XEP-0167 and XEP-0180.</p></remark>
</revision>
<revision> <revision>
<version>0.23</version> <version>0.23</version>
<date>2008-01-11</date> <date>2008-01-11</date>
@ -254,93 +260,63 @@ Romeo Juliet
| | | |
]]></code> ]]></code>
<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>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 voice chat (see <cite>XEP-0167</cite>) initiated by Romeo, where the transport is &xep0177;.</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[ <example caption="Initiator sends session-initiate"><![CDATA[
<iq from='romeo@montague.lit/orchard' <iq from='kingclaudius@shakespeare.lit/castle'
id='jingle1' id='jingle1'
to='juliet@capulet.lit/balcony' to='laertes@shakespeare.lit/castle'
type='set'> type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle' <jingle xmlns='urn:xmpp:tmp:jingle'
action='session-initiate' action='session-initiate'
initiator='romeo@montague.lit/orchard' initiator='kingclaudius@shakespeare.lit/castle'
sid='a73sjjvkla37jfea'> sid='851ba2'>
<content creator='initiator' name='this-is-the-audio-content' profile='RTP/AVP'> <content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:audio-rtp'> <description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<payload-type id='96' name='speex' clockrate='16000'/> <offer>
<payload-type id='97' name='speex' clockrate='8000'/> <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
<payload-type id='18' name='G729'/> name='test.txt'
<payload-type id='103' name='L16' clockrate='16000' channels='2'/> size='1022'
<payload-type id='98' name='x-ISAC' clockrate='8000'/> hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
</file>
</offer>
</description> </description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:raw-udp'> <transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
<candidate ip='10.1.1.104' port='13540' generation='0'/>
</transport>
</content> </content>
</jingle> </jingle>
</iq> </iq>
]]></example> ]]></example>
<example caption="Receiver acknowledges session-initiate"><![CDATA[ <p>The responder immediately acknowledges receipt of the session-initiate.</p>
<iq from='juliet@capulet.lit/balcony' <example caption="Responder acknowledges session-initiate"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='jingle1' id='jingle1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='result'/> type='result'/>
]]></example> ]]></example>
<p>If the proposed session is acceptable, the responder definitively accepts it.</p> <p>The parties would then attempt to negotiate use of the SOCKS5 Bytestreams transport method, as described in <cite>XEP-0065</cite>.</p>
<example caption="Receiver sends session-accept"><![CDATA[ <p>Once the file transfer succeeds, one of the parties terminates the session.</p>
<iq from='juliet@capulet.lit/balcony'
id='accept1'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-accept'
initiator='romeo@montague.lit/orchard'
responder='juliet@capulet.lit/balcony'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content' profile='RTP/AVP'>
<description xmlns='urn:xmpp:tmp:jingle:apps:audio-rtp'>
<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='urn:xmpp:tmp:jingle:transports:raw-udp'>
<candidate ip='208.245.212.67' port='9876' generation='0'/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<p>The initiator then acknowledges the session-accept action.</p>
<example caption="Initiator acknowledges session-accept"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='accept1'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
<p>The parties then 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[ <example caption="Receiver terminates the session"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='term1' id='term1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='set'> type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle' <jingle xmlns='urn:xmpp:tmp:jingle'
action='session-terminate' action='session-terminate'
initiator='romeo@montague.lit/orchard' initiator='kingclaudius@shakespeare.lit/castle'
reasoncode='no-error' sid='a73sjjvkla37jfea'>
reasontext='Sorry, gotta go!' <reason>
sid='a73sjjvkla37jfea'/> <condition>
<success/>
</condition>
</reason>
</iq> </iq>
]]></example> ]]></example>
<p>The other party MUST then acknowledge termination of the session.</p> <p>The other party then acknowledges termination of the session.</p>
<example caption="Initiator acknowledges termination"><![CDATA[ <example caption="Initiator acknowledges termination"><![CDATA[
<iq from='romeo@montague.lit/orchard' <iq from='kingclaudius@shakespeare.lit/castle'
id='term1' id='term1'
to='juliet@capulet.lit/balcony' to='laertes@shakespeare.lit/castle'
type='result'/> type='result'/>
]]></example> ]]></example>
</section1> </section1>
@ -442,6 +418,7 @@ PENDING o---------------------+ |
| | content-add, | | | | content-add, | |
| | content-modify, | | | | content-modify, | |
| | content-remove, | | | | content-remove, | |
| | content-replace, | |
| | session-info, | | | | session-info, | |
| | transport-info | | | | transport-info | |
| +------------------+ | | +------------------+ |
@ -480,6 +457,10 @@ PENDING o---------------------+ |
<td>content-remove</td> <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. <note>The recipient SHOULD NOT send a content-accept with the new content type definition after receiving a content-remove.</note> <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> <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. <note>The recipient SHOULD NOT send a content-accept with the new content type definition after receiving a content-remove.</note> <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>
<tr>
<td>content-replace</td>
<td>Replace the definition of a content type with a new definition. The application type MUST NOT change but the definition of the application type MAY change. The transport method MAY change or MAY be modified.</td>
</tr>
<tr> <tr>
<td>session-accept</td> <td>session-accept</td>
<td>Definitively accept a session negotiation (implicitly this action also serves as a content-accept).</td> <td>Definitively accept a session negotiation (implicitly this action also serves as a content-accept).</td>
@ -513,9 +494,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: The syntax and semantics of the &DESCRIPTION; and &TRANSPORT; elements are out of scope for this specification, since they are defined in related specifications. The syntax and semantics of the &JINGLE; and &CONTENT; elements are specified in this document under <link url='#def'>Formal Definition</link>.</p>
<p>Note: In order to expedite session establishment, the initiator MAY send transport candidates (e.g., for negotiation of the ICE transport) immediately after sending the "session-initiate" message and before receiving acknowledgement from the 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" messages after receiving the "session-initiate" message (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> <p>Note: In order to expedite session establishment, the initiator MAY send transport candidates (e.g., for negotiation of the ICE transport) immediately after sending the "session-initiate" message and before receiving acknowledgement from the 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" messages after receiving the "session-initiate" message (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="Receiver returns unknown-session error"><![CDATA[ <example caption="Receiver returns unknown-session error"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='jingle1' id='jingle1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='error'> type='error'>
<error type='cancel'> <error type='cancel'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@ -528,12 +509,12 @@ PENDING o---------------------+ |
<section3 topic='Acknowledgement' anchor='protocol-response-ack'> <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> <p>Unless one of the following errors occurs, the responder SHOULD acknowledge receipt of the initiation request.</p>
<example caption="Receiver acknowledges session-initiate"><![CDATA[ <example caption="Receiver acknowledges session-initiate"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='jingle1' id='jingle1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='result'/> type='result'/>
]]></example> ]]></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 reasoncode as described in the <link url='#session-terminate'>Termination</link> section of this document.</p> <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>
<p>If the responder acknowledges receipt of the initation request, both parties must consider the session to be in the PENDING state.</p> <p>If the responder acknowledges receipt of the initation request, both parties must consider the session to be in the PENDING state.</p>
</section3> </section3>
<section3 topic='Errors' anchor='protocol-response-errors'> <section3 topic='Errors' anchor='protocol-response-errors'>
@ -547,9 +528,9 @@ PENDING o---------------------+ |
</ul> </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> <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[ <example caption="Initiator is unknown to responder"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='jingle1' id='jingle1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='error'> type='error'>
<error type='cancel'> <error type='cancel'>
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@ -558,9 +539,9 @@ PENDING o---------------------+ |
]]></example> ]]></example>
<p>If the responder does not support Jingle, it MUST return a &unavailable; error.</p> <p>If the responder does not support Jingle, it MUST return a &unavailable; error.</p>
<example caption="Receiver does not support Jingle"><![CDATA[ <example caption="Receiver does not support Jingle"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='jingle1' id='jingle1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='error'> type='error'>
<error type='cancel'> <error type='cancel'>
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@ -569,9 +550,9 @@ PENDING o---------------------+ |
]]></example> ]]></example>
<p>If the responder wishes to redirect the request to another address, it SHOULD return a &redirect; error.</p> <p>If the responder wishes to redirect the request to another address, it SHOULD return a &redirect; error.</p>
<example caption="Receiver redirection"><![CDATA[ <example caption="Receiver redirection"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='jingle1' id='jingle1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='error'> type='error'>
<error type='cancel'> <error type='cancel'>
<redirect xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'> <redirect xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>
@ -582,9 +563,9 @@ PENDING o---------------------+ |
]]></example> ]]></example>
<p>If the responder does not have sufficient resources to participate in a session, it SHOULD return a &constraint; error.</p> <p>If the responder does not have sufficient resources to participate in a session, it SHOULD return a &constraint; error.</p>
<example caption="Receiver has insufficent resources"><![CDATA[ <example caption="Receiver has insufficent resources"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='jingle1' id='jingle1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='error'> type='error'>
<error type='wait'> <error type='wait'>
<resource-constraint xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> <resource-constraint xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@ -593,9 +574,9 @@ PENDING o---------------------+ |
]]></example> ]]></example>
<p>If the initiation request was malformed, the responder MUST return a &badrequest; error.</p> <p>If the initiation request was malformed, the responder MUST return a &badrequest; error.</p>
<example caption="Initiation request malformed"><![CDATA[ <example caption="Initiation request malformed"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='jingle1' id='jingle1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='error'> type='error'>
<error type='cancel'> <error type='cancel'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@ -625,90 +606,113 @@ PENDING o---------------------+ |
</section2> </section2>
<section2 topic='Termination' anchor='session-terminate'> <section2 topic='Termination' anchor='session-terminate'>
<p>In order to gracefully end the session (which MAY be done at any point after acknowledging receipt of the initiation request, including immediately thereafter in order to decline the request), either the responder or the initiator MUST send a "terminate" action to the other party.</p> <p>In order to gracefully end the session (which MAY be done at any point after acknowledging receipt of the initiation request, including immediately thereafter in order to decline the request), either the responder or the initiator MUST send a "terminate" action to the other party.</p>
<p>The party that terminates the session SHOULD include a 'reasoncode' attribute that specifies why the session is being terminated. Examples follow.</p> <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 reasoncode is "busy".</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[ <example caption="Terminating the session (busy)"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='term1' id='term1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='set'> type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle' <jingle xmlns='urn:xmpp:tmp:jingle'
action='session-terminate' action='session-terminate'
initiator='romeo@montague.lit/orchard' initiator='kingclaudius@shakespeare.lit/castle'
reasoncode='busy' sid='a73sjjvkla37jfea'>
sid='a73sjjvkla37jfea'/> <reason>
<condition><busy/></condition>
</reason>
</iq> </iq>
]]></example> ]]></example>
<p>Another reason for terminating the session is that the terminating party wishes to formally decline the session; in this case, the recommended reasoncode is "decline".</p> <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[ <example caption="Terminating the session (session formally declined)"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='term1' id='term1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='set'> type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle' <jingle xmlns='urn:xmpp:tmp:jingle'
action='session-terminate' action='session-terminate'
initiator='romeo@montague.lit/orchard' initiator='kingclaudius@shakespeare.lit/castle'
reasoncode='decline' sid='a73sjjvkla37jfea'>
sid='a73sjjvkla37jfea'/> <reason>
<condition><decline/></condition>
</reason>
</iq> </iq>
]]></example> ]]></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 reasoncode is "alternative-session" and the terminating party should include the session ID of the atlernative session in the 'reasontext' attribute.</p> <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[ <example caption="Terminating the session (existing session)"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='term1' id='term1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='set'> type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle' <jingle xmlns='urn:xmpp:tmp:jingle'
action='session-terminate' action='session-terminate'
initiator='romeo@montague.lit/orchard' initiator='kingclaudius@shakespeare.lit/castle'
reasoncode='alternative-session' sid='a73sjjvkla37jfea'>
reasontext='b84tkkwlmb48kgfb'/> <reason>
sid='a73sjjvkla37jfea'/> <condition><alternative-session/></condition>
<sid>b84tkkwlmb48kgfb</sid>
</reason>
</iq> </iq>
]]></example> ]]></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 reasoncode is "unsupported-applications".</p> <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[ <example caption="Terminating the session (no offered application format supported)"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='term1' id='term1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='set'> type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle' <jingle xmlns='urn:xmpp:tmp:jingle'
action='session-terminate' action='session-terminate'
initiator='romeo@montague.lit/orchard' initiator='kingclaudius@shakespeare.lit/castle'
reasoncode='unsupported-applications' sid='a73sjjvkla37jfea'>
sid='a73sjjvkla37jfea'/> <reason>
<condition><unsupported-applications/></condition>
</reason>
</iq> </iq>
]]></example> ]]></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 reasoncode is "unsupported-transports".</p> <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[ <example caption="Terminating the session (no offered transport method supported)"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='term1' id='term1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='set'> type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle' <jingle xmlns='urn:xmpp:tmp:jingle'
action='session-terminate' action='session-terminate'
initiator='romeo@montague.lit/orchard' initiator='kingclaudius@shakespeare.lit/castle'
reasoncode='unsupported-transports' sid='a73sjjvkla37jfea'>
sid='a73sjjvkla37jfea'/> <reason>
<condition><unsupported-transports/></condition>
</reason>
</iq> </iq>
]]></example> ]]></example>
<p>Upon receiving an action of "session-terminate", the other party MUST then acknowledge termination of the session:</p> <p>Upon receiving an action of "session-terminate", the other party MUST then acknowledge termination of the session:</p>
<example caption="Acknowledging termination"><![CDATA[ <example caption="Acknowledging termination"><![CDATA[
<iq from='romeo@montague.lit/orchard' <iq from='kingclaudius@shakespeare.lit/castle'
id='term1' id='term1'
to='juliet@capulet.lit/balcony' to='laertes@shakespeare.lit/castle'
type='result'/> type='result'/>
]]></example> ]]></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>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> <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>
</section2> </section2>
<section2 topic='Informational Messages' anchor='session-info'> <section2 topic='Informational Messages' anchor='session-info'>
<p>At any point after initiation of a Jingle session, either entity MAY send an informational message to the other party, for example to change a transport method, inform the other party that a device is ringing or that a scheduled event has occurred or will occur, etc.</p> <p>At any point after initiation of a Jingle session, either entity MAY send an informational message to the other party, for example to inform the other party that a device is ringing.</p>
<example caption="Responder sends ringing message"><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='ringing1'
to='romeo@montague.net/orchard'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='session-info'
initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'>
<ringing xmlns='urn:xmpp:tmp:jingle:apps:audio-rtp:info'/>
</jingle>
</iq>
]]></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> <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="Receiver returns unsupported-info error"><![CDATA[ <example caption="Receiver returns unsupported-info error"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='info1' id='info1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='error'> type='error'>
<error type='modify'> <error type='modify'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@ -741,16 +745,6 @@ PENDING o---------------------+ |
<td>The full JID of the entity that has initiated the session flow (which may be different from the 'from' address on the IQ-set).</td> <td>The full JID of the entity that has initiated the session flow (which may be different from the 'from' address on the IQ-set).</td>
<td>REQUIRED</td> <td>REQUIRED</td>
</tr> </tr>
<tr>
<td>reasoncode</td>
<td>A machine-readable purpose for the action being sent (e.g., "connectivity-error" for a session-terminate action).</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>reasontext</td>
<td>A human-readable purpose for the action being sent (e.g., "Sorry, gotta go!" for a session-terminate action).</td>
<td>OPTIONAL</td>
</tr>
<tr> <tr>
<td>responder</td> <td>responder</td>
<td>The full JID of the entity that has replied to the initiation, which may be different from the 'to' address on the IQ-set.</td> <td>The full JID of the entity that has replied to the initiation, which may be different from the 'to' address on the IQ-set.</td>
@ -781,11 +775,6 @@ PENDING o---------------------+ |
<td>A unique name or identifier for the content type (this identifier is opaque and does not have semantic meaning).</td> <td>A unique name or identifier for the content type (this identifier is opaque and does not have semantic meaning).</td>
<td>REQUIRED</td> <td>REQUIRED</td>
</tr> </tr>
<tr>
<td>profile</td>
<td>The profile in use (e.g., "RTP/AVP" in the context of the Real-time Transport Protocol).</td>
<td>RECOMMENDED</td>
</tr>
<tr> <tr>
<td>senders</td> <td>senders</td>
<td>Which parties in the session will be generating content; the allowable values are "initiator", "responder", or "both" (where "both" is the default).</td> <td>Which parties in the session will be generating content; the allowable values are "initiator", "responder", or "both" (where "both" is the default).</td>
@ -793,6 +782,62 @@ PENDING o---------------------+ |
</tr> </tr>
</table> </table>
</section2> </section2>
<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 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 mroe 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'>
<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>
</tr>
<tr>
<td>&lt;busy/&gt;</td>
<td>The party is busy and cannot accept communications.</td>
</tr>
<tr>
<td>&lt;connectivity-error/&gt;</td>
<td>The action is related to connectivity problems.</td>
</tr>
<tr>
<td>&lt;decline/&gt;</td>
<td>The party wishes to formally decline the session.</td>
</tr>
<tr>
<td>&lt;general-error/&gt;</td>
<td>The action is related to a non-specific application error.</td>
</tr>
<tr>
<td>&lt;media-error/&gt;</td>
<td>The action is related to media processing problems.</td>
</tr>
<tr>
<td>&lt;no-error/&gt;</td>
<td>The action is generated during the normal course of state management.</td>
</tr>
<tr>
<td>&lt;success/&gt;</td>
<td>The session has been successfully completed.</td>
</tr>
<tr>
<td>&lt;unsupported-applications/&gt;</td>
<td>The party supports none of the offered application types.</td>
</tr>
<tr>
<td>&lt;unsupported-transports/&gt;</td>
<td>The party supports none of the offered transport methods.</td>
</tr>
</table>
</section2>
</section1> </section1>
<section1 topic='Error Handling' anchor='errors'> <section1 topic='Error Handling' anchor='errors'>
@ -824,17 +869,17 @@ PENDING o---------------------+ |
<section1 topic='Determining Support' anchor='support'> <section1 topic='Determining Support' anchor='support'>
<p>If an entity supports Jingle, it MUST advertise that fact by returning a feature of "urn:xmpp:tmp:jingle" &NSNOTE; in response to a &xep0030; information request. The response MUST also include features for the application formats and transport methods supported by the responding entity, as described in the relevant specifications.</p> <p>If an entity supports Jingle, it MUST advertise that fact by returning a feature of "urn:xmpp:tmp:jingle" &NSNOTE; in response to a &xep0030; information request. The response MUST also include features for the application formats and transport methods supported by the responding entity, as described in the relevant specifications.</p>
<example caption="Service Discovery Information Request"><![CDATA[ <example caption="Service Discovery Information Request"><![CDATA[
<iq from='romeo@montague.lit/orchard' <iq from='kingclaudius@shakespeare.lit/castle'
id='disco1' id='disco1'
to='juliet@capulet.lit/balcony' to='laertes@shakespeare.lit/castle'
type='get'> type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/> <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq> </iq>
]]></example> ]]></example>
<example caption="Service Discovery Information Response"><![CDATA[ <example caption="Service Discovery Information Response"><![CDATA[
<iq from='juliet@capulet.lit/balcony' <iq from='laertes@shakespeare.lit/castle'
id='disco1' id='disco1'
to='romeo@montague.lit/orchard' to='kingclaudius@shakespeare.lit/castle'
type='result'> type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'> <query xmlns='http://jabber.org/protocol/disco#info'>
... ...
@ -924,82 +969,6 @@ PENDING o---------------------+ |
</transport> </transport>
]]></code> ]]></code>
</section2> </section2>
<section2 topic='Jingle Reason Codes Registry' anchor='registrar-reasoncodes'>
<section3 topic='Process' anchor='registrar-reasoncodes-process'>
<p>The XMPP Registrar shall maintain a registry of reason codes related to Jingle actions.</p>
&REGPROCESS;
<code><![CDATA[
<reason>
<code>the value of the 'reasoncode' attribute</name>
<desc>a natural-language summary of the reason code</desc>
<doc>the document in which this reason code is specified</doc>
</reason>
]]></code>
</section3>
<section3 topic='Initial Registration' anchor='registrar-reasoncodes-reg'>
<p>The following submission registers reasoncodes currently in use. Refer to the registry itself for a complete and current list of reasoncodes.</p>
<code><![CDATA[
<reason>
<code>alternative-session</code>
<desc>
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
</desc>
<doc>XEP-0166</doc>
</reason>
<reason>
<code>busy</code>
<desc>the party is busy</desc>
<doc>XEP-0166</doc>
</reason>
<reason>
<code>decline</code>
<desc>the party wishes to formally decline the session</desc>
<doc>XEP-0166</doc>
</reason>
<reason>
<code>connectivity-error</code>
<desc>the action is related to connectivity problems</desc>
<doc>XEP-0166</doc>
</reason>
<reason>
<code>general-error</code>
<desc>the action is related to a non-specific application error</desc>
<doc>XEP-0166</doc>
</reason>
<reason>
<code>media-error</code>
<desc>the action is related to media processing problems</desc>
<doc>XEP-0166</doc>
</reason>
<reason>
<code>no-error</code>
<desc>the action is generated during the normal course of state management</desc>
<doc>XEP-0166</doc>
</reason>
<reason>
<code>unsupported-applications</code>
<desc>the party supports none of the offered application formats</desc>
<doc>XEP-0166</doc>
</reason>
<reason>
<code>unsupported-transports</code>
<desc>the party supports none of the offered transport methods</desc>
<doc>XEP-0166</doc>
</reason>
]]></code>
</section3>
</section2>
</section1> </section1>
<section1 topic='XML Schemas' anchor='schema'> <section1 topic='XML Schemas' anchor='schema'>
<section2 topic='Jingle' anchor='schema-jingle'> <section2 topic='Jingle' anchor='schema-jingle'>
@ -1014,8 +983,9 @@ PENDING o---------------------+ |
<xs:element name='jingle'> <xs:element name='jingle'>
<xs:complexType> <xs:complexType>
<xs:sequence minOccurs='1' maxOccurs='unlimited'> <xs:sequence>
<xs:element ref='content'/> <xs:element ref='content' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='reason' minOccurs='0' maxOccurs='1'/>
</xs:sequence> </xs:sequence>
<xs:attribute name='action' use='required'> <xs:attribute name='action' use='required'>
<xs:simpleType> <xs:simpleType>
@ -1024,6 +994,7 @@ PENDING o---------------------+ |
<xs:enumeration value='content-add'/> <xs:enumeration value='content-add'/>
<xs:enumeration value='content-modify'/> <xs:enumeration value='content-modify'/>
<xs:enumeration value='content-remove'/> <xs:enumeration value='content-remove'/>
<xs:enumeration value='content-replace'/>
<xs:enumeration value='session-accept'/> <xs:enumeration value='session-accept'/>
<xs:enumeration value='session-info'/> <xs:enumeration value='session-info'/>
<xs:enumeration value='session-initiate'/> <xs:enumeration value='session-initiate'/>
@ -1033,8 +1004,6 @@ PENDING o---------------------+ |
</xs:simpleType> </xs:simpleType>
</xs:attribute> </xs:attribute>
<xs:attribute name='initiator' type='xs:string' use='required'/> <xs:attribute name='initiator' type='xs:string' use='required'/>
<xs:attribute name='reasoncode' type='xs:string' use='optional'/>
<xs:attribute name='reasontext' type='xs:string' use='optional'/>
<xs:attribute name='responder' type='xs:string' use='optional'/> <xs:attribute name='responder' type='xs:string' use='optional'/>
<xs:attribute name='sid' type='xs:NMTOKEN' use='required'/> <xs:attribute name='sid' type='xs:NMTOKEN' use='required'/>
</xs:complexType> </xs:complexType>
@ -1054,7 +1023,6 @@ PENDING o---------------------+ |
</xs:simpleType> </xs:simpleType>
</xs:attribute> </xs:attribute>
<xs:attribute name='name' use='required' type='xs:string'/> <xs:attribute name='name' use='required' type='xs:string'/>
<xs:attribute name='profile' use='optional' 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'>
@ -1067,6 +1035,39 @@ PENDING o---------------------+ |
</xs:complexType> </xs:complexType>
</xs:element> </xs:element>
<xs:element name='reason'>
<xs:complexType>
<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='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='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:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema> </xs:schema>
]]></code> ]]></code>
</section2> </section2>