Clarified session lifetime; defined reason attribute and associated registry; further specified conformance requirements.
Various content description formats (audio, video, etc.) and, where possible, mapping those types to the Session Description Protocol (SDP; see &rfc4566;); examples include &xep0167; and &xep0180;.
Various content transport methods; examples include &xep0176; and &xep0177;.
Procedures for mapping the Jingle signalling protocol to existing signalling standards such as the IETF's Session Initiation Protocol (SIP; see &rfc3261;) and the ITU's H.323 protocol (see &h323;); these documents are not yet written
Procedures for mapping the Jingle signalling protocol to existing signalling standards such as the IETF's Session Initiation Protocol (SIP; see &rfc3261;) and the ITU's H.323 protocol (see &h323;); these documents are forthcoming.
In order to initiate a Jingle session, the initiating entity must determine which of the receiver'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 &xep0030; or the presence-based profile of service discovery specified in &xep0115;.
+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. If a contact has only one XMPP resource, this task MUST 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.
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 &xep0168; 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 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.
+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: 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:
@@ -380,15 +389,15 @@ PENDING o---------------------+ |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:
If the initiating entity 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 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).
+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 initiating entity:
+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 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 receiver's definitive acceptance:
-The initiator then acknowledges the receiver's definitive acceptance:
+Now the initiating entity and receiver can begin sending content over the negotiated connection.
+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 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 initiating entity MUST a send a "terminate" action to the other party:
+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 initiating entity 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. 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:
Naturally, in this case there is nothing for the initiating entity to acknowledge.
+Naturally, in this case there is nothing for the initiator 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 an empty "session-info" message is received for an active session, the receiving entity 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 will define payloads related to the "session-info" action.)
+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.)
There is a one-to-one relationship between content types and sessions. This reduces the complexity of managing a given session, since it avoids the need to de-multiplex traffic for different content types sent over the same connection. However, it may be desirable to share different kinds of content at the same time (e.g., during a video chat one party may want to share a file); in order to do this, the parties must establish a separate session for each content type. Management of multiple sessions is a client implementation matter and is not discussed in this specification.
+A document that specifies a Jingle application type (e.g., audio via RTP) MUST define:
+A document that specifies a Jingle transport method (e.g., Raw UDP) MUST define:
+
- the name of the content description format (e.g., "audio")
+ the name of the content description format
a natural-language summary of the content description format
+ whether the content should be sent over a "reliable" or "lossy" transport
the document in which this content description format is specified
]]>
@@ -661,12 +691,54 @@ PENDING o---------------------+ |
®PROCESS;
- the name of the content transport method (e.g., "raw-udp")
+ the name of the content transport method
a natural-language summary of the content transport method
+ whether the transport method is "reliable" or "lossy"
the document in which this content transport method is specified
]]>
+ The XMPP Registrar shall maintain a registry of reasons for Jingle actions.
+ ®PROCESS; +
+ the value of the 'reasoncode' attribute
+ a natural-language summary of the reason code
+ the document in which this reason code is specified
+
+ ]]>
+ The following submission registers reasoncodes in use as of April 2007. Refer to the registry itself for a complete and current list of reasoncodes.
+
+ connectivity-error
+ the action (e.g., session-terminate) is related to connectivity problems
+ XEP-0166
+
+
+
+ general-error
+ the action (e.g., session-terminate) is related to a non-specific application error
+ XEP-0166
+
+
+
+ media-error
+ the action (e.g., session-terminate) is related to media processing problems
+ XEP-0166
+
+
+
+ no-error
+ the action is generated during the normal course of state management
+ XEP-0166
+
+ ]]>
+ The authors would like to thank Rohan Mahy for his valuable input on early versions of this document. Dafydd Harries, Antti Ijäs, Lauri Kaila, Jussi Laako, Anthony Minessale, Matt O'Gorman, Rob Taylor, Saku Vainio, Brian West, and others have also provided helpful input. Thanks also to those who have commented on the &SSIG; and (earlier) Jingle
The authors would like to thank Rohan Mahy for his valuable input on early versions of this document. Thiago Camargo, Dafydd Harries, Antti Ijäs, Lauri Kaila, Justin Karneges, Jussi Laako, Anthony Minessale, Matt O'Gorman, Rob Taylor, Matt Tucker, Saku Vainio, Brian West, and others have also provided helpful input. Thanks also to those who have commented on the &SSIG; and (earlier) Jingle