From 50180e35a77ffef640f207bbdd9d519a726fdde8 Mon Sep 17 00:00:00 2001 From: Peter Saint-Andre Date: Thu, 8 Nov 2007 22:36:51 +0000 Subject: [PATCH] 0.18 git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1364 4b5297f7-1745-476d-ba37-a9c6900126ab --- xep-0166.xml | 216 +++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 184 insertions(+), 32 deletions(-) diff --git a/xep-0166.xml b/xep-0166.xml index 85a44d0f..fdcebf27 100644 --- a/xep-0166.xml +++ b/xep-0166.xml @@ -27,10 +27,10 @@ &seanegan; &hildjj; - 0.18pre1 - in progress, last updated 2007-11-02 + 0.18 + 2007-11-08 psa -

Added scenarios containing more examples.

 +

Added scenarios for various session flows; clarified handling of content-add, content-modify, and content-remove actions; clarified rules for codec priority.

 0.17 @@ -231,7 +231,7 @@ Romeo Juliet action='session-initiate' initiator='romeo@montague.lit/orchard' sid='a73sjjvkla37jfea'> - + @@ -259,7 +259,7 @@ Romeo Juliet initiator='romeo@montague.lit/orchard' responder='juliet@capulet.lit/balcony' sid='a73sjjvkla37jfea'> - + @@ -276,8 +276,9 @@ Romeo Juliet ]]> -

If the foregoing payload types and transport candidates can be successfully used, then the parties would begin to exchange media (in this case audio).

-

The parties may continue the session as long as desired. Either party may terminate the session.

+

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

+

The parties may continue the session as long as desired.

+

Eventually, one of the parties terminates the session.

content-add - 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. 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. + 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. 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. content-modify - Change an existing content type. The recipient MUST NOT reply to a content-modify action with another content-modify action. 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. + 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 <content/> element with a modified value for the 'profile' attribute; if the wishes to change only the transport, then it would send a <content/> element that contains only a <transport/> 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. 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. content-remove - Remove one or more content types from the session. 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. 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). + 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. 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. 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). session-accept - 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). + Definitively accept a session negotiation (implicitly this action also serves as a content-accept). session-info @@ -565,7 +566,7 @@ PENDING o---------------------+ |

The very simple scenario described in the How It Works 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.

- +

In this scenario, Romeo initiates a voice chat with Juliet using a transport method of ICE-UDP.

The session flow is as follows:

- + @@ -625,7 +626,7 @@ Romeo Juliet action='transport-info' initiator='romeo@montague.lit/orchard' sid='a73sjjvkla37jfea'> - + - + - + - + @@ -732,12 +733,14 @@ Romeo Juliet ]]> -

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

+

If the payload types and transport candidate can be successfully used by both parties, then the initiator acknowledges the session-accept.

]]> -

The parties may continue the session as long as desired. Either party may terminate the session.

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

+

The parties may continue the session as long as desired.

+

Eventually, one of the parties terminates the session.

+ ]]> - +

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.

The session flow is as follows:

- + @@ -817,7 +820,7 @@ Romeo Juliet - + @@ -837,13 +840,13 @@ Romeo Juliet ]]>

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.

- - + ]]> @@ -857,7 +860,7 @@ Romeo Juliet action='content-accept' initiator='romeo@montague.lit/orchard' sid='a73sjjvkla37jfea'> - + @@ -877,7 +880,7 @@ Romeo Juliet initiator='romeo@montague.lit/orchard' responder='juliet@capulet.lit/balcony' sid='a73sjjvkla37jfea'> - + @@ -894,10 +897,11 @@ Romeo Juliet ]]> -

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

+

As above, if the payload types and transport candidate can be successfully used by both parties, then the initiator acknowledges the session-accept.

]]> +

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

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.

@@ -905,7 +909,7 @@ Romeo Juliet action='content-add' initiator='romeo@montague.lit/orchard' sid='a73sjjvkla37jfea'> - + @@ -930,9 +934,15 @@ Romeo Juliet action='content-accept' initiator='romeo@montague.lit/orchard' sid='a73sjjvkla37jfea'> - + - ... + + + + + + + @@ -943,7 +953,8 @@ Romeo Juliet ]]> -

The media session proceeds, this time with both audio and video.

+

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.

+

The parties may continue the session as long as desired.

Eventually, one of the parties terminates the session.

]]> + +

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").

+

The session flow is as follows:

+ | + | ack | + |<----------------------------| + | content-modify | + |<----------------------------| + | ack | + |---------------------------->| + | content-accept | + |---------------------------->| + | ack | + |<----------------------------| + | transport-info (X times) | + | (with acks) | + |<--------------------------->| + | session-accept | + |<----------------------------| + | ack | + |---------------------------->| + | AUDIO (RTP) | + |<===========================>| + | session-terminate | + |<----------------------------| + | ack | + |---------------------------->| + | | + ]]> +

The protocol flow is as follows.

+ + + + + + + + + + + + + + + ]]> + + ]]> +

However, Juliet wants to make sure that the communications are encrypted, so she sends a "content-modify" request to Romeo.

+ + + + + + ]]> +

Romeo then acknowledges the content-modify request and, if it is acceptable, returns a content-accept:

+ + ]]> + + + + + + ]]> +

The other party then acknowledges the acceptance.

+ + ]]> +

As in Scenario #1, the parties exchange ICE candidates (see above for examples).

+

If one of the candidate transports is found to work, the receiver accepts the session.

+ + + + + + + + + + + + + + + + + + + ]]> +

If the payload types and transport candidate can be successfully used by both parties, then the initiator acknowledges the session-accept.

+ + ]]> +

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

+

The parties may continue the session as long as desired.

+

Eventually, one of the parties terminates the session.

+ + + + ]]> +

The other party MUST then acknowledge termination of the session:

+ + ]]> +