Clarified error flows and handling of multiple IBB sessions within the bytestream.
&xep0166; defines a framework for negotiating and managing data sessions over XMPP. In order to provide a flexible framework, the base Jingle specification defines neither data transport methods nor application formats, leaving that up to separate specifications. The current document defines a transport method for establishing and managing data exchanges between XMPP entities using the existing In-Band Bytestreams (IBB) protocol specified in &xep0047;. This "jingle-ibb" method results in a streaming transport method suitable for use in Jingle application types where packet loss cannot be tolerated (e.g., file transfer); however, because the "jingle-ibb" transport method sends data over the XMPP channel itself (albeit not the Jingle signalling channel), it is intended as a transport of last resort when other streaming transports cannot be negotiated.
-The approach taken in this specification is to use the existing IBB mechanisms described in XEP-0047 for transporting the data, and to define Jingle-specific methods only to start and end the in-band bytestream.
+&xep0166; defines a framework for negotiating and managing data sessions over XMPP. In order to provide a flexible framework, the base Jingle specification defines neither data transport methods nor application formats, leaving that up to separate specifications. The current document defines a transport method for establishing and managing data exchanges between XMPP entities using the existing In-Band Bytestreams (IBB) protocol specified in &xep0047;. This "jingle-ibb" method results in a streaming transport method suitable for use in Jingle application types where packet loss cannot be tolerated (e.g., file transfer); however, because the "jingle-ibb" transport method sends data over the XMPP channel itself (albeit not the Jingle signalling channel), it is intended as a transport of last resort when other streaming transports (e.g., &xep0260;) cannot be negotiated.
+The approach taken in this specification is to use the existing IBB mechanisms described in XEP-0047 for transporting the data, and to define Jingle-specific methods only to start and end the in-band bytestream.
+ The basic flow is as follows.
+ |
| |
- ]]>
- This flow is illustrated in the following examples (to prevent confusion these use a "stub" description instead of a real application type).
- First the initiator sends a Jingle session-initiate request.
-
+ This flow is illustrated in the following sections (to prevent confusion these use a "stub" description instead of a real application type).
+ + +First the initiator sends a Jingle session-initiate request.
+The responder immediately acknowledges receipt (but does not yet accept the session).
-Note: The default value of the 'stanza' attribute is "iq", signifying use of &IQ; stanzas for data exchange; a value of "message" signifies that &MESSAGE; stanzas are to be used for data exchange. See XEP-0047 for further discussion regarding use of these stanza types for data exchange.
+The responder immediately acknowledges receipt (but does not yet accept the session).
+If the offer is acceptable, the responder returns a Jingle session-accept. If the responder wishes to use a smaller block-size, the responder can specify that in the session-accept by returning a different value for the 'block-size' attribute.
-If the offer is acceptable, the responder returns a Jingle session-accept. If the responder wishes to use a smaller block-size, the responder can specify that in the session-accept by returning a different value for the 'block-size' attribute.
+The initiator then acknowledges the session-accept.
-The initiator then acknowledges the session-accept.
+In essence, the foregoing Jingle negotiation replaces the <open/> element from XEP-0047. However, to provide consistent layering of Jingle on top of IBB (thus enabling separation of existing IBB code from new Jingle code), the initiator now MUST also send the <open/> element, with the same 'block-size' and 'sid' values as for the Jingle <transport/> element. This adds a roundtrip to the negotiation and could be considered a "no-op", but the extra roundtrip is inconsequential given that the parties are exchanging base64-encoded data in-band.
-In essence, the foregoing Jingle negotiation replaces the <open/> element from XEP-0047. However, to provide consistent layering of Jingle on top of IBB (thus enabling separation of existing IBB code from new Jingle code), the initiator now MUST also send the <open/> element, with the same 'block-size' and 'sid' values as for the Jingle <transport/> element it negotiated with the recipient (i.e., if the recipient sent a modified <transport/> element element containing a different block size, the initiator MUST use the negotiated values). This adds a roundtrip to the negotiation and could be considered a "no-op", but the extra roundtrip is inconsequential given that the parties will be exchanging base64-encoded data in-band.
+The responder returns an IQ-result to the initiator.
+If no error occurs, the responder returns an IQ-result to the initiator.
Now the initiator can begin sending IBB packets using an IQ-set for each chunk as described in XEP-0047, where the responder will acknowledge each IQ-set in accordance with &rfc3920;.
-Now the initiator can begin sending IBB packets using an IQ-set for each chunk as described in XEP-0047, where the responder will acknowledge each IQ-set in accordance with &rfc3920;.
+Once the parties have finished using the bytestream (e.g., because a complete file has been sent), either party can send a Jingle session-terminate action.
-As IBB is defined in XEP-0047, there is one session per bytestream (which can be used in both directions). However, because Jingle-IBB provides a management layer on top of IBB, it can be used to run multiple IBB sessions over a single bytestream. This can be done by sending a transport-info message that authorizes an additional session, as shown in the following example (although this example shows the initiator adding a session, the responder could just as well do so).
+Here the Jingle Session ID is the same ("a73sjjvkla37jfea") but the new IBB Session ID ("bt8a71h6") is different from the old IBB Session ID that is already in use ("ch3d9s71").
+If a party wishes to close one session within a bytestream, it sends an IBB <close/> element as defined in XEP-0047 specifying the appropriate IBB SessionID.
+The receiving party then acknowledges that the IBB session has been closed by returning an IQ-result.
+If a party wishes to close the bytestream itself (e.g., because the parties have finished using all sessions associated with the bytestream), it sends a Jingle session-terminate action as defined in XEP-0166.
+The other party then acknowledges the session-terminate and the Jingle session is finished.
-The other party then acknowledges the session-terminate and the Jingle session is finished.
+As IBB is defined in XEP-0047, there is one session per bytestream (which can be used in both directions). To extend this idea, it might be useful to run multiple sessions over a single bytestream. This can be done by sending a transport-info message that authorizes an additional session, as shown in the following example.
-Here the Jingle Session ID is the same ("a73sjjvkla37jfea") but the new IBB Session ID ("bt8a71h6") is different from the old IBB Session ID that is already in use ("ch3d9s71").
-To close one session within a bytestream, the initiator sends an IBB <close/> element as specified in XEP-0047.
-To close the bytestream itself, the initiator terminates the Jingle session as specified in XEP-0166.
+ ]]> +The same processing rules and usage guidelines defined in XEP-0047 apply to the Jingle IBB Transport Method.
+The same processing rules and usage guidelines defined in XEP-0047 apply to the Jingle IBB Transport Method.