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.

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.

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

As shown, there are three overall session states:

1. PENDING
2. ACTIVE
3. 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.

security-info

Exchange information about security preconditions.

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.

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.

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 &VNOTE;, 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.

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.

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.

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.

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.

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

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.

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

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

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

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.

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

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

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

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

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

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:

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.

Not all Jingle sessions end gracefully. When the parties to a Jingle session also exchange XMPP presence information, receipt of &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.

At any point after initiation of a Jingle session, either entity MAY send an informational message to the other party, for example to inform the other party that a device is ringing.

An informational message MUST be an IQ-set containing a &JINGLE; element whose 'action' attribute is set to a value of "session-info", "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; error with a Jingle-specific error condition of <unsupported-info/>.

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.

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.

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 &badrequest; error to the sender. There is no default value for the 'action' attribute.

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

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.

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.

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.

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

1. How successful application format negotiation occurs.
2. A &DESCRIPTION; element and associated semantics for representing the application format.
3. 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).
4. 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).
5. If the chosen transport handles "components", define how the components shall be identified and assigned.
6. Exactly how the media data is to be sent and received over a streaming or datagram transport.

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

1. How successful transport negotiation occurs.
2. A &TRANSPORT; element and associated semantics for representing the transport method.
3. Whether the transport is a streaming method or a datagram method.
4. If the transport supports multiple components.

A document that specifies a Jingle security precondition MUST define:

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

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.

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.

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.

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.

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

This specification defines the following XML namespaces:

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

The ®ISTRAR; includes the foregoing namespaces in its registry at &NAMESPACES;, as governed by &xep0053;.

The XMPP Registrar maintains a registry of Jingle application formats at &JINGLEAPPS;. 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).

The XMPP Registrar maintains a registry of Jingle transport methods at &JINGLETRANSPORTS;. 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).