XEP-0166: Jingle

Table 1: Glossary

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

<iq from='romeo@montague.net/orchard'
    id='jingle1'
    to='juliet@capulet.com/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:0'>
          action='session-initiate'
          initiator='romeo@montague.net/orchard'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='voice'>
      <description xmlns='urn:xmpp:jingle:apps:rtp:0' 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:0'/>
    </content>
  </jingle>
</iq>
    

<iq from='juliet@capulet.com/balcony'
    id='jingle1'
    to='romeo@montague.net/orchard'
    type='error'>
  <error type='cancel'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <unknown-session xmlns='urn:xmpp:jingle:errors:0'/>
  </error>
</iq>
    

6.3.1 Acknowledgement

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

Example 9. Responder acknowledges session-initiate

<iq from='juliet@capulet.com/balcony'
    id='jingle1'
    to='romeo@montague.net/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 [14] or stanza session negotiation as defined in Stanza Session Negotiation [15]) and the responder has a policy of not communicating via Jingle with unknown entities, it MUST return a <service-unavailable/> error.

Example 10. Initiator is unknown to responder

<iq from='juliet@capulet.com/balcony'
    id='jingle1'
    to='romeo@montague.net/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 11. Responder does not support Jingle

<iq from='juliet@capulet.com/balcony'
    id='jingle1'
    to='romeo@montague.net/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 12. Responder redirection

<iq from='juliet@capulet.com/balcony'
    id='jingle1'
    to='romeo@montague.net/orchard'
    type='error'>
  <error type='cancel'>
    <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 13. Responder has insufficent resources

<iq from='juliet@capulet.com/balcony'
    id='jingle1'
    to='romeo@montague.net/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 14. Initiation request malformed

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

<iq from='juliet@capulet.com/balcony'
    id='accept1'
    to='romeo@montague.net/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:0'
          action='session-accept'
          initiator='romeo@montague.net/orchard'
          responder='juliet@capulet.com/balcony'
          sid='a73sjjvkla37jfea'>
    <content creator='initiator' name='voice'>
      <description xmlns='urn:xmpp:jingle:apps:rtp:0' 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:0'>
        <candidate component='1'
                   foundation='1'
                   generation='0'
                   ip='192.0.2.3'
                   network='1'
                   port='45664'
                   priority='1678246398'
                   protocol='udp'
                   pwd='asd88fgpdd777uzjYhagZg'
                   type='srflx'
                   ufrag='8hhy'/>
      </transport>
    </content>
  </jingle>
</iq>
    

<iq from='romeo@montague.net/orchard'
    id='accept1'
    to='juliet@capulet.com/balcony'
    type='result'/>
    

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

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

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

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

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

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

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

<iq from='romeo@montague.lit/orchard'
    id='ringing1'
    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:0'/>
  </error>
</iq>
    

<iq from='juliet@capulet.com/balcony'
    id='ping1'
    to='romeo@montague.net/orchard'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:0'
          action='session-info'
          initiator='romeo@montague.net/orchard'
          sid='a73sjjvkla37jfea'/>
</iq>
    

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

Table 2: Attributes of Jingle Element

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.

7.2.3 content-modify

The content-modify action is used to change the direction of an existing content definition thorugh 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-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 related to that content definition or send application data related to that content definition. [17]

7.2.5 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 acceptance only of the content definition(s) included in the session-initiate, not any content definition(s) subsequently added during the PENDING state. 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. The <jingle/> element SHOULD possess a 'responder' attribute that explicitly specifies the full JID of the responding entity; after sending acknowledgement of the session-accept, the initiator SHOULD send all future commmunications about this Jingle session to the JID provided in the 'responder' attribute and note the new JID in the user interface.

7.2.6 session-info

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

7.2.7 session-initiate

The session-initiate action is used to request negotiation of a new Jingle session.

7.2.8 session-terminate

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

7.2.9 transport-accept

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

7.2.10 transport-info

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

7.2.11 transport-replace

The transport-replace action is used to redefine a transport method.

7.2.12 Tie Breaking Related to Jingle Actions

It is possible that two instances of certain actions can be sent at the same time in the context of an existing session, one by each party; for example, both parties might simulaneously attempt to send a content-add, content-modify, or content-remove action. In all such cases, 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 an <unexpected-request/> error to the responder for the duplicate action.

Table 3: Attributes of Content Element

Table 4: Defined Conditions

<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 "stream" transport, 
    a "datagram" transport, or "both".
  </transport>
  <doc>The document in which the application format is specified.</doc>
</application>
    

<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 "stream", "datagram", or "both"</type>
  <doc>the document in which this transport method is specified</doc>
</transport>
    

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

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

  <xs:element name='jingle'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='content' 
                    type='contentElementType'
                    minOccurs='0' 
                    maxOccurs='unbounded'/>
        <xs:element ref='reason' 
                    type='reasonElementType'
                    minOccurs='0' 
                    maxOccurs='1'/>
        <xs:element ref='thread' 
                    type='threadElementType'
                    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-remove'/>
            <xs:enumeration value='session-accept'/>
            <xs:enumeration value='session-info'/>
            <xs:enumeration value='session-initiate'/>
            <xs:enumeration value='session-terminate'/>
            <xs:enumeration value='transport-add'/>
            <xs:enumeration value='transport-info'/>
            <xs:enumeration value='transport-replace'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name='initiator' type='xs:string' use='required'/>
      <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'
                  maxOcccurs='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' default='initiator'>
      <xs:simpleType>
        <xs:restriction base='xs:NCName'>
          <xs:enumeration value='initiator'>
          <xs:enumeration value='responder'/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
    <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='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='connectivity-error' type='empty'/>
        <xs:element name='decline' type='empty'/>
        <xs:element name='general-error' type='empty'/>
        <xs:element name='invalid-credentials' type='empty'/>
        <xs:element name='media-error' type='empty'/>
        <xs:element name='no-error' type='empty'/>
        <xs:element name='success' 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:complexType name='threadElementType'>
    <xs:simpleContent>
      <xs:extension base='xs:NMTOKEN'>
        <xs:attribute name='parent'
                      type='xs:NMTOKEN'
                      use='optional'/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

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

</xs:schema>
    

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

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

  <xs:element name='out-of-order' 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>
    

• 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.
• Cleaned up XML schemas.

• Changed "reliable" vs. "lossy" to "stream" 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.

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

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

Corrected several errors in the state diagrams.

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.

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.

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.

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.

Further editorial review.

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

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

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

Added <unsupported-info/> error.

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

Rewrote introduction and moved historical text to separate section.

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

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.

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

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

Made several corrections to the state machines and examples.

Further cleaned up state machines and state-related actions.

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.

Added implementation note about handling multiple content types.

Changed media type to content type.

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.

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

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

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.

Initial version.

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

Restructured document flow; provided example of burst mode.

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.

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

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

Separated method description formats from signalling protocol.

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

Added more detail to basic session flow.

Protocol cleanup.

First draft.