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

There are three overall session states:

1. PENDING
2. ACTIVE
3. ENDED

The actions related to management of the overall Jingle session are as follows:

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

1. If the intended responder shares presence with the initiator (see &xmppim;) and has only one available resource, this task SHOULD be completed using &xep0030; or the presence-based profile of service discovery specified in &xep0115;. Naturally, instead of sending service discovery requests to every contact in a user's roster, it is more efficient to use Entity Capabilities, whereby support for Jingle and various Jingle content description formats and content transport methods is determined for a client version in general (rather than on a per-JID basis) and then cached. Refer to XEP-0115 for details.

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

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

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

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

The following example shows a Jingle session initiation request for a session that contains both audio and video content:

Note: The syntax and semantics of the &DESCRIPTION; and &TRANSPORT; elements are out of scope for this specification, but are defined in related specifications.

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

• The 'action' attribute is REQUIRED; it specifies a Jingle action as listed in this document (e.g., "session-initiate").
• The 'initiator' attribute is the full JID of the entity that has initiated the session flow (which may be different from the 'from' address on the IQ-set).
• The OPTIONAL 'reasoncode' attribute specifies a machine-readable purpose for the action being sent (e.g., "connectivity-error" for a session-terminate action).
• The OPTIONAL 'reasontext' attribute specifies a human-readable purpose for the action being sent (e.g., "Sorry, gotta go!" for a session-terminate action).
• The 'responder' attribute (see examples below) is the full JID of the entity that has replied to the initiation (which may be different from the 'to' address on the IQ-set).
• The 'sid' attribute is a random session identifier generated by the initiator; this SHOULD match the XML Nmtoken production See <http://www.w3.org/TR/2000/WD-xml-2e-20000814#NT-Nmtoken> so that XML character escaping is not needed for characters such as &. (Note: the 'sid' attribute effectively maps to the SIP "Call-ID" parameter.)

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

• The 'creator' attribute is REQUIRED; it specifies which party originally generated the content description (used to prevent race conditions regarding modifications).
• The 'name' attribute is REQUIRED; it specifies a unique name or identifier for the content type (this identifier is opaque and does not have semantic meaning).
• The 'profile' attribute is RECOMMENDED; for some content types, it specifies the profile in use (e.g., "RTP/AVP" in the context of the Real-time Transport Protocol).
• The 'senders' attribute is RECOMMENDED; it specifies which entities in the session will be generating content; the allowable values are "initiator", "recipient", or "both" (where "both" is the default).

Note: In order to expedite session establishment, the initiator MAY send transport candidates (e.g., for negotiation of the ICE transport) immediately after sending the "session-initiate" message and before receiving acknowledgement from the receiver (i.e., the initiator MUST consider the session to be live even before receiving acknowledgement). Given in-order delivery, the receiver should receive such "transport-info" messages after receiving the "session-initiate" message (if not, it is appropriate for the receiver to return <unknown-session/> errors since it according to its state machine the session does not exist).

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

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

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

• The initiator is unknown to the receiver (e.g., via presence subscription) and the receiver does not communicate with unknown entities.
• The receiver wishes to redirect to another address.
• The receiver does not support Jingle.
• The receiver does not support any of the specified content description formats.
• The receiver does not support any of the specified content transport methods.
• The initiation request was malformed.

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

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

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

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

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

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

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

In general, negotiation will be necessary before the parties can agree on an acceptable set of content types, content description formats, and content transport methods. The potential combinations of parameters to be negotiated are many, and not all are shown herein (some are shown in the relevant specifications for various content description formats and content transport methods).

One session-level negotiation is to remove a content types. For example, let us imagine that Juliet is having a bad hair day. She certainly does not want to include video in her Jingle session with Romeo, so she sends a "content-remove" request to Romeo:

The entity receiving the session reduction request then acknowledges the request:

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

Another session-level negotiation is to add a content type; however, this MUST NOT be done while the session is in the PENDING state and is allowed only while the session is in the ACTIVE state.

If (after negotiation of content transport methods and content description formats) the receiver determines that it will be able to establish a connection, it sends a definitive acceptance to the initiator:

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

The initiator then acknowledges the receiver's definitive acceptance:

Now the initiator and receiver can begin sending content over the negotiated connection.

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

In order to modify an active session, either party may send a "content-remove", "content-add", "content-modify", "description-modify", or "transport-modify" action to the other party. The receiving party then sends an appropriate "-accept" or "-decline" action, and may first send an appropriate "-info" action.

If both parties send modify messages at the same time, the modify message from the session initiator MUST trump the modify message from the recipient and the initiator SHOULD return an &unexpected; error to the other party.

One example of modifying an active session is to add a content type. For example, let us imagine that Juliet gets her hair in order and now wants to add video. She now sends a "content-add" request to Romeo:

The entity receiving the session extension request then acknowledges the request and, if it is acceptable, returns a content-accept:

The other party then acknowledges the acceptance.

In order to gracefully end the session (which MAY be done at any point after acknowledging receipt of the initiation request, including immediately thereafter in order to decline the request), either the receiver or the initiator MUST a send a "terminate" action to the other party:

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

Note: As soon as an entity sends a "session-terminate" action, it MUST consider the session to be ended (even before receiving acknowledgement from the other party). If the terminating entity receives additional IQ-sets from the other party after sending the "session-terminate" action, it MUST reply with an <unknown-session/> error.

Unfortunately, not all sessions end gracefully. In applications of Jingle that also involve the exchange of presence information, receipt of &UNAVAILABLE; from the other party MAY be a considered session-ending event. However, in this case there is nothing for the party to acknowledge.

At any point after initiation of a Jingle session, either entity MAY send an informational message to the other party, for example to change a content transport method or content description format parameter, inform the other party that a session initiation request is queued, that a device is ringing, or that a scheduled event has occurred or will occur. An information 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 MUST further contain a payload child element (speciific to the session, content description format, or content transport method) that specifies the information being communicated. If either party receives an empty "session-info" message for an active session, it MUST send an empty IQ result; this way, an empty "session-info" message may be used as a "ping" to determine session vitality. (A future version of this specification may define payloads related to the "session-info" action.)

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

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

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

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

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

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

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

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

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