Modified 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.
The other party MUST then acknowledge termination of the session.
-This section defines the high-level flow of a Jingle session. More detailed descriptions are provided in the specifications for Jingle application formats and transport methods.
In order to initiate a Jingle session, the initiator must determine which of the responder's XMPP resources is best for the desired application format. There are several possible scenarios:
-If the intended responder shares presence with the initiator (see &xmppim;) and has only one available resource, the initiator SHOULD attempt to negotiate a Jingle session with that resource unless the initiator knows via &xep0030; or &xep0115; that the resource does not support Jingle and the desired application format.
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 application format, the initiator SHOULD initiate the Jingle session with that resource.
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 application format, the initiator SHOULD use &xep0168; in order to determine which is the best resource with which to initiate the desired Jingle session.
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. The stanza session negotiation SHOULD result in temporary sharing of presence between the parties via the "presence" field as described in XEP-0155.
In order to initiate a Jingle session, the initiator must 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 (and associated specifications) 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 'http://www.xmpp.org/extensions/xep-0166.html#ns' namespace &NSNOTE;, 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. If either party wishes to propose the use of multiple transport methods for the same application format, it must send multiple &CONTENT; elements.
Note: The syntax and semantics of the &DESCRIPTION; and &TRANSPORT; elements are out of scope for this specification, 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.
-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 responder (i.e., the initiator MUST consider the session to be PENDING even before receiving acknowledgement). Given in-order delivery, the responder should receive such "transport-info" messages after receiving the "session-initiate" message (if not, it is appropriate for the responder to return <unknown-session/> errors since according to its state machine the session does not exist).
Unless an error occurs, the responder MUST acknowledge receipt of the initiation request.
-If the responder acknowledges receipt of the initation request, both parties must consider the session to be in the PENDING state.
-There are several reasons why the responder might return an error instead of acknowledging receipt of the initiation request:
-If the initiator is unknown to the responder (e.g., via presence subscription or stanza session negotiation) and the responder has a policy of not communicating via Jingle with unknown entities, it SHOULD return a &unavailable; error.
-Unless one of the following errors occurs, the responder SHOULD acknowledge receipt of the initiation request.
+However, after acknowledging the session initiation request, the responder may 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 MUST immediately acknowledge the session initiation request but then terminate the session with an appropriate reasoncode as described in the Termination section of this document.
+If the responder acknowledges receipt of the initation request, both parties must consider the session to be in the PENDING state.
+ +There are several reasons why the responder might immediately return an error instead of acknowledging receipt of the initiation request:
+If the initiator is unknown to the responder (e.g., via presence subscription or stanza session negotiation) and the responder has a policy of not communicating via Jingle with unknown entities, it SHOULD return a &unavailable; error.
+If the responder does not support Jingle, it MUST return a &unavailable; error.
-If the responder does not support Jingle, it MUST return a &unavailable; error.
+If the responder wishes to redirect the request to another address, it SHOULD return a &redirect; error.
-If the responder wishes to redirect the request to another address, it SHOULD return a &redirect; error.
+If the responder is busy, it SHOULD return a &recipient; error along with a Jingle-specific error condition of <busy/>.
-If the responder does not have sufficient resources to participate in a session, it SHOULD return a &constraint; error.
+If the responder does not support any of the specified application formats, it MUST return a &feature; error with a Jingle-specific error condition of <unsupported-content/>.
-If the responder does not support any of the specified transport methods, it MUST return a &feature; error with a Jingle-specific error condition of <unsupported-transports/>.
-If the initiation request was malformed, the responder MUST return a &badrequest; error.
-If the initiation request was malformed, the responder MUST return a &badrequest; error.
+In order to formally decline the session initiation request, the responder 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 application formats and transport methods. There are many potential parameter combinations, as defined in the relevant specifications for various application formats and transport methods.
@@ -625,7 +606,66 @@ PENDING o---------------------+ |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 responder or the initiator MUST send a "terminate" action to the other party.
-The other party MUST then acknowledge termination of the session:
+The party that terminates the session SHOULD include a 'reasoncode' attribute that specifies why the session is being terminated. Examples follow.
+One reason for terminating the session is that the terminating party is busy; in this case, the recommended reasoncode is "busy".
+Another reason for terminating the session is that the terminating party wishes to formally decline the session; in this case, the recommended reasoncode is "decline".
+Another reason for terminating the session is that the terminating party does not support any of the offered application formats; in this case, the recommended reasoncode is "unsupported-applications".
+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 reasoncode is "unsupported-transports".
+Upon receiving an action of "session-terminate", 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.
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 considered a session-ending event. However, in this case there is nothing for the party to acknowledge.
The following submission registers reasoncodes currently in use. Refer to the registry itself for a complete and current list of reasoncodes.
+ busy
+ the party is busy
+ XEP-0166
+
+
+
+ decline
+ the party wishes to formally decline the session
+ XEP-0166
+
+
connectivity-error
the action is related to connectivity problems
@@ -893,6 +940,18 @@ PENDING o---------------------+ |
the action is generated during the normal course of state management
XEP-0166
+
+
+ unsupported-applications
+ the party supports none of the offered application formats
+ XEP-0166
+
+
+
+ unsupported-transports
+ the party supports none of the offered transport methods
+ XEP-0166
+
]]>