From 828ca33f2d10de49af5a0b886f0f243926b9bfc1 Mon Sep 17 00:00:00 2001 From: Peter Saint-Andre Date: Fri, 29 Feb 2008 03:17:16 +0000 Subject: [PATCH] 0.24 git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1706 4b5297f7-1745-476d-ba37-a9c6900126ab --- xep-0166.xml | 435 ++++++++++++++++++++++++++------------------------- 1 file changed, 218 insertions(+), 217 deletions(-) diff --git a/xep-0166.xml b/xep-0166.xml index c9574e35..bb39edea 100644 --- a/xep-0166.xml +++ b/xep-0166.xml @@ -26,6 +26,12 @@ &robmcqueen; &seanegan; &hildjj; + + 0.24 + 2008-02-28 + ram/psa +

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.

 + 0.23 2008-01-11 @@ -254,93 +260,63 @@ Romeo Juliet | | ]]>

Naturally, more complex scenarios are probable; such scenarios are described in other specifications, such as XEP-0167 for voice chat.

-

The simplest flow might happen as follows. The example is that of a voice chat (see XEP-0167) initiated by Romeo, where the transport is &xep0177;.

+

The simplest flow might happen as follows. The example is that of a file transfer offer, where the transport method is &xep0065;.

- - - - - - - + initiator='kingclaudius@shakespeare.lit/castle' + sid='851ba2'> + + + + + This is a test. If this were a real file... + + - - - + ]]> - The responder immediately acknowledges receipt of the session-initiate.

+ ]]> -

If the proposed session is acceptable, the responder definitively accepts it.

- - - - - - - - - - - - - - - - - - - ]]> -

The initiator then acknowledges the session-accept action.

- - ]]> -

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

-

The parties may continue the session as long as desired.

-

Eventually, one of the parties terminates the session.

+

The parties would then attempt to negotiate use of the SOCKS5 Bytestreams transport method, as described in XEP-0065.

+

Once the file transfer succeeds, one of the parties terminates the session.

+ initiator='kingclaudius@shakespeare.lit/castle' + sid='a73sjjvkla37jfea'> + + + + + ]]> -

The other party MUST then acknowledge termination of the session.

+

The other party then acknowledges termination of the session.

]]> @@ -442,6 +418,7 @@ PENDING o---------------------+ | | | content-add, | | | | content-modify, | | | | content-remove, | | + | | content-replace, | | | | session-info, | | | | transport-info | | | +------------------+ | @@ -480,6 +457,10 @@ PENDING o---------------------+ | content-remove 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. The recipient SHOULD NOT send a content-accept with the new content type definition after receiving a content-remove. 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. 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). + + content-replace + 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. + session-accept Definitively accept a session negotiation (implicitly this action also serves as a content-accept). @@ -513,9 +494,9 @@ PENDING o---------------------+ |

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 Formal Definition.

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 <unknown-session/> errors since according to its state machine the session does not exist).

@@ -528,12 +509,12 @@ PENDING o---------------------+ |

Unless one of the following errors occurs, the responder SHOULD acknowledge receipt of the initiation request.

]]> -

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 Termination section of this document.

+

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 Termination section of this document.

If the responder acknowledges receipt of the initation request, both parties must consider the session to be in the PENDING state.

 @@ -547,9 +528,9 @@ PENDING o---------------------+ |

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.

@@ -558,9 +539,9 @@ PENDING o---------------------+ | ]]>

If the responder does not support Jingle, it MUST return a &unavailable; error.

@@ -569,9 +550,9 @@ PENDING o---------------------+ | ]]>

If the responder wishes to redirect the request to another address, it SHOULD return a &redirect; error.

@@ -582,9 +563,9 @@ PENDING o---------------------+ | ]]>

If the responder does not have sufficient resources to participate in a session, it SHOULD return a &constraint; error.

@@ -593,9 +574,9 @@ PENDING o---------------------+ | ]]>

If the initiation request was malformed, the responder MUST return a &badrequest; error.

@@ -625,90 +606,113 @@ PENDING o---------------------+ |

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.

-

The party that terminates the session SHOULD include a 'reasoncode' attribute that specifies why the session is being terminated. Examples follow.

-

One reason for terminating the session is that the terminating party is busy; in this case, the recommended reasoncode is "busy".

+

The party that terminates the session SHOULD include a <reason/> element that specifies why the session is being terminated. Examples follow.

+

One reason for terminating the session is that the terminating party is busy; in this case, the recommended condition is "busy".

+ initiator='kingclaudius@shakespeare.lit/castle' + sid='a73sjjvkla37jfea'> + + + ]]> -

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

+

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

+ initiator='kingclaudius@shakespeare.lit/castle' + sid='a73sjjvkla37jfea'> + + + ]]> -

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.

+

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 <sid/> element.

- sid='a73sjjvkla37jfea'/> + initiator='kingclaudius@shakespeare.lit/castle' + sid='a73sjjvkla37jfea'> + + + b84tkkwlmb48kgfb + ]]> -

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

+

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

+ initiator='kingclaudius@shakespeare.lit/castle' + sid='a73sjjvkla37jfea'> + + + ]]> -

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

+

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

+ initiator='kingclaudius@shakespeare.lit/castle' + sid='a73sjjvkla37jfea'> + + + ]]>

Upon receiving an action of "session-terminate", the other party MUST then acknowledge termination of the session:

]]>

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 <unknown-session/> error.

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.

 -

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.

+

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.

+ + + + + + ]]>

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 <unsupported-info/>.

@@ -741,16 +745,6 @@ PENDING o---------------------+ | The full JID of the entity that has initiated the session flow (which may be different from the 'from' address on the IQ-set). REQUIRED - - reasoncode - A machine-readable purpose for the action being sent (e.g., "connectivity-error" for a session-terminate action). - OPTIONAL - - - reasontext - A human-readable purpose for the action being sent (e.g., "Sorry, gotta go!" for a session-terminate action). - OPTIONAL - responder The full JID of the entity that has replied to the initiation, which may be different from the 'to' address on the IQ-set. @@ -781,11 +775,6 @@ PENDING o---------------------+ | A unique name or identifier for the content type (this identifier is opaque and does not have semantic meaning). REQUIRED - - profile - The profile in use (e.g., "RTP/AVP" in the context of the Real-time Transport Protocol). - RECOMMENDED - senders Which parties in the session will be generating content; the allowable values are "initiator", "responder", or "both" (where "both" is the default). @@ -793,6 +782,62 @@ PENDING o---------------------+ | + +

The structure of the <reason/> element is as follows.

+
    +
  • The <reason/> element MUST contain a <condition/> element that provides machine-readable information about the reason for the action.
    • +
  • The <reason/> element MAY contain a <sid/> element that specifies a Jingle SessionID (e.g., to point to an alternative session).
    • +
  • The <reason/> element MAY contain a <text/> element that provides human-readable information about the reason for the action.
    • +
  • The <reason/> element MAY contain an element qualified by some other namespace that provides mroe detailed machine-readable information about the reason for the action.
    • +
+

The defined conditions are described in the folloiwing table.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementDescription
<alternative-session/>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.
<busy/>The party is busy and cannot accept communications.
<connectivity-error/>The action is related to connectivity problems.
<decline/>The party wishes to formally decline the session.
<general-error/>The action is related to a non-specific application error.
<media-error/>The action is related to media processing problems.
<no-error/>The action is generated during the normal course of state management.
<success/>The session has been successfully completed.
<unsupported-applications/>The party supports none of the offered application types.
<unsupported-transports/>The party supports none of the offered transport methods.
+ @@ -824,17 +869,17 @@ PENDING o---------------------+ |

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.

]]> ... @@ -924,82 +969,6 @@ PENDING o---------------------+ | ]]> - - -

The XMPP Registrar shall maintain a registry of reason codes related to Jingle actions.

- ®PROCESS; - - the value of the 'reasoncode' attribute - a natural-language summary of the reason code - the document in which this reason code is specified - - ]]> - - -

The following submission registers reasoncodes currently in use. Refer to the registry itself for a complete and current list of reasoncodes.

- - alternative-session - - 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 - - XEP-0166 - - - - busy - the party is busy - XEP-0166 - - - - decline - the party wishes to formally decline the session - XEP-0166 - - - - connectivity-error - the action is related to connectivity problems - XEP-0166 - - - - general-error - the action is related to a non-specific application error - XEP-0166 - - - - media-error - the action is related to media processing problems - XEP-0166 - - - - no-error - the action is generated during the normal course of state management - XEP-0166 - - - - unsupported-applications - the party supports none of the offered application formats - XEP-0166 - - - - unsupported-transports - the party supports none of the offered transport methods - XEP-0166 - - ]]> - - @@ -1014,8 +983,9 @@ PENDING o---------------------+ | - - + + + @@ -1024,6 +994,7 @@ PENDING o---------------------+ | + @@ -1033,8 +1004,6 @@ PENDING o---------------------+ | - - @@ -1054,7 +1023,6 @@ PENDING o---------------------+ | - @@ -1067,6 +1035,39 @@ PENDING o---------------------+ | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]>