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:

1. content-accept (accept a content-add, content-modify, or content-remove; implicitly also serves as a description-accept and transport-accept)
2. content-add (add one or more new content types to the session; this MUST NOT be sent while the session is in the PENDING state)
3. content-decline (reject a content-add or content-modify)
4. content-modify (change an existing content type, mainly the directionality)
5. content-remove (remove one or more content types from the session)
6. session-accept (definitively accept a session request; implicitly also serves as a description-accept and transport-accept)
7. session-initiate (request a new Jingle session)
8. session-info (session-level information / messages)
9. session-redirect (redirect an initiate request to another address)
10. session-terminate (end an existing session)

The content type of a session is made up of two aspects:

1. The content description format specifies the "what" of the session (e.g., audio).
2. The content transport method defines "how" the data shall be exchanged (e.g., raw UDP).

The &CONTENT; element also specifies who will be sending content (the initiator, the recipient, or both).

In order to initiate a Jingle session, the initiating entity must determine which of the target entity's XMPP resources is best for the desired content description format. If a contact has only one XMPP resource, this task MUST be completed using &jep0030; or the presence-based profile of service discovery specified in &jep0115;.

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 JEP-0115 for details.

If a contact has more than one XMPP resource, it may be that only one of the resources supports Jingle and the desired content description format, in which case the user MUST initiate the Jingle signalling with that resource.

If a contact has more than one XMPP resource that supports Jingle and the desired content description format, it is RECOMMENDED for a client to use &jep0168; in order to determine which is the best resource with which to initiate the desired Jingle session.

Once the initiating entity has discovered which of the target entity's XMPP resources is ideal for the desired content description format, it sends a session initiation request to the target entity. This request is an IQ-set containing a &JINGLE; element qualified by the 'http://jabber.org/protocol/jingle' 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 or more &TRANSPORT; child elements that specify potential content transport methods.

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 '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 '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 'senders' attribute specifies which entities in the session will be generating content; the allowable values are "initiator", "recipient", or "both" (where "both" is the default).

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

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

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

• The initiating entity is unknown to the target entity (e.g., via presence subscription).
• The target entity does not support Jingle.
• The target entity does not support any of the specified content description formats.
• The target entity does not support any of the specified content transport methods.
• The initiation request was malformed.

The initiating entity is unknown to the target entity (e.g., via presence subscription) and the target entity has a policy of not communicating via Jingle with unknown entities, it MUST return a &unavailable; error.

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

If the target entity 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 target entity 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 target entity MUST return a &badrequest; error.

After acknowledging receipt of the initiation request, the target entity MAY redirect the session to another address (e.g., because the principal is not answering at the original resource). This is done by sending a Jingle redirect action to the initiating entity:

The recipient then acknowledges the redirection:

Both entities MUST now consider the original session to be in the ENDED state, and if the initiating entity wishes to initiate a session with the redirected address it MUST do so by sending a session initiation request to that address with a new session ID.

In order to decline the session initiation request, the target entity MUST acknowledge receipt of the session initiation request, then terminate the session as described in the Termination section of this document.

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 during while the session is in the PENDING state and is allowed only while the session is in the ACTIVE state (see below).

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

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

The initiating entity then acknowledges the target entity's definitive acceptance:

Now the initiating entity and target entity 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 target entity or the initiating entity MUST a send a "terminate" action to the other party:

The initiating entity MUST then acknowledge termination of the session:

Unfortunately, not all sessions end gracefully. The following events MUST be considered session-ending events, and any further Jingle communication for the negotiated content description format and content transport method MUST be completed through negotiation of a new session:

• Receipt of a 'session-redirect' or 'session-terminate' action from the other party.
• Receipt of &UNAVAILABLE; from the other party.

In particular, one party MUST consider the session to be in the ENDED state if it receives presence of type "unavailable" from the other party:

Naturally, in this case there is nothing for the initiating entity 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. (A future version of this specification will define payloads related to the "session-info" action.)

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.

The ®ISTRAR; shall include 'http://jabber.org/protocol/jingle' and 'http://jabber.org/protocol/jingle#errors' in its registry of protocol namespaces.

The Jabber Registrar shall maintain a registry of Jingle content description formats. All content description format registrations shall be defined in separate documents (not in this JEP). Content description formats defined within the JEP series MUST be registered with the Jabber Registrar, resulting in protocol URIs of the form "http://jabber.org/protocol/jingle/description/name" (where "name" is the registered name of the content description format).

The Jabber Registrar shall maintain a registry of Jingle content transport methods. All content transport method registrations shall be defined in separate documents (not in this JEP). Content transport methods defined within the JEP series MUST be registered with the Jabber Registrar, resulting in protocol URIs of the form "http://jabber.org/protocol/jingle/transport/name" (where "name" is the registered name of the content transport method).