From aaed812202b04d9e82496b4b6a1a941a30493706 Mon Sep 17 00:00:00 2001 From: Peter Saint-Andre Date: Tue, 20 Nov 2007 17:18:17 +0000 Subject: [PATCH] copy edit git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1405 4b5297f7-1745-476d-ba37-a9c6900126ab --- xep-0166.xml | 177 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 106 insertions(+), 71 deletions(-) diff --git a/xep-0166.xml b/xep-0166.xml index 2ce5751f..3e120b4f 100644 --- a/xep-0166.xml +++ b/xep-0166.xml @@ -238,7 +238,10 @@ 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 happens as follows. The example is that of a voice chat (see XEP-0167) initiated by Romeo, where the transport is &xep0177;.

+ ]]> - ]]> +

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

+ ]]> -

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 initiator then acknowledges the session-accept message.

+ + ]]> +

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.

When a peer-to-peer connection cannot be negotiated, make it possible to fall back to relayed communications.
  • Clearly separate the signalling channel (XMPP) from the data channel.
  • Clearly separate the application formats (e.g., video) from the transport methods (e.g., RTP).
    • -
  • Make it possible to add, modify, and remove both media types and transport methods in relation to an existing session.
    • +
  • Make it possible to add, modify, and remove both application types and transport methods in relation to an existing session.
  • Make it relatively easy to implement support for the protocol in standard Jabber/XMPP clients.
  • Where communication with non-XMPP entities is needed, push as much complexity as possible onto server-side gateways between the XMPP network and the non-XMPP network.

    • This document defines the signalling protocol only. Additional documents specify the following:

    @@ -374,14 +388,14 @@ Romeo Juliet
  • Application types (the "what")
  • Transport methods (the "how")
    • -

    This document defines the semantics and syntax for overall session management. It also provides pluggable "slots" for application formats and transport methods, which are specified in separate documents; however, for the sake of completeness, this document also includes examples for all actions related to application formats and transport methods.

    +

    This document defines the semantics and syntax for overall session management. It also provides pluggable "slots" for application formats and transport methods, which are specified in separate documents.

    At the most basic level, the process for negotiating a Jingle session is as follows:

      -
    1. One user (the "initator") sends to another user (the "receiver") a session request with at least one content type.
      2. -
    2. If the receiver wants to proceed, it provisionally accepts the request by sending an IQ result.
      3. -
    3. Both the initiator and receive start exchanging possible transport candidates as quickly as possible (these are sent in quick succession before further negotiation in order to minimize the time required before media data can flow).
      4. +
    4. One user (the "initator") sends to another user (the "responder") a session request with at least one content type.
      5. +
    5. If the responder wants to proceed, it provisionally accepts the request by sending an IQ result.
      6. +
    6. Both the initiator and responder start exchanging possible transport candidates as quickly as possible (these are sent in quick succession before further negotiation in order to minimize the time required before media data can flow).
    7. These candidates are checked for connectivity.
      8. -
    8. As soon as the receiver finds a candidate over which media can flow, the receiver sends to the initiator a "session-accept" action.
      9. +
    9. As soon as the responder finds a candidate over which media can flow, the responder sends to the initiator a "session-accept" action.
    10. The parties start sending media over the negotiated candidate.

    If the parties later discover a better candidate, they perform a "content-modify" negotiation and then switch to the better candidate. Naturally they can also modify various other parameters related to the session (e.g., adding video to a voice chat).

    @@ -437,15 +451,15 @@ PENDING o---------------------+ | content-add - 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 type 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. + 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 current content type 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 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 type 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. + Change an existing content type. The sender SHOULD specify only the aspects for which a modification is desired (e.g., if a party wishes to change only the profile then it would send an empty <content/> element with a modified value for the 'profile' attribute; if a party 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 current content type 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. 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 type definition. 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 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 current content type definition. 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). session-accept @@ -473,7 +487,7 @@ PENDING o---------------------+ |

    This section defines the high-level flow of a Jingle session. More detailed descriptions are provided in the specifications for Jingle application formats and transport methods.

    -

    In order to initiate a Jingle session, the initiator must determine which of the receiver's XMPP resources is best for the desired application format. There are several possible scenarios:

    +

    In order to initiate a Jingle session, the initiator must determine which of the responder's XMPP resources is best for the desired application format. There are several possible scenarios:

    1. If the intended responder shares presence with the initiator (see &xmppim;) and has only one available resource, the initiator SHOULD attempt to negotiate a Jingle session with that resource unless the initiator knows via &xep0030; or &xep0115; that the resource does not support Jingle and the desired application format. Naturally, instead of sending service discovery requests to every contact in a user's roster, it is more efficient to use Entity Capabilities, whereby support for Jingle and various Jingle application formats and transport methods is determined for a client version in general (rather than on a per-JID basis) and then cached. Refer to XEP-0115 for details.

    2. If the intended responder shares presence with the initiator and has more than one available resource but only one of the resources supports Jingle and the desired application format, the initiator SHOULD initiate the Jingle session with that resource.

      3. @@ -482,78 +496,99 @@ PENDING o---------------------+ |
    -

    Once the initiator has discovered which of the receiver's XMPP resources is ideal for the desired application format, it sends a session initiation request to the receiver. This request is an IQ-set containing a &JINGLE; element qualified by the 'http://www.xmpp.org/extensions/xep-0166.html#ns' namespace &NSNOTE;, where the value of the 'action' attribute is "session-initiate" and where the &JINGLE; element contains one or more &CONTENT; elements. Each &CONTENT; element defines a content type to be transferred during the session, and each &CONTENT; element in turn contains one &DESCRIPTION; child element that specifies a desired application format and one &TRANSPORT; child element that specifies a potential transport method. If either party wishes to propose the use of multiple transport methods for the same application format, it must send multiple &CONTENT; elements.

    +

    Once the initiator has discovered which of the responder's XMPP resources is ideal for the desired application format, it sends a session initiation request to the responder. This request is an IQ-set containing a &JINGLE; element qualified by the 'http://www.xmpp.org/extensions/xep-0166.html#ns' namespace &NSNOTE;, where the value of the 'action' attribute is "session-initiate" and where the &JINGLE; element contains one or more &CONTENT; elements. Each &CONTENT; element defines a content type to be transferred during the session, and each &CONTENT; element in turn contains one &DESCRIPTION; child element that specifies a desired application format and one &TRANSPORT; child element that specifies a potential transport method. If either party wishes to propose the use of multiple transport methods for the same application format, it must send multiple &CONTENT; elements.

    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 receiver (i.e., the initiator MUST consider the session to be live even before receiving acknowledgement). Given in-order delivery, the receiver should receive such "transport-info" messages after receiving the "session-initiate" message (if not, it is appropriate for the receiver to return <unknown-session/> errors since it according to its state machine the session does not exist).

    +

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

     -

    Unless an error occurs, the receiver MUST acknowledge receipt of the initiation request.

    -

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

    -

    There are several reasons why the receiver might return an error instead of acknowledging receipt of the initiation request:

    +

    Unless an error occurs, the responder MUST acknowledge receipt of the initiation request.

    +

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

    +

    There are several reasons why the responder might return an error instead of acknowledging receipt of the initiation request:

      -
    • The initiator is unknown to the receiver (e.g., via presence subscription or stanza session negotiation) and the receiver does not communicate with unknown entities.
      • -
    • The receiver does not support Jingle.
      • -
    • The receiver wishes to redirect the request to another address.
      • -
    • The receiver is busy and therefore cannot participate in a session.
      • -
    • The receiver does not support any of the specified application formats.
      • -
    • The receiver does not support any of the specified transport methods.
      • +
    • The initiator is unknown to the responder (e.g., via presence subscription or stanza session negotiation) and the responder does not communicate with unknown entities.
      • +
    • The responder does not support Jingle.
      • +
    • The responder wishes to redirect the request to another address.
      • +
    • The responder is busy and therefore cannot participate in a session.
      • +
    • The responder does not support any of the specified application formats.
      • +
    • The responder does not support any of the specified transport methods.
    • The initiation request was malformed.
    -

    If the initiator is unknown to the receiver (e.g., via presence subscription or stanza session negotiation) and the receiver has a policy of not communicating via Jingle with unknown entities, it SHOULD return a &unavailable; error.

    - +

    If the initiator is unknown to the responder (e.g., via presence subscription or stanza session negotiation) and the responder has a policy of not communicating via Jingle with unknown entities, it SHOULD return a &unavailable; error.

    + ]]> -

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

    - +

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

    + ]]> -

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

    - +

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

    + - xmpp:voicemail@capulet.lit + voicemail@capulet.lit ]]> -

    If the receiver is busy, it SHOULD return a &recipient; error along with a Jingle-specific error condition of <busy/>.

    - +

    If the responder is busy, it SHOULD return a &recipient; error along with a Jingle-specific error condition of <busy/>.

    + ]]> -

    If the receiver does not support any of the specified application formats, it MUST return a &feature; error with a Jingle-specific error condition of <unsupported-content/>.

    - +

    If the responder does not support any of the specified application formats, it MUST return a &feature; error with a Jingle-specific error condition of <unsupported-content/>.

    + ]]> -

    If the receiver does not support any of the specified transport methods, it MUST return a &feature; error with a Jingle-specific error condition of <unsupported-transports/>.

    - +

    If the responder does not support any of the specified transport methods, it MUST return a &feature; error with a Jingle-specific error condition of <unsupported-transports/>.

    + ]]> -

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

    - +

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

    + @@ -561,10 +596,10 @@ PENDING o---------------------+ | ]]>     -

    In order to formally decline the session initiation request, the receiver MUST acknowledge receipt of the session initiation request, then terminate the session as described under Termination.

    +

    In order to formally decline the session initiation request, the responder MUST acknowledge receipt of the session initiation request, then terminate the session as described under Termination.

     -

    In general, negotiation will be necessary before the parties can agree on an acceptable set of content types, application formats, and transport methods. There are many potential parameter combinations, as defined in the relevant specifications for various application formats and transport methods.

    +

    In general, negotiation will be necessary before the parties can agree on an acceptable set of application formats and transport methods. There are many potential parameter combinations, as defined in the relevant specifications for various application formats and transport methods.

    The allowable negotiations (including content-level and transport-level negotiations) are as follows:

    • Adding a content type via the content-add action (not allowed in the PENDING state).
      • @@ -574,25 +609,25 @@ PENDING o---------------------+ |
    -

    If (after negotiation of transport methods and application formats as well as checking of transport candidates) the receiver determines that it will be able to establish a connection, it sends a definitive acceptance to the initiator.

    +

    If (after negotiation of transport methods and application formats as well as checking of transport candidates) the responder determines that it will be able to establish a connection, it sends a definitive acceptance to the initiator.

    Note: In the accept stanza, the &JINGLE; element MUST contain one or more <content/> elements, each of which MUST contain one <description/> element and one <transport/> element. The &JINGLE; element SHOULD possess a 'responder' attribute that explicitly specifies the full JID of the responding entity, and the initiator SHOULD send all future commmunications about this Jingle session to the JID provided in the 'responder' attribute.

    -

    The initiator then acknowledges the receiver's definitive acceptance, after which the parties can exchange media over the negotiated connection.

    +

    The initiator then acknowledges the responder's definitive acceptance, after which the parties can exchange media over the negotiated connection.

    If one of the parties cannot find a suitable transport method or candidate, it SHOULD terminate the session as described below.

    Once a session is in the ACTIVE state, it may be modified via a content-add, content-modify, or content-remove action. Examples of such modifications are shown in the specifications for various application formats and transport methods.

     -

    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 initiator MUST send a "terminate" action to the other party.

    +

    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 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 ended (even before receiving acknowledgement from the other party). If the terminating entity receives additional 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 a considered session-ending event. However, in this case there is nothing for the party to acknowledge.

    +

    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 or application format parameter, 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 change a transport method, inform the other party that a device is ringing or that a scheduled event has occurred or will occur, etc.

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

    If either party receives an empty "session-info" message for an active session, it MUST send an empty IQ result; this way, an empty "session-info" message may be used as a "ping" to determine session vitality.

    -

    Informational messages are specific to a particular description format or transport method and therefore are described in specifications other than this one.

    +

    Informational messages are specific to a particular application type or transport method and therefore are described in specifications other than this one.

         @@ -633,13 +668,13 @@ PENDING o---------------------+ | sid - A random session identifier generated by the initiator, which effectively maps to the SIP "Call-ID" parameter; this SHOULD match the XML Nmtoken production See <http://www.w3.org/TR/2000/WD-xml-2e-20000814#NT-Nmtoken> so that XML character escaping is not needed for characters such as &. + A random session identifier generated by the initiator, which effectively maps to the SIP "Call-ID" parameter; this SHOULD match the XML Nmtoken production See <http://www.w3.org/TR/2000/WD-xml-2e-20000814#NT-Nmtoken> so that XML character escaping is not needed for characters such as '&'. REQUIRED -

    The attributes of the &CONTENT; element are as follows:

    +

    The attributes of the &CONTENT; element are as follows.

    @@ -663,7 +698,7 @@ PENDING o---------------------+ | - +
    Attribute
    sendersWhich parties in the session will be generating content; the allowable values are "initiator", "recipient", or "both" (where "both" is the default).Which parties in the session will be generating content; the allowable values are "initiator", "responder", or "both" (where "both" is the default). RECOMMENDED
    @@ -671,7 +706,7 @@ PENDING o---------------------+ | -

    The Jingle-specific error conditions are as follows.

    +

    The Jingle-specific error conditions are as follows. These condition elements are qualified by the 'http://www.xmpp.org/extensions/xep-0166.html#ns-errors' namespace &NSNOTE;.

    @@ -686,7 +721,7 @@ PENDING o---------------------+ | - + @@ -712,7 +747,7 @@ PENDING o---------------------+ | -

    If an entity supports Jingle, it MUST advertise that fact by returning a feature of "http://www.xmpp.org/extensions/xep-0166.html#ns" &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 specifications for those formats and methods.

    +

    If an entity supports Jingle, it MUST advertise that fact by returning a feature of "http://www.xmpp.org/extensions/xep-0166.html#ns" &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.

    the name of the application format a natural-language summary of the application format - whether the media should be sent over a "reliable" or "lossy" transport + + whether the media can be sent over a "reliable" transport, a "lossy" transport, or "both" + the document in which this application format is specified ]]> @@ -796,7 +833,7 @@ PENDING o---------------------+ | the name of the transport method a natural-language summary of the transport method - whether the transport method is "reliable" or "lossy" + whether the transport method can be "reliable", "lossy", or "both" the document in which this transport method is specified ]]> @@ -884,11 +921,9 @@ PENDING o---------------------+ | - - - - - + + + @@ -949,7 +984,7 @@ PENDING o---------------------+ |
  • Define a full-featured protocol for XMPP signalling.

    • Implementation experience indicates that a dual-stack approach may not be feasible on all the computing platforms for which Jabber clients have been written, or even desirable on platforms where it is feasible. For example, one large ISP decided to switch to a pure XMPP approach after having implemented and deployed a dual-stack client for several years. Therefore, it seemed reasonable to define an XMPP signalling protocol that could provide the necessary session management semantics while also making it relatively straightforward to interoperate with existing Internet standards.

    -

    As a result of feedback received on XEP-0111, the original authors of this document (Joe Hildebrand and Peter Saint-Andre) began to define such a signalling protocol, code-named Jingle. Upon communication with members of the Google Talk team, Google Talk is a messaging and voice chat service and client provided by Google; see <http://www.google.com/talk/>. it was discovered that the emerging Jingle approach was conceptually (and even syntactically) quite similar to the signalling protocol used in the Google Talk application. Therefore, in the interest of interoperability and adoption, we decided to harmonize the two approaches. The signalling protocol specified herein is, therefore, substantially equivalent to the original Google Talk protocol, with several adjustments based on feedback received from implementors as well as for publication within the XMPP Standards Foundation's standards process.

    +

    As a result of feedback received on XEP-0111, the original authors of this document (Joe Hildebrand and Peter Saint-Andre) began to define such a signalling protocol, code-named Jingle. Upon communication with members of the Google Talk team, Google Talk is a messaging and voice chat service and client provided by Google; see <http://www.google.com/talk/>. it was discovered that the emerging Jingle approach was conceptually (and even syntactically) quite similar to the signalling protocol used in the Google Talk application. Therefore, in the interest of interoperability and adoption, we decided to harmonize the two approaches. The signalling protocol specified herein is, therefore, substantially equivalent to the original Google Talk protocol, with several adjustments based on feedback received from implementors as well as for publication by the XMPP Standards Foundation.

    The authors would like to thank Rohan Mahy for his valuable input on early versions of this document. Thiago Camargo, Dafydd Harries, Antti Ijäs, Lauri Kaila, Justin Karneges, Jussi Laako, Anthony Minessale, Matt O'Gorman, Rob Taylor, Matt Tucker, Saku Vainio, Brian West, and others have also provided helpful input. Thanks also to those who have commented on the &SSIG; and (earlier) Jingle Before this specification was formally accepted by the XMPP Standards Foundation as an XMPP Extension Protocol, it was discussed on the semi-private <jingle@jabber.org> mailing list; although that list is no longer used since the standards@xmpp.org list is the preferred discussion venue, for historical purposes it is publicly archived at <http://mail.jabber.org/pipermail/jingle/>. mailing lists.

    Jingle Condition
    <out-of-order/> &unexpected;The request cannot occur at this point in the state machine (e.g., initiate after accept).The request cannot occur at this point in the state machine (e.g., session-initiate after session-accept).
    <unknown-session/>