moparisthebest
/
xeps
mirror of https://github.com/moparisthebest/xeps
1
0
Fork 0
Code Issues Releases Wiki Activity

0.11-pre3 

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@150 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2006-10-31 22:33:53 +00:00
parent 89d17abcbe
commit 51ab061ce8
1 changed files with 53 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
xep-0166.xml
View File

@ -239,7 +239,7 @@ PENDING o---------------------+ |
| | content-remove, | |
| | content-modify, | |
| | content-accept, | |
| | content-decline, | |
| | content-decline | |
| +------------------+ |
| |
| session-accept |
@ -250,7 +250,7 @@ PENDING o---------------------+ |
| | content-remove, | |
| | content-modify, | |
| | content-accept, | |
| | content-decline, | |
| | content-decline | |
| +------------------+ |
| |
+-------------------------+
@ -268,17 +268,18 @@ PENDING o---------------------+ |
</ol>
<p>The actions related to management of the overall Jingle session are:</p>
<ol start='1'>
<li>content-accept (accept a content-add, content-modify, or content-remove; implicitly also serves as a description-accept and transport-accept)</li>
<li>content-add (add one or more new content types to the session; this MUST NOT be sent while the session is in the PENDING state)</li>
<li>content-decline (reject a content-add or content-modify)</li>
<li>content-modify (change an existing content type, mainly the directionality)</li>
<li>content-remove (remove one or more content types from the session)</li>
<li>session-accept (definitively accept a session request; implicitly also serves as a description-accept and transport-accept)</li>
<li>session-initiate (request a new Jingle session)</li>
<li>session-info (session-level information / messages)</li>
<li>session-redirect (redirect an initiate request to another address)</li>
<li>session-terminate (end an existing session)</li>
<li>content-accept</li>
<li>content-add</li>
<li>content-decline</li>
<li>content-modify</li>
<li>content-remove</li>
<li>session-accept</li>
<li>session-initiate</li>
<li>session-info</li>
<li>session-redirect</li>
<li>session-terminate</li>
</ol>
<p>These actions are defined in greater detail under <link url='#actions'>Jingle Actions</link>.</p>
</section2>
<section2 topic='Session Content' anchor='concepts-content'>
<p>The content type of a session is made up of two aspects:</p>
@ -327,11 +328,12 @@ PENDING o---------------------+ |
</ol>
<p>The actions related to management of content description formats are:</p>
<ol>
<li>description-info (description-level information / messages)</li>
<li>description-modify (request a change to a content description format)</li>
<li>description-accept (accept a proposed content change)</li>
<li>description-decline (decline a proposed content change)</li>
<li>description-accept</li>
<li>description-decline</li>
<li>description-info</li>
<li>description-modify</li>
</ol>
<p>These actions are defined in greater detail under <link url='#actions'>Jingle Actions</link>.</p>
</section3>
<section3 topic='Content Transport Methods' anchor='concepts-transport'>
<p>As with the content description formats, the content transport methods are specified in separate specifications. Possible content transport methods include Real-time Transport Protocol (RTP) with Interactive Connectivity Establishment (ICE) and raw UDP. Those specifications will also define the state chart for the content transport method in question.</p>
@ -373,23 +375,24 @@ PENDING o---------------------+ |
</ol>
<p>The actions related to management of content transport methods are:</p>
<ol>
<li>transport-info (transport-level information / messages)</li>
<li>transport-modify (request a change to the content transport methods)</li>
<li>transport-accept (accept a proposed transport change)</li>
<li>transport-decline (decline a proposed transport change)</li>
<li>transport-accept</li>
<li>transport-decline</li>
<li>transport-info</li>
<li>transport-modify</li>
</ol>
<p>These actions are defined in greater detail under <link url='#actions'>Jingle Actions</link>.</p>
</section3>
</section2>
</section1>
<section1 topic='Protocol' anchor='protocol'>
<section2 topic='Resource Determination' anchor='protocol-resource'>
<p>In order to initiate a Jingle session, the initiating entity must determine which of the target entity's XMPP resources is best for the desired content description format. If a contact has only one XMPP resource, this task MUST be completed using &xep0030; or the presence-based profile of service discovery specified in &xep0115;.</p>
<p>In order to initiate a Jingle session, the initiating entity must determine which of the receiver's XMPP resources is best for the desired content description format. If a contact has only one XMPP resource, this task MUST be completed using &xep0030; or the presence-based profile of service discovery specified in &xep0115;.</p>
<p>Naturally, instead of sending service discovery requests to every contact in a user's roster, it is more efficient to use <cite>Entity Capabilities</cite>, whereby support for Jingle and various Jingle content description formats and content transport methods is determined for a client version in general (rather than on a per-JID basis) and then cached. Refer to <cite>XEP-0115</cite> for details.</p>
<p>If a contact has more than one XMPP resource, it may be that only one of the resources supports Jingle and the desired content description format, in which case the user MUST initiate the Jingle signalling with that resource.</p>
<p>If a contact has more than one XMPP resource that supports Jingle and the desired content description format, it is RECOMMENDED for a client to use &xep0168; in order to determine which is the best resource with which to initiate the desired Jingle session.</p>
</section2>
<section2 topic='Initiation' anchor='protocol-initiate'>
<p>Once the initiating entity has discovered which of the target entity's XMPP resources is ideal for the desired content description format, it sends a session initiation request to the target entity. This request is an IQ-set containing a &JINGLE; element qualified by the 'http://jabber.org/protocol/jingle' namespace. The &JINGLE; element MUST possess the 'action', 'initiator', and 'sid' attributes (the latter two uniquely identify the session). For initiation, the 'action' attribute MUST have a value of "session-initiate" and the &JINGLE; element MUST contain one or more &CONTENT; elements, each of which defines a content type to be transferred during the session; each &CONTENT; element in turn contains one &DESCRIPTION; child element that specifies a desired content description format and one or more &TRANSPORT; child elements that specify potential content transport methods.</p>
<p>Once the initiating entity has discovered which of the receiver's XMPP resources is ideal for the desired content description format, it sends a session initiation request to the receiver. This request is an IQ-set containing a &JINGLE; element qualified by the 'http://jabber.org/protocol/jingle' namespace. The &JINGLE; element MUST possess the 'action', 'initiator', and 'sid' attributes (the latter two uniquely identify the session). For initiation, the 'action' attribute MUST have a value of "session-initiate" and the &JINGLE; element MUST contain one or more &CONTENT; elements, each of which defines a content type to be transferred during the session; each &CONTENT; element in turn contains one &DESCRIPTION; child element that specifies a desired content description format and one or more &TRANSPORT; child elements that specify potential content transport methods.</p>
<p>The following example shows a Jingle session initiation request for a session that contains both audio and video content:</p>
<example caption="Initiation Example"><![CDATA[
<iq to='juliet@capulet.com/balcony' from='romeo@montague.net/orchard' id='jingle1' type='set'>
@ -436,38 +439,38 @@ PENDING o---------------------+ |
<li>The 'senders' attribute specifies which entities in the session will be generating content; the allowable values are "initiator", "recipient", or "both" (where "both" is the default).</li>
</ul>
</section2>
<section2 topic='Target Entity Response' anchor='protocol-response'>
<p>Unless an error occurs, the target entity MUST acknowledge receipt of the initiation request:</p>
<example caption="Target Entity Acknowledges Receipt of Initiation Request"><![CDATA[
<section2 topic='Receiver Response' anchor='protocol-response'>
<p>Unless an error occurs, the receiver MUST acknowledge receipt of the initiation request:</p>
<example caption="Receiver Acknowledges Receipt of Initiation Request"><![CDATA[
<iq type='result' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'/>
]]></example>
<p>If the target entity acknowledges receipt of the initation request, both parties must consider the session to be in the PENDING state.</p>
<p>There are several reasons why the target entity might return an error instead of acknowledging receipt of the initiation request:</p>
<p>If the receiver acknowledges receipt of the initation request, both parties must consider the session to be in the PENDING state.</p>
<p>There are several reasons why the receiver might return an error instead of acknowledging receipt of the initiation request:</p>
<ul>
<li>The initiating entity is unknown to the target entity (e.g., via presence subscription).</li>
<li>The target entity does not support Jingle.</li>
<li>The target entity does not support any of the specified content description formats.</li>
<li>The target entity does not support any of the specified content transport methods.</li>
<li>The initiating entity is unknown to the receiver (e.g., via presence subscription).</li>
<li>The receiver does not support Jingle.</li>
<li>The receiver does not support any of the specified content description formats.</li>
<li>The receiver does not support any of the specified content transport methods.</li>
<li>The initiation request was malformed.</li>
</ul>
<p>The initiating entity is unknown to the target entity (e.g., via presence subscription) and the target entity has a policy of not communicating via Jingle with unknown entities, it MUST return a &unavailable; error.</p>
<example caption="Initiating Entity Unknown to Target Entity"><![CDATA[
<p>The initiating entity is unknown to the receiver (e.g., via presence subscription) and the receiver has a policy of not communicating via Jingle with unknown entities, it MUST return a &unavailable; error.</p>
<example caption="Initiating Entity Unknown to Receiver"><![CDATA[
<iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'>
<error type='cancel'>
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>If the target entity does not support Jingle, it MUST return a &unavailable; error.</p>
<example caption="Target Entity Does Not Support Jingle"><![CDATA[
<p>If the receiver does not support Jingle, it MUST return a &unavailable; error.</p>
<example caption="Receiver Does Not Support Jingle"><![CDATA[
<iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'>
<error type='cancel'>
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>If the target entity does not support any of the specified content description formats, it MUST return a &feature; error with a Jingle-specific error condition of &lt;unsupported-content/&gt;.</p>
<example caption="Target Entity Does Not Support Any Content Description Formats"><![CDATA[
<p>If the receiver does not support any of the specified content description formats, it MUST return a &feature; error with a Jingle-specific error condition of &lt;unsupported-content/&gt;.</p>
<example caption="Receiver Does Not Support Any Content Description Formats"><![CDATA[
<iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'>
<error type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@ -475,8 +478,8 @@ PENDING o---------------------+ |
</error>
</iq>
]]></example>
<p>If the target entity does not support any of the specified content transport methods, it MUST return a &feature; error with a Jingle-specific error condition of &lt;unsupported-transports/&gt;.</p>
<example caption="Target Entity Does Not Support Any Transport Methods"><![CDATA[
<p>If the receiver does not support any of the specified content transport methods, it MUST return a &feature; error with a Jingle-specific error condition of &lt;unsupported-transports/&gt;.</p>
<example caption="Receiver Does Not Support Any Transport Methods"><![CDATA[
<iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'>
<error type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
@ -484,7 +487,7 @@ PENDING o---------------------+ |
</error>
</iq>
]]></example>
<p>If the initiation request was malformed, the target entity MUST return a &badrequest; error.</p>
<p>If the initiation request was malformed, the receiver MUST return a &badrequest; error.</p>
<example caption="Initiation Request Malformed"><![CDATA[
<iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle1'>
<error type='cancel'>
@ -494,8 +497,8 @@ PENDING o---------------------+ |
]]></example>
</section2>
<section2 topic='Redirection' anchor='protocol-redirect'>
<p>After acknowledging receipt of the initiation request, the target entity MAY redirect the session to another address (e.g., because the principal is not answering at the original resource). This is done by sending a Jingle redirect action to the initiating entity:</p>
<example caption="Target Entity Redirects the Session"><![CDATA[
<p>After acknowledging receipt of the initiation request, the receiver MAY redirect the session to another address (e.g., because the principal is not answering at the original resource). This is done by sending a Jingle redirect action to the initiating entity:</p>
<example caption="Receiver Redirects the Session"><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='jingle2'
to='romeo@montague.net/orchard'
@ -519,7 +522,7 @@ PENDING o---------------------+ |
<p>Both entities MUST now consider the original session to be in the ENDED state, and if the initiating entity wishes to initiate a session with the redirected address it MUST do so by sending a session initiation request to that address with a new session ID.</p>
</section2>
<section2 topic='Decline' anchor='protocol-decline'>
<p>In order to decline the session initiation request, the target entity MUST acknowledge receipt of the session initiation request, then terminate the session as described in the <link url='#protocol-terminate'>Termination</link> section of this document.</p>
<p>In order to decline the session initiation request, the receiver MUST acknowledge receipt of the session initiation request, then terminate the session as described in the <link url='#protocol-terminate'>Termination</link> section of this document.</p>
</section2>
<section2 topic='Negotiation' anchor='protocol-negotiation'>
<p>In general, negotiation will be necessary before the parties can agree on an acceptable set of content types, content description formats, and content transport methods. The potential combinations of parameters to be negotiated are many, and not all are shown herein (some are shown in the relevant specifications for various content description formats and content transport methods).</p>
@ -542,8 +545,8 @@ PENDING o---------------------+ |
<p>Another session-level negotiation is to <em>add</em> a content type; however, this MUST NOT be done during while the session is in the PENDING state and is allowed only while the session is in the ACTIVE state (see below).</p>
</section2>
<section2 topic='Acceptance' anchor='protocol-acceptance'>
<p>If (after negotiation of content transport methods and content description formats) the target entity determines that it will be able to establish a connection, it sends a definitive acceptance to the initiating entity:</p>
<example caption="Target Entity Definitively Accepts the Call"><![CDATA[
<p>If (after negotiation of content transport methods and content description formats) the receiver determines that it will be able to establish a connection, it sends a definitive acceptance to the initiating entity:</p>
<example caption="Receiver Definitively Accepts the Call"><![CDATA[
<iq type='set' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='accept1'>
<jingle xmlns='http://jabber.org/protocol/jingle'
action='session-accept'
@ -575,11 +578,11 @@ PENDING o---------------------+ |
</iq>
]]></example>
<p>The &JINGLE; element in the accept stanza MUST contain one or more &lt;content/&gt; elements, each of which MUST contain only one &lt;description/&gt; element and one or more &lt;transport/&gt; elements. The &JINGLE; element SHOULD possess a 'responder' attribute that explicitly specifies the full JID of the responding entity, and the initiating entity SHOULD send all future commmunications about this Jingle session to the JID provided in the 'responder' attribute.</p>
<p>The initiating entity then acknowledges the target entity's definitive acceptance:</p>
<p>The initiating entity then acknowledges the receiver's definitive acceptance:</p>
<example caption="Initiating Entity Acknowledges Definitive Acceptance"><![CDATA[
<iq type='result' to='juliet@capulet.com/balcony' from='romeo@montague.net/orchard' id='accept1'/>
]]></example>
<p>Now the initiating entity and target entity can begin sending content over the negotiated connection.</p>
<p>Now the initiating entity and receiver can begin sending content over the negotiated connection.</p>
<p>If one of the parties cannot find a suitable content transport method, it SHOULD terminate the session as described below.</p>
</section2>
<section2 topic='Modifying an Active Session' anchor='protocol-modify'>
@ -636,8 +639,8 @@ PENDING o---------------------+ |
]]></example>
</section2>
<section2 topic='Termination' anchor='protocol-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 target entity or the initiating entity MUST a send a "terminate" action to the other party:</p>
<example caption="Target Entity Terminates the Session"><![CDATA[
<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 receiver or the initiating entity MUST a send a "terminate" action to the other party:</p>
<example caption="Receiver Terminates the Session"><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='term1'
to='romeo@montague.net/orchard'
@ -658,7 +661,7 @@ PENDING o---------------------+ |
<li>Receipt of &UNAVAILABLE; from the other party.</li>
</ul>
<p>In particular, one party MUST consider the session to be in the ENDED state if it receives presence of type "unavailable" from the other party:</p>
<example caption="Target Entity Goes Offline"><![CDATA[
<example caption="Receiver Goes Offline"><![CDATA[
<presence from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' type='unavailable'/>
]]></example>
<p>Naturally, in this case there is nothing for the initiating entity to acknowledge.</p>