XEP-0166: Jingle

NOTICE: The protocol defined herein is a Draft Standard of the XMPP Standards Foundation. Implementations are encouraged and the protocol is appropriate for deployment in production systems, but some changes to the protocol are possible before it becomes a Final Standard.

1. Introduction
2. How It Works
3. Requirements
4. Terminology
    4.1. Glossary
    4.2. Conventions
5. Concepts and Approach
    5.1. Overall Session Management
6. Session Flow
    6.1. Resource Determination
    6.2. Initiation
    6.3. Responder Response
       6.3.1. Acknowledgement
       6.3.2. Errors
    6.4. Negotiation
    6.5. Acceptance
    6.6. Modifying an Active Session
    6.7. Termination
    6.8. Informational Messages
7. Formal Definition
    7.1. Jingle Element
    7.2. Action Attribute
       7.2.1. content-accept
       7.2.2. content-add
       7.2.3. content-modify
       7.2.4. content-reject
       7.2.5. content-remove
       7.2.6. description-info
       7.2.7. security-info
       7.2.8. session-accept
       7.2.9. session-info
       7.2.10. session-initiate
       7.2.11. session-terminate
       7.2.12. transport-accept
       7.2.13. transport-info
       7.2.14. transport-reject
       7.2.15. transport-replace
       7.2.16. Tie Breaking Related to Jingle Actions
    7.3. Content Element
    7.4. Reason Element
8. Transport Types
    8.1. Datagram
    8.2. Streaming
9. Security Preconditions
10. Error Handling
11. Determining Support
12. Conformance by Using Protocols
    12.1. Application Formats
    12.2. Transport Methods
    12.3. Security Preconditions
13. Security Considerations
    13.1. Transport Security
    13.2. Denial of Service
    13.3. Communication Through Gateways
    13.4. Information Exposure
    13.5. Redirection
14. IANA Considerations
15. XMPP Registrar Considerations
    15.1. Protocol Namespaces
    15.2. Namespace Versioning
    15.3. Jingle Application Formats Registry
    15.4. Jingle Transport Methods Registry
16. XML Schemas
    16.1. Jingle
    16.2. Jingle Errors
17. History
18. Acknowledgements

Appendices
    A: Document Information
    B: Author Information
    C: Legal Notices
    D: Relation to XMPP
    E: Discussion Venue
    F: Requirements Conformance
    G: Notes
    H: Revision History

1. Introduction

The purpose of Jingle is to enable one-to-one, peer-to-peer media sessions between XMPP entities, where the negotiation occurs over the XMPP signalling channel and the media is exchanged over a data channel that is usually a dedicated non-XMPP transport. Jingle is designed in a modular way:

It is expected that most application types, transport methods, and security preconditions will be documented in specifications produced by the XMPP Standards Foundation (XSF) [14] or the Internet Engineering Task Force (IETF) [15]; however, developers can also define proprietary methods for custom functionality.

Although Jingle provides a general framework for session management, the original target application for Jingle was simple voice and video chat. We stress the word "simple". The purpose of Jingle was 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 adding support for them to the core Jingle layer would introduce unnecessary complexity into a technology that is designed for simple but generalized session negotiation.

Furthermore, Jingle is not intended to supplant or replace existing Internet technologies based on the Session Initiation Protocol (SIP; RFC 3261 [16]). 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.

2. How It Works

In essence, Jingle enables two XMPP entities (e.g., romeo@montague.lit and juliet@capulet.lit) to set up, manage, and tear down a multimedia session. The negotiation takes place over XMPP, and the media transfer typically takes place outside of XMPP. A simplified session flow would be as follows: [17]

Romeo                         Juliet
  |                             |
  |   session-initiate          |
  |---------------------------->|
  |   ack                       |
  |<----------------------------|
  |   session-accept            |
  |<----------------------------|
  |   ack                       |
  |---------------------------->|
  |   MEDIA SESSION             |
  |<===========================>|
  |   session-terminate         |
  |<----------------------------|
  |   ack                       |
  |---------------------------->|
  |                             |

To illustrate the basic flow, we show a truncated example with a "stub" application format and transport method (skipping non-essential steps to enforce the most essential concepts and ignoring security preconditions for now).

<iq from='romeo@montague.lit/orchard'
    id='zid615d9'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-initiate'
          initiator='romeo@montague.lit/orchard'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='this-is-a-stub'>
      <description xmlns='urn:xmpp:jingle:apps:stub:0'/>
      <transport xmlns='urn:xmpp:jingle:transports:stub:0'/>
    </content>
  </jingle>
</iq>

In this example, the initiator (romeo@montague.lit/orchard) sends a session initiation offer to the responder (juliet@capulet.lit/balcony), where the session is defined as the exchange of "stub" media over a "stub" transport.

After the responding client acknowledges receipt of the session-initiate message (not shown here), it prompts the responding user (if any) to choose whether she wants to proceed with the session (however, it does not need to prompt the user if for example she has configured her client to automatically accept session requests from this particular initiator). If she wants to proceed she selects the appropriate interface element and her client sends a session-accept message to the initiator.

<iq from='juliet@capulet.lit/balcony'
    id='rc61n59s'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-accept'
          responder='juliet@capulet.lit/balcony'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='this-is-a-stub'>
      <description xmlns='urn:xmpp:jingle:apps:stub:0'/>
      <transport xmlns='urn:xmpp:jingle:transports:stub:0'/>
    </content>
  </jingle>
</iq>

The initiating client acknowledges receipt of the session-accept message (not shown here) and the parties can exchange "stub" media data over the "stub" transport.

<iq from='juliet@capulet.lit/balcony'
    id='le71fa63'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <success/>
    </reason>
  </jingle>
</iq>

The initiating client acknowledges receipt of the session-terminate message (not shown here) and the session is ended.

We now "fill in the blanks" for the <description/> and <transport/> elements with a more complex example: a voice chat session, where the application type is a Jingle RTP session (with several different codec possibilities) and the transport method is ICE-UDP.

<iq from='romeo@montague.lit/orchard'
    id='ph37a419'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-initiate'
          initiator='romeo@montague.lit/orchard'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='voice'>
      <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
        <payload-type id='96' name='speex' clockrate='16000'/>
        <payload-type id='97' name='speex' clockrate='8000'/>
        <payload-type id='18' name='G729'/>
        <payload-type id='0' name='PCMU' />
        <payload-type id='103' name='L16' clockrate='16000' channels='2'/>
        <payload-type id='98' name='x-ISAC' clockrate='8000'/>
      </description>
      <transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'
                 pwd='asd88fgpdd777uzjYhagZg'
                 ufrag='8hhy'>
        <candidate component='1'
                   foundation='1'
                   generation='0'
                   id='el0747fg11'
                   ip='10.0.1.1'
                   network='1'
                   port='8998'
                   priority='2130706431'
                   protocol='udp'
                   type='host'/>
        <candidate component='1'
                   foundation='2'
                   generation='0'
                   id='y3s2b30v3r'
                   ip='192.0.2.3'
                   network='1'
                   port='45664'
                   priority='1694498815'
                   protocol='udp'
                   rel-addr='10.0.1.1'
                   rel-port='8998'
                   type='srflx'/>
      </transport>
    </content>
  </jingle>
</iq>

Upon receiving the session-initiate message, the responder determines whether it can proceed with the negotiation. If there is no error, the responder acknowledges the session initiation request.

<iq from='juliet@capulet.lit/balcony'
    id='ph37a419'
    to='romeo@montague.lit/orchard'
    type='result'/>

When the responding user affirms that she would like to proceed with the session, the responding client sends a session-accept message to the initiator (including in this example the subset of offered codecs that the responding client supports and one or more transport candidates generated by the responder).

<iq from='juliet@capulet.lit/balcony'
    id='yd71f495'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-accept'
          responder='juliet@capulet.lit/balcony'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='voice'>
      <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
        <payload-type id='97' name='speex' clockrate='8000'/>
        <payload-type id='18' name='G729'/>
      </description>
      <transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'>
        <candidate component='1'
                   foundation='1'
                   generation='0'
                   id='or2ii2syr1'
                   ip='192.0.2.1'
                   network='0'
                   port='3478'
                   priority='2130706431'
                   protocol='udp'
                   type='host'/>
      </transport>
    </content>
  </jingle>
</iq>

<iq from='romeo@montague.lit/orchard'
    id='yd71f495'
    to='juliet@capulet.lit/balcony'
    type='result'/>

Once the parties finish the transport negotiation, they would then exchange media using any of the acceptable codecs.

<iq from='juliet@capulet.lit/balcony'
    id='vua614d9'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <success/>
      <text>Sorry, gotta go!</text>
    </reason>
  </jingle>
</iq>

<iq from='romeo@montague.lit/orchard'
    id='vua614d9'
    to='juliet@capulet.lit/balcony'
    type='result'/>

3. Requirements

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

4. Terminology

4.1 Glossary

Application Format: The data format of the content type being established, which formally declares one purpose of the session (e.g., "audio" 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 format is the namespace of the <description/> element.
Component: A numbered stream of data that 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 might be needed (e.g., one to transmit an RTP stream and another to transmit RTCP timing information).
Content Type: A pair formed by the combination of one application format and one transport method.
Session: One or more content types negotiated between two entities. It is delimited in time by a session-initiate action and a session-terminate action. During the lifetime of a session, content types can be added or removed. A session consists of at least one content type at a time.
Transport Method: The method for establishing data stream(s) between entities. Possible transports might include ICE-UDP, ICE-TCP, Raw UDP, In-Band Bytestreams, SOCKS5 Bytestreams, 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 "datagram" or "streaming" as described in the Transport Types section of this document.

4.2 Conventions

In diagrams, the following conventions are used:

Single-dashed lines (---) represent Jingle stanzas that are sent via the XMPP signalling channel.
Double-dashed lines (===) represent media packets that are sent via the data channel, which typically is not an XMPP channel (although the Jingle In-Band Bytestreams Transport Method is an exception) but instead is a direct or mediated channel between the endpoints.

5. Concepts and Approach

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 initial negotiation of a Jingle session is as follows:

Even after application data is being exchanged, the parties can adjust the session definition by sending additional Jingle messages, such as content-modify, content-remove, content-add, description-info, security-info, session-info, and transport-replace.

5.1 Overall Session Management

The state machine for overall session management (i.e., the state per Session ID) is as follows:

         o
         |
         | session-initiate
         |
         | +---------->--------------+
         |/                          |
PENDING  o-----------------------+   |
         |   | content-accept,   |   |
         |   | content-add,      |   |
         |   | content-modify,   |   |
         |   | content-reject,   |   |
         |   | content-remove,   |   |
         |   | description-info, |   |
        \|/  | session-info,     |   |
         |   | transport-accept, |   |
         |   | transport-info,   |   |
         |   | transport-reject, |   |
         |   | transport-replace |   |
         |   +-------------------+   |
         |                           |
         | session-accept           \|/
         |                           |
 ACTIVE  o-----------------------+   |
         |   | content-accept,   |   |
         |   | content-add,      |   |
         |   | content-modify,   |   |
         |   | content-reject,   |   |
         |   | content-remove,   |   |
         |   | description-info, |   |
        \|/  | session-info,     |   |
         |   | transport-accept, |   |
         |   | transport-info,   |   |
         |   | transport-reject, |   |
         |   | transport-replace |   |
         |   +-------------------+   |
         |                           |
         +------------>--------------+
                                     |
                                     | session-terminate
                                     |
                                     o ENDED

As shown, there are three overall session states:

PENDING
ACTIVE
ENDED

Note: While it is allowed to send all actions while in the PENDING state, typically the responder will send a session-accept message as quickly as possible in order to expedite the transport negotiation; see the Security Considerations section of this document regarding information exposure when the responder sends transport candidates to the initiator.

The actions related to management of the overall Jingle session are as follows (detailed definitions are provided in the Action Attribute section of this document).

content-accept: Accept a content-add action received from another party.
content-add: Add one or more new content definitions to the session.
content-modify: Change the directionality of media sending.
content-reject: Reject a content-add action received from another party.
content-remove: Remove one or more content definitions from the session.
description-info: Exchange information about parameters for an application type.
session-accept: Definitively accept a session negotiation.
session-info: Send session-level information, such as a ping or a ringing message.
session-initiate: Request negotiation of a new Jingle session.
session-terminate: End an existing session.
transport-accept: Accept a transport-replace action received from another party.
transport-info: Exchange transport candidates.
transport-reject: Reject a transport-replace action received from another party.
transport-replace: Redefine a transport method or replace it with a different method.

6. Session Flow

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.

6.1 Resource Determination

In order to initiate a Jingle session, the initiator needs to determine which of the responder's XMPP resources is best for the desired application format. Methods for doing so are out of scope for this specification. However, see the Determining Support section of this document for relevant information.

6.2 Initiation

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 'urn:xmpp:jingle:1' namespace (see Namespace Versioning regarding the possibility of incrementing the version number), 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, as well as (optionally) one <security/> element that specifies a security precondition that needs to be met before the parties can exchange application data over the negotiated transport.

Example 10. Initiator sends session-initiate

<iq from='romeo@montague.lit/orchard'
    id='xs51r0k4'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-initiate'
          initiator='romeo@montague.lit/orchard'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='voice'>
      <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
        <payload-type id='96' name='speex' clockrate='16000'/>
        <payload-type id='97' name='speex' clockrate='8000'/>
        <payload-type id='18' name='G729'/>
        <payload-type id='0' name='PCMU' />
        <payload-type id='103' name='L16' clockrate='16000' channels='2'/>
        <payload-type id='98' name='x-ISAC' clockrate='8000'/>
      </description>
      <transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'
                 pwd='asd88fgpdd777uzjYhagZg'
                 ufrag='8hhy'>
        <candidate component='1'
                   foundation='1'
                   generation='0'
                   id='el0747fg11'
                   ip='10.0.1.1'
                   network='1'
                   port='8998'
                   priority='2130706431'
                   protocol='udp'
                   type='host'/>
        <candidate component='1'
                   foundation='2'
                   generation='0'
                   id='y3s2b30v3r'
                   ip='192.0.2.3'
                   network='1'
                   port='45664'
                   priority='1694498815'
                   protocol='udp'
                   rel-addr='10.0.1.1'
                   rel-port='8998'
                   type='srflx'/>
      </transport>
    </content>
  </jingle>
</iq>

Application types ought not to be mixed beyond necessity within a single session. Therefore the session initiation request (along with subsequent additions) will include only content-types that can be grouped together into a coherent session within a given Jingle application. For example, two parties might start an audio call but then add a video aspect to that call. If one of the parties decides to send a file to the other party as a result of discussion over the audio/video session or a text chat conversation, conceptually that is probably a separate session (unless file exchange or screen sharing or some other application type is an integral part of a broader collaboration experience and needs to be calibrated with the audio/video session).

Note: The syntax and semantics of the <description/>, <transport/>, and <security/> elements are out of scope for this document, 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.

6.3 Responder Response

6.3.1 Acknowledgement

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

Example 11. Responder acknowledges session-initiate

<iq from='juliet@capulet.lit/balcony'
    id='xs51r0k4'
    to='romeo@montague.lit/orchard'
    type='result'/>

However, after acknowledging the session initiation request, the responder might 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.

6.3.2 Errors

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

The initiator is unknown to the responder 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 does not have sufficient resources to participate in a session.
The initiation request was malformed.

If the initiator is unknown to the responder (e.g., via presence subscription as defined in RFC 3921 [21]) and the responder has a policy of not communicating via Jingle with unknown entities, it MUST return a <service-unavailable/> error.

Example 12. Initiator is unknown to responder

<iq from='juliet@capulet.lit/balcony'
    id='xs51r0k4'
    to='romeo@montague.lit/orchard'
    type='error'>
  <error type='cancel'>
    <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

If the responder does not support Jingle, it MUST return a <service-unavailable/> error.

Example 13. Responder does not support Jingle

<iq from='juliet@capulet.lit/balcony'
    id='xs51r0k4'
    to='romeo@montague.lit/orchard'
    type='error'>
  <error type='cancel'>
    <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

If the responder wishes to redirect the request to another address, it MUST return a <redirect/> error.

Example 14. Responder redirection

<iq from='juliet@capulet.lit/balcony'
    id='xs51r0k4'
    to='romeo@montague.lit/orchard'
    type='error'>
  <error type='modify'>
    <redirect xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>
      xmpp:voicemail@capulet.lit
    </redirect>
  </error>
</iq>

If the responder does not have sufficient resources to participate in a session, it MUST return a <resource-constraint/> error.

Example 15. Responder has insufficent resources

<iq from='juliet@capulet.lit/balcony'
    id='xs51r0k4'
    to='romeo@montague.lit/orchard'
    type='error'>
  <error type='wait'>
    <resource-constraint xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

If the initiation request was malformed, the responder MUST return a <bad-request/> error.

Example 16. Initiation request malformed

<iq from='juliet@capulet.lit/balcony'
    id='xs51r0k4'
    to='romeo@montague.lit/orchard'
    type='error'>
  <error type='cancel'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

6.4 Negotiation

Although in general it is preferable for the responder to send a session-accept message as soon as possible, some forms of negotiation might 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 (e.g., content-level and transport-level negotiations) include:

Exchanging particular transport candidates via the transport-info action.
Modifying the communication direction for a content type via the content-modify action.
Changing the definition of a content type via the transport-replace action (typically to fall back to a more suitable transport).
Adding a content type via the content-add action.
Removing a content type via the content-remove action.

These forms of negotiation can also occur after the session has been accepted.

6.5 Acceptance

As soon as possible after receiving the session-initiate message, the responder informs the initiator that she wishes to proceed with the session by sending a session-accept message.

Example 17. Responder accepts the session

<iq from='juliet@capulet.lit/balcony'
    id='jd82f517'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-accept'
          responder='juliet@capulet.lit/balcony'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='voice'>
      <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
        <payload-type id='97' name='speex' clockrate='8000'/>
        <payload-type id='18' name='G729'/>
      </description>
      <transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'>
        <candidate component='1'
                   foundation='1'
                   generation='0'
                   id='or2ii2syr1'
                   ip='192.0.2.1'
                   network='0'
                   port='3478'
                   priority='2130706431'
                   protocol='udp'
                   type='host'/>
      </transport>
    </content>
  </jingle>
</iq>

Note: After receiving and acknowledging the "session-initiate" action received from the initiator, the responding client SHOULD present an interface element that enables a human user to explicitly agree to proceeding with the session (e.g., an "Accept Incoming Call?" pop-up window including "Yes" and "No" buttons). However, the responding client SHOULD NOT return a "session-accept" action to the initiator until the responder has explicitly agreed to proceed with the session (unless the initiator is on a list of entities whose sessions are automatically accepted).

The initiator then acknowledges the responder's definitive acceptance.

Example 18. Initiator acknowledges session acceptance

<iq from='romeo@montague.lit/orchard'
    id='jd82f517'
    to='juliet@capulet.lit/balcony'
    type='result'/>

The session is now in the ACTIVE state. However, this does not necessarily mean that the parties can exchange application data yet, because further negotiation might be necessary (e.g., to fall back from the offered transport method to a suitable alternative).

6.6 Modifying an Active Session

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

6.7 Termination

In order to gracefully end the session (which can 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 session-terminate message to the other party.

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

Probably the primary reason for terminating a session is that the session has ended successfully (e.g., because a file has been sent or a voice call has completed); in this case, the recommended condition is <success/>.

Example 19. Terminating the session (success)

<iq from='juliet@capulet.lit/balcony'
    id='bv81gs75'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <success/>
    </reason>
  </jingle>
</iq>

Another reason for terminating the session is that the terminating party is busy; in this case, the recommended condition is <busy/>.

Example 20. Terminating the session (busy)

<iq from='juliet@capulet.lit/balcony'
    id='hr81fs63'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <busy/>
    </reason>
  </jingle>
</iq>

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

Example 21. Terminating the session (session formally declined)

<iq from='juliet@capulet.lit/balcony'
    id='ky47g295'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <decline/>
    </reason>
  </jingle>
</iq>

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 alternative session in the <sid/> element.

Example 22. Terminating the session (existing session)

<iq from='juliet@capulet.lit/balcony'
    id='ay3r2b86'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <alternative-session>
        <sid>b84tkkwlmb48kgfb</sid>
      </alternative-session>
    </reason>
  </jingle>
</iq>

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

Example 23. Terminating the session (no offered transport method supported)

<iq from='juliet@capulet.lit/balcony'
    id='h82bs51g'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <unsupported-transports/>
    </reason>
  </jingle>
</iq>

Another reason for terminating the session is that the terminating party has determined that transport setup has failed in an unrecoverable fashion (e.g., all transport methods have been exhausted even after fallback and the last method attempted has failed); in this case, the recommended condition is <failed-transport/>.

Example 24. Terminating the session (transport negotiation failed)

<iq from='juliet@capulet.lit/balcony'
    id='pe81ga88'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <failed-transport/>
    </reason>
  </jingle>
</iq>

Another reason for terminating the session is that the terminating party does not support any of the offered application types; in this case, the recommended condition is <unsupported-applications/>.

Example 25. Terminating the session (no offered application type supported)

<iq from='juliet@capulet.lit/balcony'
    id='yd62vd67'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <unsupported-applications/>
    </reason>
  </jingle>
</iq>

Another reason for terminating the session is that the terminating party has determined that setup of the application type has failed in an unrecoverable fashion (e.g., the client cannot initialize audio processing for a voice call); in this case, the recommended condition is <failed-application/>.

Example 26. Terminating the session (application setup failed)

<iq from='juliet@capulet.lit/balcony'
    id='kd82vs71'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <failed-application/>
    </reason>
  </jingle>
</iq>

Another reason for terminating the session is that the terminating party supports the offered application type but does not support the offered or negotiated parameters (e.g., in a voice call none of the payload types); in this case, the recommended condition is <incompatible-parameters/>.

Example 27. Terminating the session (incompatible parameters)

<iq from='juliet@capulet.lit/balcony'
    id='hb3m59s7'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-terminate'
          sid='a73sjjvkla37jfea'>
    <reason>
      <incompatible-parameters/>
    </reason>
  </jingle>
</iq>

Note: Other reasons for terminating the session might apply, and the foregoing list is not exhaustive.

Upon receiving session-terminate message, the other party MUST then acknowledge termination of the session:

Example 28. Acknowledging termination

<iq from='romeo@montague.lit/orchard'
    id='h82bs51g'
    to='juliet@capulet.lit/balcony'
    type='result'/>

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.

Example 29. Unknown-session error

<iq from='romeo@montague.lit/orchard'
    id='ur71vs62'
    to='juliet@capulet.lit/balcony'
    type='error'>
  <error type='cancel'>
    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <unknown-session xmlns='urn:xmpp:jingle:errors:1'/>
  </error>
</iq>

Not all Jingle sessions end gracefully. When the parties to a Jingle session also exchange XMPP presence information, receipt of <presence type='unavailable'/> from the other party SHOULD be considered a session-ending event that justifies proactively sending a session-terminate message to the seemingly unavailable party -- if, that is, no other communication has been received within 5 or 10 seconds from the seemingly unavailable party in the form of XMPP signalling traffic, connectivity checks, or continued media transfer.

6.8 Informational Messages

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.

Example 30. Responder sends ringing message

<iq from='juliet@capulet.lit/balcony'
    id='hq7rg186'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-info'
          sid='a73sjjvkla37jfea'>
    <ringing xmlns='urn:xmpp:jingle:apps:rtp:1:info'/>
  </jingle>
</iq>

An informational message MUST be an IQ-set containing a <jingle/> element whose 'action' attribute is set to a value of "session-info", "description-info", or "transport-info"; the <jingle/> element SHOULD further contain a payload child element (specific to the application format or 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-not-implemented/> error with a Jingle-specific error condition of <unsupported-info/>.

Example 31. Responder returns unsupported-info error

<iq from='romeo@montague.lit/orchard'
    id='hq7rg186'
    to='juliet@capulet.lit/balcony'
    type='error'>
  <error type='modify'>
    <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <unsupported-info xmlns='urn:xmpp:jingle:errors:1'/>
  </error>
</iq>

However, the <jingle/> element associated with a session-info message MAY be empty. If either party receives an empty session-info message for an active session, it MUST send an empty IQ result; this usage functions as a "ping" to determine session vitality via the XMPP signalling channel.

Example 32. Responder sends session ping

<iq from='juliet@capulet.lit/balcony'
    id='ug37vb25'
    to='romeo@montague.lit/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-info'
          sid='a73sjjvkla37jfea'/>
</iq>

Example 33. Initiator returns IQ-result

<iq from='romeo@montague.lit/orchard'
    id='ug37vb25'
    to='juliet@capulet.lit/balcony'
    type='result'/>

7. Formal Definition

7.1 Jingle Element

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.

Table 1: Attributes of Jingle Element

Attribute	Definition	Inclusion
action	A Jingle action as described under Action Attribute.	REQUIRED
initiator*	The full JID of the entity that has initiated the session flow. When the Jingle action is "session-initiate", the <jingle/> element SHOULD possess an 'initiator' attribute that explicitly specifies the full JID of the initiating entity; for all other actions, the <jingle/> element SHOULD NOT possess an 'initiator' attribute and the recipient of the message SHOULD ignore the value if provided. The value of the 'initiator' attribute MAY be different from the 'from' address on the IQ-set of the session-initiate message (e.g., to handle certain interactions involving call managers, soft switches, and media relays). This usage shall be defined in other specifications, for example, in Jingle Session Transfer (XEP-0251) [22]. However, in all cases if the 'initiator' and 'from' values differ then the responder MUST NOT interact with the 'initiator' JID unless it trusts the 'initiator' JID or trusts that the 'from' JID is allowed to authorize the 'initiator' JID to act on the 'from' JID's behalf. In the absence of explicit rules for handling this case, the responder SHOULD simply ignore the 'initiator' attribute and treat the 'from' JID as the initiating entity. After sending acknowledgement of the session-initiate message, the responder MUST send all future commmunications about the Jingle session to the initiator (whether the initiator is considered the 'from' JID or the 'initiator' JID).	RECOMMENDED for session-initiate, NOT RECOMMENDED otherwise
responder*	The full JID of the entity that has replied to the initiation, which can be different from the 'to' address on the IQ-set. When the Jingle action is "session-accept", the <jingle/> element SHOULD possess a 'responder' attribute that explicitly specifies the full JID of the responding entity; for all other actions, the <jingle/> element SHOULD NOT possess a 'responder' attribute and the recipient of the message SHOULD ignore the value if provided. The value of the 'responder' attribute MAY be different from the 'from' address on the IQ-set of the session-accept message, where the logic for handling any difference between the 'responder' JID and the 'from' JID follows the same logic as for session-initiate messages (see above). After sending acknowledgement of the session-accept message, the initiator MUST send all future commmunications about this Jingle session to the responder (whether the responder is considered the 'from' JID or the 'responder' JID).	RECOMMENDED for session-accept, NOT RECOMMENDED otherwise
sid	A random session identifier generated by the initiator, which effectively maps to the local-part of a SIP "Call-ID" parameter; this SHOULD match the XML Nmtoken production [23] so that XML character escaping is not needed for characters such as '&'. In some situations the Jingle session identifier might have security implications. See RFC 4086 [24] regarding requirements for randomness.	REQUIRED

7.2 Action Attribute

The value of the 'action' attribute MUST be one of the following. If an entity receives a value not defined here, it MUST ignore the attribute and MUST return a <bad-request/> error to the sender. There is no default value for the 'action' attribute.

7.2.1 content-accept

The content-accept action is used to accept a content-add action received from another party.

7.2.2 content-add

The content-add action is used to add one or more new content definitions to the session. The sender MUST specify only the added content definition(s), not the added content definition(s) plus the existing content definition(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content definition(s). If the recipient wishes to include the new content definition in the session, it MUST send a content-accept action to the other party; if not, it MUST send a content-reject action to the other party.

7.2.3 content-modify

The content-modify action is used to change the direction of an existing content definition through modification of the 'senders' attribute. If the recipient deems the directionality of a content-modify action to be unacceptable, it MAY reply with a contrary content-modify action, terminate the session, or simply refuse to send or accept application data in the new direction. In any case, the recipient MUST NOT send a content-accept action in response to the content-modify.

7.2.4 content-reject

The content-reject action is used to reject a content-add action received from another party.

If the content-reject results in zero content definitions for the session, the entity that receives the content-reject SHOULD send a session-terminate action to the other party (since a session with no content definitions is void).

7.2.5 content-remove

The content-remove action is used to remove one or more content definitions from the session. The sender MUST specify only the removed content definition(s), not the removed content definition(s) plus the remaining content definition(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content definition(s). Upon receiving a content-remove from the other party, the recipient MUST NOT send a content-accept and MUST NOT continue to negotiate the transport method or send application data related to that content definition.

If the content-remove results in zero content definitions 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 definitions is void).

7.2.6 description-info

The description-info action is used to send informational hints about parameters related to the application type, such as the suggested height and width of a video display area or suggested configuration for an audio stream.

7.2.7 security-info

The security-info action is used to send information related to establishment or maintenance of security preconditions.

7.2.8 session-accept

The session-accept action is used to definitively accept a session negotiation (implicitly this action also serves as a content-accept). A session-accept action indicates a willingness to proceed with the session (which might necessitate further negotiation before media can be exchanged). The session-accept action indicates acceptance only of the content definition(s) whose disposition type is "session" (the default value of the <content/> element's 'disposition' attribute), not any content definition(s) whose disposition type is something other than "session" (e.g., "early-session" for early media).

In the session-accept stanza, the <jingle/> element MUST contain one or more <content/> elements, each of which MUST contain one <description/> element and one <transport/> element.

7.2.9 session-info

The session-info action is used to send session-level information, such as a session ping or (for Jingle RTP sessions) a ringing message.

7.2.10 session-initiate

The session-initiate action is used to request negotiation of a new Jingle session. When sending a session-initiate with one <content/> element, the value of the <content/> element's 'disposition' attribute MUST be "session" (if there are multiple <content/> elements then at least one MUST have a disposition of "session"); if this rule is violated, the responder MUST return a <bad-request/> error to the initiator.

7.2.11 session-terminate

The session-terminate action is used to end an existing session.

7.2.12 transport-accept

The transport-accept action is used to accept a transport-replace action received from another party.

7.2.13 transport-info

The transport-info action is used to exchange transport candidates; it is mainly used in Jingle ICE-UDP but might be used in other transport specifications.

7.2.14 transport-reject

The transport-reject action is used to reject a transport-replace action received from another party.

7.2.15 transport-replace

The transport-replace action is used to redefine a transport method, typically for fallback to a different method (e.g., changing from ICE-UDP to Raw UDP for a datagram transport, or changing from SOCKS5 Bytestreams (XEP-0065) [25] to In-Band Bytestreams (XEP-0047) [26] for a streaming transport). If the recipient wishes to use the new transport definition, it MUST send a transport-accept action to the other party; if not, it MUST send a transport-reject action to the other party.

7.2.16 Tie Breaking Related to Jingle Actions

It is possible that the same Jingle action can be sent at the same time by both parties. There are two possible scenarios:

No existing session: If there is no existing session and both parties simultaneously send a Jingle session-initiate message with a content-type that is functionally equivalent (e.g., each message requests initiation of a voice call), the action with the lower of the two session IDs MUST overrule the other action, where by "lower" is meant the session ID that is sorted first using "i;octet" collation as specified in Section 9.3 of RFC 4790 [27] (in the unlikely event that the random session IDs are the same, the action sent by the lower of the JabberIDs MUST overrule the other action). The party that receives the session-initiate action with the lower of the two session IDs MUST acknowledge the action or return an error condition that would normally be returned when receiving a session-initiate message, and the party that receives the session-initiate action with the higher of the two session IDs MUST return a <conflict/> error to the other party, which SHOULD include a Jingle-specific condition of <tie-break/>.
Existing session: In the context of an existing session, the action sent by the initiator MUST overrule the action sent by the responder; i.e., both parties MUST accept the action sent by the initiator and the initiator MUST return a <conflict/> error to the responder for the duplicate action, which SHOULD include a Jingle-specific condition of <tie-break/>.

In both scenarios, the error to be returned is <conflict/>, as shown in the following example.

Example 34. Initiator returns conflict error on tie-break

<iq from='romeo@montague.lit/orchard'
    id='hb2f164w'
    to='juliet@capulet.lit/balcony'
    type='error'>
  <error type='cancel'>
    <conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <tie-break xmlns='urn:xmpp:jingle:errors:1'/>
  </error>
</iq>

7.3 Content Element

The attributes of the <content/> element are as follows.

Table 2: Attributes of Content Element

Attribute	Definition	Inclusion
creator	Which party originally generated the content type (used to prevent race conditions regarding modifications); the defined values are "initiator" and "responder" (where the default is "initiator"). The value of the 'creator' attribute for a given content type MUST always match the party that originally generated the content type, even for Jingle actions that are sent by the other party in relation to that content type (e.g., subsequent content-modify or transport-info messages). The combination of the 'creator' attribute and the 'name' attribute is unique among both parties to a Jingle session.	REQUIRED
disposition	How the content definition is to be interpreted by the recipient. The meaning of this attribute matches the "Content-Disposition" header as defined in RFC 2183 [28] and applied to SIP by RFC 3261. The value of this attribute SHOULD be one of the values registered in the IANA Mail Content Disposition Values and Parameters Registry [29]. The default value of this attribute is "session".	OPTIONAL
name	A unique name or identifier for the content type according to the creator, which MAY have meaning to a human user in order to differentiate this content type from other content types (e.g., two content types containing video media could differentiate between "room-pan" and "slides"). If there are two content types with the same value for the 'name' attribute, they shall understood as alternative definitions for the same purpose (e.g., a legacy method and a standards-based method for establishing a voice call), typically to smooth the transition from an older technology to Jingle.	REQUIRED
senders	Which parties in the session will be generating content (i.e., the direction in which a Jingle session is active); the allowable values are "both", "initiator", "none", and "responder" (where the default is "both"). Note that the defined values of the 'senders' attribute in Jingle correspond to the SDP attributes of "sendrecv", "sendonly", "inactive", and "recvonly" defined in RFC 4566 [30] and used in the offer-answer model RFC 3264 [31].	OPTIONAL except when sending content-modify, in which case it is REQUIRED.

7.4 Reason Element

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

The <reason/> element MUST contain an element that provides machine-readable information about the condition that prompted the action.
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 more detailed machine-readable information about the reason for the action.

A <reason/> element can be included with any Jingle action, and is not limited to session termination events.

The defined conditions are described in the following table.

Table 3: Defined Conditions

Element	Description
<alternative-session/>	The party prefers to use an existing session with the peer rather than initiate a new session; the Jingle session ID of the alternative session SHOULD be provided as the XML character data of the <sid/> child.
<busy/>	The party is busy and cannot accept a session.
<cancel/>	The initiator wishes to formally cancel the session initiation request.
<connectivity-error/>	The action is related to connectivity problems.
<decline/>	The party wishes to formally decline the session.
<expired/>	The session length has exceeded a pre-defined time limit (e.g., a meeting hosted at a conference service).
<failed-application/>	The party has been unable to initialize processing related to the application type.
<failed-transport/>	The party has been unable to establish connectivity for the transport method.
<general-error/>	The action is related to a non-specific application error.
<gone/>	The entity is going offline or is no longer available.
<incompatible-parameters/>	The party supports the offered application type but does not support the offered or negotiated parameters.
<media-error/>	The action is related to media processing problems.
<security-error/>	The action is related to a violation of local security policies.
<success/>	The action is generated during the normal course of state management and does not reflect any error.
<timeout/>	A request has not been answered so the sender is timing out the request.
<unsupported-applications/>	The party supports none of the offered application types.
<unsupported-transports/>	The party supports none of the offered transport methods.

8. Transport Types

8.1 Datagram

A datagram transport has one or more components with which to exchange packets with UDP-like behavior. Packets might be of arbitrary length, might be received out of order, and might not be received at all (i.e., the transport is lossy). Each component is assigned a string identifier and has a maximum packet length.

Applications compatible with datagram transports MUST specify how many components are necessary, what identifier to assign each component, and how each component will be used.

8.2 Streaming

A streaming transport has one or more components with which to exchange bidirectional bytestreams with TCP-like behavior. Bytes are received reliably and in order, and applications MUST NOT rely on a stream being chunked in any specific way. Each component is assigned a string identifier and has a maximum packet length.

Applications compatible with stream transports MUST specify how many components are necessary, what identifier to assign each component, and what data shall be exchanged over the transport.

9. Security Preconditions

The initiator MAY include a <security/> element in its offer to signal that it wishes to enforce some security precondition on the session. A stub example follows.

<iq from='romeo@montague.lit/orchard'
    id='tiw51bv9'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-initiate'
          initiator='romeo@montague.lit/orchard'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='this-is-a-stub'>
      <description xmlns='urn:xmpp:jingle:apps:stub:0'/>
      <transport xmlns='urn:xmpp:jingle:transports:stub:0'/>
      <security xmlns='urn:xmpp:jingle:security:stub:0'/>
    </content>
  </jingle>
</iq>

Currently the only security precondition that is envisioned will enforce the use of end-to-end encryption for the transport before application data can be exchanged. This document does not define any security preconditions, just as it does not define any application types or transport methods. See Jingle XTLS [32] for an in-progress description of a security precondition using Transport Layer Security (TLS).

In order to exchange information about the establishment or maintenance of a security precondition, either party might send a Jingle security-info message. For example, when attempting to negotiate the use of TLS the initiator might send hints about his supported TLS methods (e.g., X.509 certificates and Secure Remote Password) in his session-initiate message and the responder might also send hints about her supported methods (e.g., X.509 and SRP) in her session-accept message; however, it is possible that the initiator might be able to verify the responder's certificate and therefore needs to inform the responder (via a security-info message) that he can in the end support only the X.509 method for this negotiation. An example follows.

<iq from='romeo@montague.lit/orchard'
    id='zyw6m167'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='security-info'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='xmlstream'>
      <security xmlns='urn:xmpp:jingle:security:xtls:0'>
        <method name='x509'/>
      </security>
    </content>
  </jingle>
</iq>

If one of the parties attempts to send information over the unsecured XMPP signalling channel that the other party expects to receive over the encrypted data channel, the receiving party SHOULD return a <not-acceptable/> error to the sender, including a <security-required/> element qualified by the 'urn:xmpp:jingle:errors:1' namespace. An example follows.

<iq from='romeo@montague.lit/orchard'
    id='bsi381f5'
    to='juliet@capulet.lit/balcony'
    type='error'>
  <error type='cancel'>
    <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <security-required xmlns='urn:xmpp:jingle:errors:1'/>
  </error>
</iq>

10. Error Handling

The Jingle-specific error conditions are as follows. These condition elements are qualified by the 'urn:xmpp:jingle:errors:1' namespace (see Namespace Versioning regarding the possibility of incrementing the version number).

Table 4: Error Conditions

Jingle Condition	XMPP Condition	Description
<out-of-order/>	<unexpected-request/>	The request cannot occur at this point in the state machine (e.g., session-initiate after session-accept).
<tie-break/>	<conflict/>	The request is rejected because it was sent while the initiator was awaiting a reply on a similar request.
<unknown-session/>	<item-not-found/>	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-info/>	<feature-not-implemented/>	The recipient does not support the informational payload of a session-info action.

11. Determining Support

If an entity supports Jingle, it MUST advertise that fact by returning a feature of "urn:xmpp:jingle:1" (see Namespace Versioning regarding the possibility of incrementing the version number) in response to a Service Discovery (XEP-0030) [33] 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.

<iq from='kingclaudius@shakespeare.lit/castle'
    id='ku6e51v3'
    to='laertes@shakespeare.lit/castle'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

<iq from='laertes@shakespeare.lit/castle'
    id='ku6e51v3'
    to='kingclaudius@shakespeare.lit/castle'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='urn:xmpp:jingle:1'/>
    <feature var='urn:xmpp:jingle:apps:rtp:1'/>
    <feature var='urn:xmpp:jingle:apps:rtp:audio'/>
    <feature var='urn:xmpp:jingle:apps:rtp:video'/>
  </query>
</iq>

In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in Entity Capabilities (XEP-0115) [34]. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.

12. Conformance by Using Protocols

12.1 Application Formats

A document that specifies a Jingle application format (e.g., RTP sessions) MUST define:

How successful application format negotiation occurs.
A <description/> element and associated semantics for representing the application format.
If and how the application format can be mapped to the Session Description Protocol, including the appropriate SDP media type (see Section 8.2.1 of RFC 4566).
Whether the media data for the application format shall be sent over a streaming transport method or a datagram transport method (or, if both, which is preferred).
If the chosen transport handles "components", define how the components shall be identified and assigned.
Exactly how the media data is to be sent and received over a streaming or datagram transport.

12.2 Transport Methods

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

How successful transport negotiation occurs.
A <transport/> element and associated semantics for representing the transport method.
Whether the transport is a streaming method or a datagram method.
If the transport supports multiple components.

12.3 Security Preconditions

A document that specifies a Jingle security precondition MUST define:

A <security/> element and associated semantics for representing the security precondition.
Whether the security precondition applies to streaming transport methods, datagram transport methods, or both.
When the precondition is met so that application data can be sent over the negotiated transport.

13. Security Considerations

13.1 Transport Security

It is strongly recommended to protect the transport method using an appropriate security precondition (e.g., Transport Layer Security). However, methods for doing so are out of scope for this specification.

13.2 Denial of Service

Jingle sessions can 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.

13.3 Communication Through Gateways

Jingle communications can be enabled through gateways to non-XMPP networks, whose security characteristics can 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.

13.4 Information Exposure

Mere negotiation of a Jingle session can expose sensitive information about the parties (e.g., IP addresses, or even the full JID of the responder). 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.

13.5 Redirection

The 'initiator' and 'responder' attributes can be used to redirect a session from one JID to another JID (i.e., the 'initiator' or 'responder' attribute might not match the 'from' or 'to' attribute of the sender). An application SHOULD NOT accept the redirection unless the bare JIDs match (i.e., the session is being redirected from one authorized resource to another authorized resource associated with the same account).

14. IANA Considerations

15. XMPP Registrar Considerations

15.1 Protocol Namespaces

This specification defines the following XML namespaces:

urn:xmpp:jingle:1
urn:xmpp:jingle:errors:1

The XMPP Registrar [36] includes the foregoing namespaces in its registry at <http://xmpp.org/registrar/namespaces.html>, as governed by XMPP Registrar Function (XEP-0053) [37].

15.2 Namespace Versioning

If the protocol defined in this specification undergoes a revision that is not fully backwards-compatible with an older version, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of XEP-0053.

15.3 Jingle Application Formats Registry

The XMPP Registrar maintains a registry of Jingle application formats at <http://xmpp.org/registrar/jingle-apps.html>. All application format 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:app:name:X" (where "name" is the registered name of the application format and "X" is a non-negative integer).

In order to submit new values to this registry, the registrant shall define an XML fragment of the following form and either include it in the relevant XMPP Extension Protocol or send it to the email address <registrar@xmpp.org>:

<application>
  <name>The name of the application format.</name>
  <desc>A natural-language summary of the application format.</desc>
  <transport>
    Whether the media can be sent over a "streaming" transport, 
    a "datagram" transport, or "both".
  </transport>
  <doc>The document in which the application format is specified.</doc>
</application>

15.4 Jingle Transport Methods Registry

The XMPP Registrar maintains a registry of Jingle transport methods at <http://xmpp.org/registrar/jingle-transports.html>. 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).

<transport>
  <name>The name of the transport method.</name>
  <desc>A natural-language summary of the transport method.</desc>
  <type>
    Whether the transport method can be "streaming", "datagram", 
    or "both".
  </type>
  <doc>The document in which this transport method is specified.</doc>
</transport>

16. XML Schemas

16.1 Jingle

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:jingle:1'
    xmlns='urn:xmpp:jingle:1'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0166: http://www.xmpp.org/extensions/xep-0166.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='jingle'>
    <xs:complexType>
      <xs:sequence>
        <xs:element name='content' 
                    type='contentElementType'
                    minOccurs='0' 
                    maxOccurs='unbounded'/>
        <xs:element name='reason' 
                    type='reasonElementType'
                    minOccurs='0' 
                    maxOccurs='1'/>
        <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='action' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='content-accept'/>
            <xs:enumeration value='content-add'/>
            <xs:enumeration value='content-modify'/>
            <xs:enumeration value='content-reject'/>
            <xs:enumeration value='content-remove'/>
            <xs:enumeration value='description-info'/>
            <xs:enumeration value='security-info'/>
            <xs:enumeration value='session-accept'/>
            <xs:enumeration value='session-info'/>
            <xs:enumeration value='session-initiate'/>
            <xs:enumeration value='session-terminate'/>
            <xs:enumeration value='transport-accept'/>
            <xs:enumeration value='transport-info'/>
            <xs:enumeration value='transport-reject'/>
            <xs:enumeration value='transport-replace'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name='initiator' type='xs:string' use='optional'/>
      <xs:attribute name='responder' type='xs:string' use='optional'/>
      <xs:attribute name='sid' type='xs:NMTOKEN' use='required'/>
    </xs:complexType>
  </xs:element>

  <xs:complexType name='alternativeSessionElementType'>
    <xs:sequence>
      <xs:element name='sid'
                  minOccurs='0'
                  maxOccurs='1'
                  type='xs:NMTOKEN'/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name='contentElementType'>
    <xs:sequence>
      <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
    </xs:sequence>
    <xs:attribute name='creator'
                  use='required'>
      <xs:simpleType>
        <xs:restriction base='xs:NCName'>
          <xs:enumeration value='initiator'/>
          <xs:enumeration value='responder'/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
    <xs:attribute name='disposition'
                  use='optional'
                  type='xs:NCName'
                  default='session'/>
    <xs:attribute name='name'
                  use='required'
                  type='xs:string'/>
    <xs:attribute name='senders'
                  use='optional'
                  default='both'>
      <xs:simpleType>
        <xs:restriction base='xs:NCName'>
          <xs:enumeration value='both'/>
          <xs:enumeration value='initiator'/>
          <xs:enumeration value='none'/>
          <xs:enumeration value='responder'/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
  </xs:complexType>

  <xs:complexType name='reasonElementType'>
    <xs:sequence>
      <xs:choice>
        <xs:element name='alternative-session' 
                    type='alternativeSessionElementType'/>
        <xs:element name='busy' type='empty'/>
        <xs:element name='cancel' type='empty'/>
        <xs:element name='connectivity-error' type='empty'/>
        <xs:element name='decline' type='empty'/>
        <xs:element name='expired' type='empty'/>
        <xs:element name='failed-application' type='empty'/>
        <xs:element name='failed-transport' type='empty'/>
        <xs:element name='general-error' type='empty'/>
        <xs:element name='gone' type='empty'/>
        <xs:element name='incompatible-parameters' type='empty'/>
        <xs:element name='media-error' type='empty'/>
        <xs:element name='security-error' type='empty'/>
        <xs:element name='success' type='empty'/>
        <xs:element name='timeout' type='empty'/>
        <xs:element name='unsupported-applications' type='empty'/>
        <xs:element name='unsupported-transports' type='empty'/>
      </xs:choice>
      <xs:element name='text' type='xs:string' minOccurs='0' maxOccurs='1'/>
      <xs:any namespace='##other' minOccurs='0' maxOccurs='1'/>
    </xs:sequence>
  </xs:complexType>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>

16.2 Jingle Errors

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:jingle:errors:1'
    xmlns='urn:xmpp:jingle:errors:1'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0166: http://www.xmpp.org/extensions/xep-0166.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='out-of-order' type='empty'/>
  <xs:element name='tie-break' type='empty'/>
  <xs:element name='unknown-session' type='empty'/>
  <xs:element name='unsupported-info' type='empty'/>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>

17. History

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 A Transport for Initiating and Negotiating Sessions (XEP-0111) [38], 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. [39]

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

Implementation experience indicates that a dual-stack approach might not be feasible on all the computing platforms for which Jabber clients have been written, or even desirable on platforms where it is feasible. [40] 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, [41] 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.

18. Acknowledgements

The authors would like to thank Rohan Mahy for his valuable input on early versions of the Jingle specifications. Thiago Camargo, Diana Cionoiu, Olivier Crête, Dafydd Harries, Antti Ijäs, Tim Julien, Lauri Kaila, Justin Karneges, Jussi Laako, Steffen Larsen, Marcus Lundblad, Dirk Meyer, Anthony Minessale, Akito Nozaki, Matt O'Gorman, Mike Ruprecht, Rob Taylor, Will Thompson, Matt Tucker, Justin Uberti, Saku Vainio, Unnikrishnan Vikrama Panicker, Brian West, Jeff Williams, and others have also provided helpful input. Thanks also to those who have commented on the Standards SIG [42] and Jingle [43] mailing lists.

Appendices

Appendix A: Document Information

Appendix B: Author Information

Appendix C: Legal Notices

Copyright

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <http://xmpp.org/about-xmpp/xsf/xsf-ipr-policy/> or obtained by writing to XMPP Standards Foundation, 1899 Wynkoop Street, Suite 600, Denver, CO 80202 USA).

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue

There exists a special venue for discussion related to the technology described in this document: the <jingle@xmpp.org> mailing list.

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Appendix G: Notes

1. XEP-0167: Jingle RTP Sessions <http://xmpp.org/extensions/xep-0167.html>.

2. XEP-0234: Jingle File Transfer <http://xmpp.org/extensions/xep-0234.html>.

3. XEP-0247: Jingle XML Streams <http://xmpp.org/extensions/xep-0247.html>.

4. RFC 768: User Datagram Protocol <http://tools.ietf.org/html/rfc0768>.

5. XEP-0177: Jingle Raw UDP Transport Method <http://xmpp.org/extensions/xep-0177.html>.

6. XEP-0176: Jingle ICE-UDP Transport Method <http://xmpp.org/extensions/xep-0176.html>.

7. RFC 793: Transmission Control Protocol <http://tools.ietf.org/html/rfc0793>.

8. XEP-0065: SOCKS5 Bytestreams <http://xmpp.org/extensions/xep-0065.html>.

9. XEP-0260: Jingle SOCKS5 Bytestreams Transport Method <http://xmpp.org/extensions/xep-0260.html>.

10. XEP-0047: In-Band Bytestreams <http://xmpp.org/extensions/xep-0047.html>.

11. XEP-0261: Jingle In-Band Bytestreams Transport Method <http://xmpp.org/extensions/xep-0261.html>.

12. RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 <http://tools.ietf.org/html/rfc5246>.

13. RFC 4347: Datagram Transport Layer Security <http://tools.ietf.org/html/rfc4347>.

14. The XMPP Standards Foundation (XSF) is an independent, non-profit membership organization that develops open extensions to the IETF's Extensible Messaging and Presence Protocol (XMPP). For further information, see <http://xmpp.org/xsf/>.

15. The Internet Engineering Task Force is the principal body engaged in the development of new Internet standard specifications, best known for its work on standards such as HTTP and SMTP. For further information, see <http://www.ietf.org/>.

16. RFC 3261: Session Initiation Protocol (SIP) <http://tools.ietf.org/html/rfc3261>.

17. Naturally, more complex scenarios are possible; such scenarios are described in other specifications, such as Jingle RTP Sessions for voice and video chat.

18. RFC 4566: SDP: Session Description Protocol <http://tools.ietf.org/html/rfc4566>.

19. Extensible Messaging and Presence Protocol (XMPP) End-to-End Encryption Using Transport Layer Security ("XTLS") <http://tools.ietf.org/html/draft-meyer-xmpp-e2e-encryption>.

20. ITU Recommendation H.323: Packet-based Multimedia Communications Systems (September 1999).

21. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://tools.ietf.org/html/rfc3921>.

22. XEP-0251: Jingle Session Transfer <http://xmpp.org/extensions/xep-0251.html>.

23. See <http://www.w3.org/TR/2000/WD-xml-2e-20000814#NT-Nmtoken>

24. RFC 4086: Randomness Requirements for Security <http://tools.ietf.org/html/rfc4086>.

25. XEP-0065: SOCKS5 Bytestreams <http://xmpp.org/extensions/xep-0065.html>.

26. XEP-0047: In-Band Bytestreams <http://xmpp.org/extensions/xep-0047.html>.

27. RFC 4790: Internet Application Protocol Collation Registry <http://tools.ietf.org/html/rfc4790>.

28. RFC 2183: Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field <http://tools.ietf.org/html/rfc2183>.

29. IANA registry of Mail Content Disposition Values and Parameters <http://www.iana.org/assignments/mail-cont-disp>.

30. RFC 4566: SDP: Session Description Protocol <http://tools.ietf.org/html/rfc4566>.

31. RFC 3264: An Offer/Answer Model with the Session Description Protocol (SDP) <http://tools.ietf.org/html/rfc3264>.

32. Extensible Messaging and Presence Protocol (XMPP) End-to-End Encryption Using Transport Layer Security ("XTLS") <http://tools.ietf.org/html/draft-meyer-xmpp-e2e-encryption>.

33. XEP-0030: Service Discovery <http://xmpp.org/extensions/xep-0030.html>.

34. XEP-0115: Entity Capabilities <http://xmpp.org/extensions/xep-0115.html>.

35. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

36. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://xmpp.org/registrar/>.

37. XEP-0053: XMPP Registrar Function <http://xmpp.org/extensions/xep-0053.html>.

38. XEP-0111: A Transport for Initiating and Negotiating Sessions <http://xmpp.org/extensions/xep-0111.html>.

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

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

41. Google Talk is an instant messaging and voice/video chat service and client provided by Google; see <http://www.google.com/talk/>.

42. The Standards SIG is a standing Special Interest Group devoted to development of XMPP Extension Protocols. The discussion list of the Standards SIG is the primary venue for discussion of XMPP protocol extensions, as well as for announcements by the XMPP Extensions Editor and XMPP Registrar. To subscribe to the list or view the list archives, visit <http://mail.jabber.org/mailman/listinfo/standards/>.

43. 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. This list has since been resurrected as a special-purpose venue for discussion of Jingle protocols and implementation; interested developers can subscribe and access the archives at at <http://mail.jabber.org/mailman/listinfo/jingle/>.

Appendix H: Revision History

Version 1.1 (2009-12-23)

Specified handling of duplicate name attributes on content element; clarified recommended usage of Jingle when exchanging multiple content-types; declared the principle that application types ought not to be mixed beyond necessity within a single session; clarified use of the reason element in cases other than termination.

(psa/jjh)

Version 1.0 (2009-06-10)

Per a vote of the XMPP Council, advanced specification from Experimental to Draft; also required inclusion of the creator attribute per list consensus.

(psa)

Version 0.38 (2009-05-27)

Clarified and tightened handling of the initiator, responder, creator, and senders attributes.

(psa)

Version 0.37 (2009-04-20)

Specified tie-breaking for session-initiate action; incremented errors namespace to match core namespace; clarified some ambiguities in the text, examples, and state machine.

(psa)

Version 0.36 (2009-03-11)

Added none value for senders attribute.

(psa)

Version 0.35 (2009-03-06)

Added the concept of a security precondition to the Jingle framework, where preconditions are defined in separate specifications (just as application types and transport methods are).
Defined a new Jingle action of security-info.
Incremented the namespace to urn:xmpp:jingle:1 in order to reflect the addition of security preconditions and the security-info action.
Clarified a number of points about the overall session flow and state machine.
Added Jingle reasons for failed-application, failed-transport, and incompatible-parameters.

(psa)

Version 0.34 (2009-02-17)

Clarified the definitions and conformance requirements for datagram and streaming transports; tightened the security requirements regarding the initiator and responder attributes; updated examples to reflect changes to XEP-0176.

(psa)

Version 0.33 (2008-12-18)

Clarified handling of session timeouts.
Added description-info action.
Added cancel, expired, gone, security-error, and timeout reason conditions.
Changed XMPP error condition for Jingle <unknown-session/> condition from <bad-request/> to <item-not-found/>.
Changed XMPP error condition for Jingle tie breaks from <unexpected-request/> to <conflict/> and defined Jingle-specific condition of <tie-break/>.
Corrected schema.

(psa)

Version 0.32 (2008-10-07)

Added content-reject action to mirror content-accept for replies to content-add; also added transport-reject action to mirror transport-accept for replies to transport-replace.

(psa)

Version 0.31 (2008-09-25)

Added disposition attribute to content element for mapping to SIP Content-Disposition header.

(psa)

Version 0.30 (2008-09-23)

Allowed content-add in PENDING state.
Clarified that session-accept action accepts only the content definition(s) in the session-initiate.
Added optional thread element.
Clarified tie breaks for transport-replace.
Modified namespaces to incorporate namespace versioning.
Cleaned up XML schemas.

(ram/psa)

Version 0.29 (2008-07-31)

Changed "reliable" vs. "lossy" to "streaming" vs. "datagram", since reliability or dependability is orthogonal to the streaming nature of the transport.
Deleted the "content-remove" action.
Added "transport-replace" action (answered by "transport-accept").
Removed <condition/> element as container for Jingle condition elements inside <reason/>, since it introduced an unnecessary layer of indirection.
Modified state machine to allow content removal during PENDING state.
Noted that a session can have more than one content instance of the same type.
Noted that the 'name' attribute is unique to a creator.
Changed examples to once again use voice chat instead of file transfer.

(psa/ram)

Version 0.28 (2008-06-16)

Modified state machine to allow content-replace during PENDING state for more seamless handling of fallback scenarios.

(psa)

Version 0.27 (2008-06-04)

Updated examples to track changes to XEP-0167 and retraction of XEP-0180; corrected definition of name attribute to allow semantic meaning.

(psa)

Version 0.26 (2008-05-28)

Corrected several errors in the state diagrams.

(psa)

Version 0.25 (2008-02-29)

More clearly specified the content-replace action (essentially similar to content-add); specified that content-accept shall be sent in response to content-replace; removed content-modify and content-accept from PENDING state; adjusted text regarding initial session negotiation.

(psa)

Version 0.24 (2008-02-28)

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.

(ram/psa)

Version 0.23 (2008-01-11)

Removed content-accept after content-remove; removed errors for unsupported-content and unsupported-transports since they are handled via session-terminate; clarified handling of responder attribute.

(psa)

Version 0.22 (2007-12-06)

Modified session flows for busy, unsupported application formats, and unsupported transport methods to enable separation between Jingle core and distinct modules for applications and transports; moved resource determination recommendations to XEP-208.

(psa)

Version 0.21 (2007-11-27)

Further editorial review.

(psa)

Version 0.20 (2007-11-15)

Editorial review and consistency check; moved voice chat scenarios to XEP-0167.

(psa)

Version 0.19 (2007-11-13)

Added scenario for handling of busy state, including Jingle-specific error code and modified error flow (no longer an instance of decline).

(psa)

Version 0.18 (2007-11-08)

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

(psa)

Version 0.17 (2007-06-20)

Added <unsupported-info/> error.

(psa)

Version 0.16 (2007-06-06)

Clarified resource determination process and updated text to reflect modifications to XEP-0168.

(psa)

Version 0.15 (2007-05-25)

Rewrote introduction and moved historical text to separate section.

(psa)

Version 0.14 (2007-04-17)

Clarified session lifetime; defined reason attribute and associated registry; further specified conformance requirements.

(psa)

Version 0.13 (2007-03-23)

Simplified signalling process and state chart; Removed session-redirect action (use redirect error instead); removed content-decline action; removed transport-* actions (except transport-info for ICE negotiation); removed description-* actions; simplified syntax to allow only one transport per content type; corrected syntax of creator attribute to be either initiator or responder (not JIDs); added profile attribute to content element in order to specify RTP profile in use.

(psa/ram)

Version 0.12 (2006-12-21)

Added creator attribute to content element for prevention of race condition; modified spec to use provisional namespace before advancement to Draft (per XEP-0053).

(psa/ram)

Version 0.11 (2006-10-31)

Completed clarifications and corrections throughout; added section on Jingle Actions.

(psa)

Version 0.10 (2006-09-29)

Made several corrections to the state machines and examples.

(ram/psa)

Version 0.9 (2006-09-08)

Further cleaned up state machines and state-related actions.

(ram/psa)

Version 0.8 (2006-08-23)

Changed channels to components in line with ICE; changed various action names for consistency; added session-extend and session-reduce actions to add and remove description/transport pairs; added description-modify action; added sender attribute to specify directionality.

(ram/psa)

Version 0.7 (2006-07-17)

Added implementation note about handling multiple content types.

(psa)

Version 0.6 (2006-07-12)

Changed media type to content type.

(se/psa)

Version 0.5 (2006-03-20)

Further clarified state machine diagrams; specified that session accept must include agreed-upon media format and transport description; moved deployment notes to appropriate transport spec.

(psa/jb)

Version 0.4 (2006-03-01)

Added glossary; clarified state machines; updated to reflect publication of XEP-0176 and XEP-0177.

(psa/jb)

Version 0.3 (2006-02-24)

Provided more detail about modify scenarios; defined media-specific and transport-specific actions and adjusted state machine accordingly.

(psa/jb)

Version 0.2 (2006-02-13)

Per agreement among the co-authors, moved transport definition to separate specification, simplified state machine, and made other associated changes to the text, examples, and schemas; also harmonized redirect, decline, and terminate processes.

(psa/jb)

Version 0.1 (2005-12-15)

Initial version.

(psa)

Version 0.0.10 (2005-12-11)

More fully documented burst mode, connectivity checks, error cases, etc.

(psa)

Version 0.0.9 (2005-12-08)

Restructured document flow; provided example of burst mode.

(psa)

Version 0.0.8 (2005-12-05)

Distinguished between dribble mode and burst mode, including mode attribute, service discovery features, and implementation notes; provided detailed resource discovery examples; corrected state chart; specified session termination; specified error conditions; specified semantics of informational messages; began to define security considerations; added Joe Beda as co-author.

(psa/sl/jb)

Version 0.0.7 (2005-11-08)

Added more detail to basic session flow; harmonized candidate negotiation process with ICE.

(psa)

Version 0.0.6 (2005-10-27)

Added XMPP Registrar considerations; defined schema; completed slight syntax cleanup.

(psa)

Version 0.0.5 (2005-10-21)

Separated method description formats from signalling protocol.

(psa/sl)

Version 0.0.4 (2005-10-19)

Harmonized basic session flow with Google Talk protocol; added Scott Ludwig as co-author.

(psa/sl)

Version 0.0.3 (2005-10-10)

Added more detail to basic session flow.

(psa)

Version 0.0.2 (2005-10-07)

Protocol cleanup.

(psa/jjh)

Version 0.0.1 (2005-10-06)

First draft.

(psa/jjh)

Abstract:	This specification defines an XMPP protocol extension for initiating and managing peer-to-peer media sessions between two XMPP entities in a way that is interoperable with existing Internet standards. The protocol provides a pluggable model that enables the core session management semantics (compatible with SIP) to be used for a wide variety of application types (e.g., voice chat, video chat, file transfer) and with a wide variety of transport methods (e.g., TCP, UDP, ICE, application-specific transports).
Authors:	Scott Ludwig, Joe Beda, Peter Saint-Andre, Robert McQueen, Sean Egan, Joe Hildebrand
Copyright:	© 1999 - 2016 XMPP Standards Foundation. SEE LEGAL NOTICES.
Status:	Draft
Type:	Standards Track
Version:	1.1
Last Updated:	2009-12-23

XEP-0166: Jingle

Table of Contents

1. Introduction

2. How It Works

3. Requirements

4. Terminology

4.1 Glossary

4.2 Conventions

5. Concepts and Approach

5.1 Overall Session Management

6. Session Flow

6.1 Resource Determination

6.2 Initiation

6.3 Responder Response

6.3.1 Acknowledgement

6.3.2 Errors

6.4 Negotiation

6.5 Acceptance

6.6 Modifying an Active Session

6.7 Termination

6.8 Informational Messages

7. Formal Definition

7.1 Jingle Element

7.2 Action Attribute

7.2.1 content-accept

7.2.2 content-add

7.2.3 content-modify

7.2.4 content-reject

7.2.5 content-remove

7.2.6 description-info

7.2.7 security-info

7.2.8 session-accept

7.2.9 session-info

7.2.10 session-initiate

7.2.11 session-terminate

7.2.12 transport-accept

7.2.13 transport-info

7.2.14 transport-reject

7.2.15 transport-replace

7.2.16 Tie Breaking Related to Jingle Actions

7.3 Content Element

7.4 Reason Element

8. Transport Types

8.1 Datagram

8.2 Streaming

9. Security Preconditions

10. Error Handling

11. Determining Support

12. Conformance by Using Protocols

12.1 Application Formats

12.2 Transport Methods

12.3 Security Preconditions

13. Security Considerations

13.1 Transport Security

13.2 Denial of Service

13.3 Communication Through Gateways

13.4 Information Exposure

13.5 Redirection

14. IANA Considerations

15. XMPP Registrar Considerations

15.1 Protocol Namespaces

15.2 Namespace Versioning

15.3 Jingle Application Formats Registry

15.4 Jingle Transport Methods Registry

16. XML Schemas

16.1 Jingle

16.2 Jingle Errors

17. History

18. Acknowledgements

Appendices

Appendix A: Document Information

Appendix B: Author Information

Scott Ludwig

Joe Beda

Peter Saint-Andre

Robert McQueen

Sean Egan

Joe Hildebrand

Appendix C: Legal Notices

Copyright