From 1e2643de6f204a25707e0bbf86db19663011c3a0 Mon Sep 17 00:00:00 2001 From: Peter Saint-Andre Date: Thu, 15 Nov 2007 04:51:37 +0000 Subject: [PATCH] copy edit git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1380 4b5297f7-1745-476d-ba37-a9c6900126ab --- xep-0166.xml | 828 ++++++++++++++++++++++++++------------------------- 1 file changed, 417 insertions(+), 411 deletions(-) diff --git a/xep-0166.xml b/xep-0166.xml index bb5e9ff3..ef9d6f69 100644 --- a/xep-0166.xml +++ b/xep-0166.xml @@ -202,7 +202,7 @@ -

The purpose of Jingle is to enable one-to-one, peer-to-peer media sessions between XMPP entities, with the negotiation occurring over XMPP and the media being exchanged outside the XMPP band using technologies such as the Real-time Transport Protocol (RTP; &rfc3550;), the User Datagram Protocol (UDP; &rfc0768;), and &ice;.

+

The purpose of Jingle is to enable one-to-one, peer-to-peer media sessions between XMPP entities, with the negotiation being completed XMPP and the media being exchanged outside the XMPP band using technologies such as the Real-time Transport Protocol (RTP; &rfc3550;), the User Datagram Protocol (UDP; &rfc0768;), and &ice;.

One target application for Jingle is simple voice chat (see &xep0167;). We stress the word "simple". The purpose of Jingle is not to build a full-fledged telephony application that supports call waiting, call forwarding, call transfer, hold music, IVR systems, find-me-follow-me functionality, conference calls, and the like. These features are of interest to some user populations, but building in support for these features would introduce unnecessary complexity into a technology that is designed for basic multimedia interaction.

The purpose of Jingle is not to supplant or replace technologies based on Session Initiation Protocol (SIP; &rfc3261;). Because dual-stack XMPP+SIP clients are difficult to build, Jingle was designed as a pure XMPP signalling protocol. However, Jingle is at the same time designed to interwork with SIP so that the millions of deployed XMPP clients can be added onto existing Voice over Internet Protocol (VoIP) networks, rather than limiting XMPP users to a separate and distinct network.

Jingle is designed in a modular way so that developers can easily add support for multimedia session types other than voice chat, such as video chat (see &xep0180;), application sharing, file sharing, collaborative editing, whiteboarding, and torrent broadcasting. The transport methods are also modular, so that Jingle implementations can use any appropriate media transport (including proprietary methods not standardized through the XMPP Standards Foundation).

@@ -221,7 +221,7 @@ Romeo Juliet |<----------------------------| | ack | |---------------------------->| - | MEDIA SESSION (RTP) | + | MEDIA SESSION | |<===========================>| | session-terminate | |<----------------------------| @@ -229,7 +229,7 @@ Romeo Juliet |---------------------------->| | | ]]> -

Naturally, more complex scenarios are possible; see the Scenarios section of this document for details.

+

Naturally, more complex scenarios are probably; see the Scenarios section of this document for details.

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

@@ -297,7 +297,7 @@ Romeo Juliet sid='a73sjjvkla37jfea'/> ]]> -

The other party MUST then acknowledge termination of the session:

+

The other party MUST then acknowledge termination of the session.

The protocol defined herein is designed to meet the following requirements:

    -
  1. Make it possible to manage a wide variety of peer-to-peer sessions (not limited to voice and video) within XMPP.
    2. +
  2. Make it possible to manage a wide variety of peer-to-peer sessions (including but not limited to voice and video) within XMPP.
    3. +
  3. When a peer-to-peer connection cannot be negotiated, make it possible to fall back to relayed communications.
  4. Clearly separate the signalling channel (XMPP) from the data channel.
    5. -
  5. Clearly separate the content description formats (e.g., for voice chat) from the content transport methods.
    6. -
  6. Make it possible to add, modify, and remove content types from an existing session.
    7. +
  7. Clearly separate the application types (e.g., video) from the transport methods (e.g., RTP).
    8. +
  8. Make it possible to add, modify, and remove both media types and transport methods in relation to an existing session.
  9. Make it relatively easy to implement support for the protocol in standard Jabber/XMPP clients.
  10. 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:

    -

  • Various content description formats (audio, video, etc.) and, where possible, mapping those types to the Session Description Protocol (SDP; see &rfc4566;); examples include Jingle Audio via RTP and Jingle Video via RTP.

    • -

  • Various content transport methods; examples include &xep0176; and Raw UDP Transport.

    • +

  • Various application types (audio, video, etc.) and, where possible, mapping those types to the Session Description Protocol (SDP; see &rfc4566;); examples include Jingle Audio via RTP and Jingle Video via RTP.

    • +

  • Various transport methods; examples include &xep0176; and Raw UDP Transport.

  • Procedures for mapping the Jingle signalling protocol to existing signalling standards such as the IETF's Session Initiation Protocol (SIP) and the ITU's H.323 protocol (see &h323;); these documents are forthcoming.

 @@ -332,23 +333,23 @@ Romeo Juliet Session - A number of pairs of negotiated content transport methods and content description formats connecting two entities. It is delimited in time by an initiate request and session ending events. During the lifetime of a session, pairs of content descriptions and content transport methods can be added or removed. A session consists of at least one active negotiated content type at a time. + A number of pairs of negotiated application types and transport methods connecting two entities. It is delimited in time by an initiate request and session ending events. During the lifetime of a session, pairs of application types and transport methods can be added or removed. A session consists of at least one content type at a time. Content Type - The combination of one content description and one content transport method. + The combination of one application type and one transport method. - Content Description - The format of the content type being established, which formally declares one purpose of the session (e.g., "voice" or "video"). This is the 'what' of the session (i.e., the bits to be transferred), such as the acceptable codecs when establishing a voice conversation. In Jingle XML syntax the content type is the namespace of the &DESCRIPTION; element. + Application Type + The data format of the content type being established, which formally declares one purpose of the session (e.g., "voice" or "video"). This is the 'what' of the session (i.e., the bits to be transferred), such as the acceptable codecs when establishing a voice conversation. In Jingle XML syntax the application type is the namespace of the &DESCRIPTION; element. Transport Method - The method for establishing data stream(s) between entities. Possible transports might include ICE-TCP, Raw UDP, inband data, etc. This is the 'how' of the session. In Jingle XML syntax this is the namespace of the &TRANSPORT; element. The content transport method defines how to transfer bits from one host to another. Each transport method must specify whether it is lossy (thus suitable for applications where some packet loss is tolerable) or reliable (thus suitable for applications where packet loss is not tolerable). + The method for establishing data stream(s) between entities. Possible transports might include ICE-TCP, Raw UDP, inband data, etc. This is the 'how' of the session. In Jingle XML syntax this is the namespace of the &TRANSPORT; element. The transport method defines how to transfer bits from one host to another. Each transport method must specify whether it is lossy (thus suitable for applications where some packet loss is tolerable) or reliable (thus suitable for applications where packet loss is not tolerable). Component - A component is a numbered stream of data which needs to be transmitted between the endpoints for a given content type in the context of a given session. It is up to the transport to negotiate the details of each component. Depending on the content type and the content description, one content description may require multiple components to be communicated (e.g., the audio content type might use two components: one to transmit an RTP stream and another to transmit RTCP timing information). + A component is a numbered stream of data which needs to be transmitted between the endpoints for a given content type in the context of a given session. It is up to the transport to negotiate the details of each component. Depending on the content type, multiple components may be needed (e.g., two components might be needed, one to transmit an RTP stream and another to transmit RTCP timing information). @@ -361,16 +362,16 @@ Romeo Juliet -

Jingle consists of three parts, each with its own syntax, semantics, and state machine:

+

Jingle consists of three parts, each with its own syntax and semantics:

  1. Overall session management
    2. -
  2. Content description formats (the "what")
    3. -
  3. Content transport methods (the "how")
    4. +
  4. Application types (the "what")
    5. +
  5. Transport methods (the "how")
-

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

+

This document defines the semantics and syntax for overall session management. It also provides pluggable "slots" for application types 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 types and transport methods.

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 one content type, which includes at least one content type.
    2. +
  2. One user (the "initator") sends to another user (the "receiver") a session request with at least one content type.
  3. If the receiver wants to proceed, it provisionally accepts the request by sending an IQ result.
  4. 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).
  5. These candidates are checked for connectivity.
    6. @@ -426,19 +427,19 @@ PENDING o---------------------+ | content-accept - Accept a content-add or content-remove action received from another party. + Accept a content-add, content-modify, or content-remove action received from another party. 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 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 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 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 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. 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 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). + 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). session-accept @@ -466,16 +467,16 @@ PENDING o---------------------+ |

    This section defines the high-level flow of a Jingle session. More detailed descriptions are provided in the Scenarios section of this document.

    -

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

    +

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

      -

    1. If the intended responder shares presence with the initiator (see &xmppim;) and has only one available resource, this task SHOULD be completed using &xep0030; or the presence-based profile of service discovery specified in &xep0115;. 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 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 XEP-0115 for details.

      2. -

    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 content description format, the initiator SHOULD initiate the Jingle signalling with that resource.

      3. -

    3. If the intended responder shares presence with the initiator and has more than one available resource but more than one of the resources supports Jingle and the desired content description format, the initiator SHOULD use &xep0168; in order to determine which is the best resource with which to initiate the desired Jingle session.

      4. +

    4. 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 type. 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 types 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.

      5. +

    5. 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 type, the initiator SHOULD initiate the Jingle session with that resource.

      6. +

    6. If the intended responder shares presence with the initiator and has more than one available resource but more than one of the resources supports Jingle and the desired application type, the initiator SHOULD use &xep0168; in order to determine which is the best resource with which to initiate the desired Jingle session.

    7. If the intended responder does not share presence with the initiator, the initiator SHOULD first send a &xep0155; request to the responder in order to initiate the exchange of XMPP stanzas. The request SHOULD include a RAP routing hint as specified in XEP-0168 and the &MESSAGE; stanza containing the request SHOULD be of type "headline" so that (typically) it is not stored offline for later delivery. The stanza session negotiation SHOULD result in temporary sharing of presence between the parties via the "presence" field as described in XEP-0155.

     -

    Once the initiator 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://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 content description format and one &TRANSPORT; child element that specifies a potential content transport method. If either party wishes to propose the use of multiple transport methods for the same content description, it must send multiple &CONTENT; elements.

    +

    Once the initiator has discovered which of the receiver's XMPP resources is ideal for the desired application type, 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 type 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 type, 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).

    @@ -485,20 +486,28 @@ PENDING o---------------------+ |

    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:

      -
    • The initiator is unknown to the receiver (e.g., via presence subscription) and the receiver does not communicate with unknown entities.
      • -
    • The receiver wishes to redirect to another address.
      • +
    • 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 content description formats.
      • -
    • The receiver does not support any of the specified content transport methods.
      • +
    • The receiver does not support any of the specified application types.
      • +
    • The receiver 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) 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 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 receiver 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.

    @@ -507,14 +516,6 @@ PENDING o---------------------+ | xmpp:voicemail@capulet.lit - - ]]> -

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

    - - - - ]]>

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

    @@ -526,7 +527,7 @@ PENDING o---------------------+ | ]]> -

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

    +

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

    @@ -535,7 +536,7 @@ PENDING o---------------------+ | ]]> -

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

    +

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

    @@ -554,10 +555,10 @@ PENDING o---------------------+ | ]]>     -

    In order to 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 receiver 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, 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 defined in the relevant specifications for various content description formats and content transport methods, and illustrated in the Scenarios section of this document.

    +

    In general, negotiation will be necessary before the parties can agree on an acceptable set of content types, application types, and transport methods. The potential combinations of parameters to be negotiated are many, and not all are shown herein. Some are defined in the relevant specifications for various application types and transport methods, and illustrated in the Scenarios section of this document.

    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).
      • @@ -567,25 +568,370 @@ PENDING o---------------------+ |
    -

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

    +

    If (after negotiation of transport methods and application types 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.

    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 content over the negotiated connection.

    -

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

    +

    The initiator then acknowledges the receiver'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. Potential modifications are shown in the Scenarios section of this document.

    +

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

     -

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

    -

    The other party (in this case the initiator) MUST then acknowledge termination of the session:

    +

    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.

    +

    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.

     -

    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 content transport method or content description format parameter, inform the other party that a session initiation request is queued, that a device is ringing, or that a scheduled event has occurred or will occur.

    +

    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 type parameter, 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.

    -

    Most 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 description format or transport method and therefore are described in specifications other than this one.

    +     +     + + + +

    The &JINGLE; element MAY be empty or contain one or more &CONTENT; elements (for which see Content Element).

    +

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

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeDefinitionInclusion
    actionA Jingle action as listed in this document (e.g., "session-terminate").REQUIRED
    initiatorThe full JID of the entity that has initiated the session flow (which may be different from the 'from' address on the IQ-set).REQUIRED
    reasoncodeA machine-readable purpose for the action being sent (e.g., "connectivity-error" for a session-terminate action).OPTIONAL
    reasontextA human-readable purpose for the action being sent (e.g., "Sorry, gotta go!" for a session-terminate action).OPTIONAL
    responderThe full JID of the entity that has replied to the initiation, which may be different from the 'to' address on the IQ-set.RECOMMENDED
    sidA 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:

    + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeDefinitionInclusion
    creatorWhich party originally generated the content type (used to prevent race conditions regarding modifications).REQUIRED
    nameA unique name or identifier for the content type (this identifier is opaque and does not have semantic meaning).REQUIRED
    profileThe profile in use (e.g., "RTP/AVP" in the context of the Real-time Transport Protocol).RECOMMENDED
    sendersWhich parties in the session will be generating content; the allowable values are "initiator", "recipient", or "both" (where "both" is the default).RECOMMENDED
    +     +     + + +

    The Jingle-specific error conditions are as follows.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Jingle ConditionXMPP ConditionDescription
    <busy/>&recipient;The session-initiate is declined because the recipient is online but unavailable to participate in a session (this maps to error code 486 in SIP).
    <out-of-order/>&unexpected;The request cannot occur at this point in the state machine (e.g., initiate after accept).
    <unknown-session/>&badrequest;The 'sid' attribute specifies a session that is unknown to the recipient (e.g., no longer live according to the recipient's state machine because the recipient previously terminated the session).
    <unsupported-content/>¬acceptable;The recipient does not support any of the desired application types.
    <unsupported-info/>&feature;The recipient does not support the informational payload of a session-info message.
    <unsupported-transports/>¬acceptable;The recipient does not support any of the desired transport 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 types and transport methods supported by the responding entity, as described in the specifications for those formats and methods.

    + + + + ]]> + + + ... + + ... + + + ]]> +     + + + +

    A document that specifies a Jingle application type (e.g., audio via RTP) MUST define:

    +
      +
    1. How successful application type negotiation occurs for encapsulation into Jingle.
      2. +
    2. A &DESCRIPTION; element and associated semantics for representing the application type.
      3. +
    3. If and how the application type can be mapped to the Session Description Protocol.
      4. +
    4. Whether the media for the application type should be sent over a reliable or lossy transport type (or both).
      5. +
    5. Exactly how the media is to be sent and received over a reliable or lossy transport.
      6. +
    +     + +

    A document that specifies a Jingle transport method (e.g., Raw UDP) MUST define:

    +
      +
    1. How successful transport negotiation occurs for encapsulation into Jingle.
      2. +
    2. A &TRANSPORT; element and associated semantics for representing the transport type.
      3. +
    3. Whether the transport is reliable or lossy.
      4. +
    4. If and how the transport handles components as defined herein (e.g., for the Real Time Control Protocol).
      5. +
    +     +     + + + +

    Jingle sessions may be resource-intensive. Therefore, it is possible to launch a denial-of-service attack against an entity by burdening it with too many Jingle sessions. Care must be taken to accept sessions only from known entities and only if the entity's device is able to process such sessions.

    +     + +

    Jingle communications may be enabled through gateways to non-XMPP networks, whose security characteristics may be quite different from those of XMPP networks. (For example, on some SIP networks authentication is optional and "from" addresses can be easily forged.) Care must be taken in communicating through such gateways.

    +     + +

    Mere negotiation of a Jingle session may expose sensitive information about the parties (e.g., IP addresses). Care must be taken in communicating such information, and end-to-end encryption should be used if the parties do not trust the intermediate servers or gateways.

    +     +     + + +

    This document requires no interaction with &IANA;.

    +     + + + +

    Until this specification advances to a status of Draft, its associated namespaces shall be "http://www.xmpp.org/extensions/xep-0166.html#ns" and "http://www.xmpp.org/extensions/xep-0166.html#ns-errors"; upon advancement of this specification, the ®ISTRAR; shall issue permanent namespaces in accordance with the process defined in Section 4 of &xep0053;.

    +     + +

    The XMPP Registrar shall maintain a registry of Jingle application types. All application type registrations shall be defined in separate specifications (not in this document). Application types defined within the XEP series MUST be registered with the XMPP Registrar, resulting in protocol URNs of the form "urn:xmpp:jingle:application:name" (where "name" is the registered name of the application type).

    + ®PROCESS; + + the name of the application type + a natural-language summary of the application type + whether the media should be sent over a "reliable" or "lossy" transport + the document in which this application type is specified + + ]]> +     + +

    The XMPP Registrar shall maintain a registry of Jingle transport methods. All transport method registrations shall be defined in separate specifications (not in this document). Transport methods defined within the XEP series MUST be registered with the XMPP Registrar, resulting in protocol URNs of the form "urn:xmpp:jingle:transport:name" (where "name" is the registered name of the transport method).

    + ®PROCESS; + + the name of the transport method + a natural-language summary of the transport method + whether the transport method is "reliable" or "lossy" + the document in which this transport method is specified + + ]]> +     + + +

    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.

    + + 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 + + ]]> +     +     +     + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + + + + + + + + + + + + + + + + + + + + ]]> @@ -601,6 +947,7 @@ Romeo Juliet |---------------------------->| | error | | (recipient-unavailable) | + |<----------------------------| ]]>

    The protocol flow is as follows.

    -

    In this scenario, Romeo initiates a voice chat with Juliet using a transport method of ICE-UDP, and the parties exchange informational messages.

    +

    In this scenario, Romeo initiates a voice chat with Juliet using a transport method of ICE-UDP. The parties also exchange informational messages.

    The session flow is as follows:

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

    For each candidate received, the other party MUST acknowledge receipt or return an error:

    - For each candidate received, the other party acknowledges receipt or returns an error:

    + @@ -798,7 +1145,7 @@ Romeo Juliet ]]>

    At the same time (i.e., immediately after provisionally accepting the session, not waiting for the initiator to begin or finish sending candidates), the responder also begins sending candidates that may work for it. As above, the initiator acknowledges receipt of the candidates.

    -

    As the initiator and responder receive candidates, they probe the various candidate transports for connectivity. In performing these connectivity checks, the parties follow the procedure specified in Section 7 of draft-ietf-mmusic-ice.

    +

    As the initiator and responder receive candidates, they probe the various candidate transports for connectivity. In performing these connectivity checks, the parties follow the procedure specified in Section 7 of draft-ietf-mmusic-ice.

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

    @@ -843,8 +1190,8 @@ Romeo Juliet sid='a73sjjvkla37jfea'/> ]]> -

    The other party MUST then acknowledge termination of the session:

    - The other party then acknowledges termination of the session:

    + ]]> - ]]> ]]> -

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

    +

    As in the previous scenario, the parties exchange ICE candidates (see above for examples).

    Once the parties find candidate transports that work, the receiver accepts the session.

    @@ -1091,7 +1438,7 @@ Romeo Juliet ]]> - ]]> -

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

    +

    As in the previous scenario, the parties exchange ICE candidates (see above for examples).

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

    @@ -1294,8 +1641,8 @@ Romeo Juliet sid='a73sjjvkla37jfea'/> ]]> -

    The other party MUST then acknowledge termination of the session:

    - The other party then acknowledges termination of the session:

    + - - -

    The &JINGLE; element MAY be empty or contain one or more &CONTENT; elements (for which see Content Element).

    -

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

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    AttributeDefinitionInclusion
    actionA Jingle action as listed in this document (e.g., "session-terminate").REQUIRED
    initiatorThe full JID of the entity that has initiated the session flow (which may be different from the 'from' address on the IQ-set).REQUIRED
    reasoncodeA machine-readable purpose for the action being sent (e.g., "connectivity-error" for a session-terminate action).OPTIONAL
    reasontextA human-readable purpose for the action being sent (e.g., "Sorry, gotta go!" for a session-terminate action).OPTIONAL
    responderThe full JID of the entity that has replied to the initiation, which may be different from the 'to' address on the IQ-set.RECOMMENDED
    sidA 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:

    - - - - - - - - - - - - - - - - - - - - - - - - - - -
    AttributeDefinitionInclusion
    creatorWhich party originally generated the content description (used to prevent race conditions regarding modifications).REQUIRED
    nameA unique name or identifier for the content type (this identifier is opaque and does not have semantic meaning).REQUIRED
    profileThe profile in use (e.g., "RTP/AVP" in the context of the Real-time Transport Protocol).RECOMMENDED
    senderswhich entities in the session will be generating content; the allowable values are "initiator", "recipient", or "both" (where "both" is the default).RECOMMENDED
    -     -     - - -

    The Jingle-specific error conditions are as follows.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Jingle ConditionXMPP ConditionDescription
    <busy/>&recipient;The session-initiate is declined because the recipient is online but unavailable to participate in a session (this maps to error code 486 in SIP).
    <out-of-order/>&unexpected;The request cannot occur at this point in the state machine (e.g., initiate after accept).
    <unknown-session/>&badrequest;The 'sid' attribute specifies a session that is unknown to the recipient (e.g., no longer live according to the recipient's state machine because the recipient previously terminated the session).
    <unsupported-content/>¬acceptable;The recipient does not support any of the desired content description formats.
    <unsupported-info/>&feature;The recipient does not support the informational payload of a session-info message.
    <unsupported-transports/>¬acceptable;The recipient does not support any of the desired content transport 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 &xep0030; information requests.

    - - - - ]]> - - - ... - - ... - - - ]]> -     - - - -

    A document that specifies a Jingle application type (e.g., audio via RTP) MUST define:

    -
      -
    1. How successful content negotiation occurs for encapsulation into Jingle.
      2. -
    2. A &DESCRIPTION; element and associated semantics for representing the content.
      3. -
    3. If and how the content description can be mapped to the Session Description Protocol.
      4. -
    4. Whether the content should be sent over a reliable or lossy transport type (or both).
      5. -
    5. Exactly how the content is to be sent and received over a reliable or lossy transport.
      6. -
    -     - -

    A document that specifies a Jingle transport method (e.g., Raw UDP) MUST define:

    -
      -
    1. How successful transport negotiation occurs for encapsulation into Jingle.
      2. -
    2. A &TRANSPORT; element and associated semantics for representing the transport type.
      3. -
    3. Whether the transport is reliable or lossy.
      4. -
    4. If and how the transport handles components as defined herein (e.g., for the Real Time Control Protocol).
      5. -
    -     -     - - - -

    Jingle sessions may be resource-intensive. Therefore, it is possible to launch a denial-of-service attack against an entity by burdening it with too many Jingle sessions. Care must be taken to accept content sessions only from known entities and only if the entity's device is able to process such sessions.

    -     - -

    Jingle communications may be enabled through gateways to non-XMPP networks, whose security characteristics may be quite different from those of XMPP networks. (For example, on some SIP networks authentication is optional and "from" addresses can be easily forged.) Care must be taken in communicating through such gateways.

    -     -     - - -

    This document requires no interaction with &IANA;.

    -     - - - -

    Until this specification advances to a status of Draft, its associated namespaces shall be "http://www.xmpp.org/extensions/xep-0166.html#ns" and "http://www.xmpp.org/extensions/xep-0166.html#ns-errors"; upon advancement of this specification, the ®ISTRAR; shall issue permanent namespaces in accordance with the process defined in Section 4 of &xep0053;.

    -     - -

    The XMPP Registrar shall maintain a registry of Jingle content description formats. All content description format registrations shall be defined in separate specifications (not in this document). Content description formats defined within the XEP series MUST be registered with the XMPP Registrar, resulting in protocol URNs of the form "urn:xmpp:jingle:description:name" (where "name" is the registered name of the content description format).

    - ®PROCESS; - - the name of the content description format - a natural-language summary of the content description format - whether the content should be sent over a "reliable" or "lossy" transport - the document in which this content description format is specified - - ]]> -     - -

    The XMPP Registrar shall maintain a registry of Jingle content transport methods. All content transport method registrations shall be defined in separate specifications (not in this document). Content transport methods defined within the XEP series MUST be registered with the XMPP Registrar, resulting in protocol URNs of the form "urn:xmpp:jingle:transport:name" (where "name" is the registered name of the content transport method).

    - ®PROCESS; - - the name of the content transport method - a natural-language summary of the content transport method - whether the transport method is "reliable" or "lossy" - the document in which this content transport method is specified - - ]]> -     - - -

    The XMPP Registrar shall maintain a registry of reasons for 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 in use as of April 2007. Refer to the registry itself for a complete and current list of reasoncodes.

    - - connectivity-error - the action (e.g., session-terminate) is related to connectivity problems - XEP-0166 - - - - general-error - the action (e.g., session-terminate) is related to a non-specific application error - XEP-0166 - - - - media-error - the action (e.g., session-terminate) is related to media processing problems - XEP-0166 - - - - no-error - the action is generated during the normal course of state management - XEP-0166 - - ]]> -     -     -     - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ]]> - - - - - - - - - - - - - - - - - - - - ]]> - -

    Until Jingle was developed, there existed no widely-adopted standard for initiating and managing peer-to-peer interactions between XMPP entities. Although several large service providers and Jabber client teams had written and implemented their own proprietary XMPP extensions for peer-to-peer signalling (usually only for voice), those technologies were not open and did not always take into account requirements to interoperate with SIP-based technologies. The only existing open protocol was &xep0111;, which made it possible to initiate and manage peer-to-peer sessions, but which did not provide enough of the key signalling semantics to be easily implemented in Jabber/XMPP clients. It is true that TINS made it relatively easy to implement an XMPP-to-SIP gateway; however, in line with the long-time Jabber philosophy of "simple clients, complex servers", it would be better to force complexity onto the server-side gateway and to keep the client as simple as possible.

    The result was an unfortunate fragmentation within the XMPP community regarding signalling protocols. Essentially, there were two possible approaches to solving the problem:

    @@ -1656,6 +1662,6 @@ Romeo Juliet

    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.

     -

    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 accepted as a XMPP Extension Protocol specification, it was discussed on the semi-private <jingle@jabber.org> mailing list; although that list is no longer used (the Standards list is the preferred discussion venue), for historical purposes it is publicly archived at <http://mail.jabber.org/pipermail/jingle/>. mailing lists.

    +

    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.