Corrected value of 'h' so that zero means no stanzas have yet been handled; clarified distinction between a cleanly closed stream and an unfinished stream.
&xmppcore; defines the fundamental streaming XML technology used by XMPP (i.e., stream establishment and termination including authentication and encryption). However, the core XMPP specification does not provide tools for actively managing a "live" XML stream.
-The basic concept behind stream management is that the initiating entity (either a client or a server) and the receiving entity (a server) can exchange "commands" for active management of the stream. (Instead of using XMPP IQ, message, or presence stanzas, stream management uses a series of short XML elements at the root stream level.) In particular, it is expected that the following stream management features will improve network reliability and the end-user experience:
+The basic concept behind stream management is that the initiating entity (either a client or a server) and the receiving entity (a server) can exchange "commands" for active management of the stream. The following stream management features are of particular interest because they are expected to improve network reliability and the end-user experience:
Detailed descriptions of these features are provided in the remainder of this specification.
-Note: To check TCP connectivity for a given stream, it is RECOMMENDED to use &xep0199;, whitespace pings (see Section 5.7.3 of &rfc3920bis;), or TCP keepalives.
-Note: This specification applies at the level of an XML stream between a client and a server or between two servers. By constrast, &xep0079; and &xep0184; define acks that are sent end-to-end over multiple streams; these facilities are useful in special scenarios but are unnecessary for checking of a direct stream between two XMPP entities. (It is also expected that this protocol will revive interest in Advanced Message Processing (AMP), because single-hop acks are necessary for AMP delivery receipts to function properly.)
-Note: Examples prepended by "C:" are sent by a client and examples prepended by "S:" are sent by a server. Stream management can be used server-to-server but most of the examples in this specification show its use between a client and a server.
+Stream management implements these features using short XML elements at the root stream level. These elements are not "stanzas" in the XMPP sense (i.e., not &IQ;, &MESSAGE;, or &PRESENCE; stanzas as defined in &rfc3920;) and are not counted or acked in stream management, since they exist for the purpose of managing stanzas themselves.
+Stream management is used at the level of an XML stream. To check TCP connectivity underneath a given stream, it is RECOMMENDED to use &xep0199;, whitespace keepalives (see Section 5.7.3 of &rfc3920bis;), or TCP keepalives. By constrast with stream management, &xep0079; and &xep0184; define acks that are sent end-to-end over multiple streams; these facilities are useful in special scenarios but are unnecessary for checking of a direct stream between two XMPP entities.
+(Examples prepended by "C:" are sent by a client and examples prepended by "S:" are sent by a server. Stream management can be used server-to-server but most of the examples in this specification show its use between a client and a server.)
An <a/> element MUST possess an 'h' attribute.
An <r/> element SHOULD NOT possess any attributes.
Definition: Acknowledging a previously-received ack element indicates that the stanza(s) sent since then have been "handled" by the receiver. By "handled" we mean that the receiver has accepted responsibility for a stanza or stanzas (e.g., to process the stanza(s) directly, deliver the stanza(s) to a local entity such as another connected client on the same server, or route the stanza(s) to a remote entity at a different server); until a stanza has been affirmed as handled by the receiver, that stanza is the responsibility of the sender (e.g., to resend it or generate an error if it is never affirmed as handled by the receiver).
-Note: The value of 'h' starts at zero for the first stanza handled and is incremented with each subsequent stanza handled. In the unlikely case that the number of stanzas handled during a stream management session exceeds the number of digits that can be represented by the unsignedInt datatype as specified in &w3xmlschema2; (i.e., 232), the value of 'h' shall be reset from 232-1 back to zero (rather than being incremented to 232).
+Note: The value of 'h' starts at zero before any stanzas are handled, is incremented to one for the first stanza handled, and is incremented again with each subsequent stanza handled. In the unlikely case that the number of stanzas handled during a stream management session exceeds the number of digits that can be represented by the unsignedInt datatype as specified in &w3xmlschema2; (i.e., 232), the value of 'h' shall be reset from 232-1 back to zero (rather than being incremented to 232).
The following example shows a message sent by the client, a request for acknowledgement, and an ack of the stanza.
Stream management errors SHOULD be considered recoverable; however, misuse of stream management MAY result in termination of the stream.
A cleanly closed stream differs from an unfinished stream. If a client wishes to cleanly close its stream and end its session, it MUST send a </stream:stream> so that the server can send unavailable presence on the client's behalf.
+If the stream is not cleanly closed then the server SHOULD consider the stream to be unfinished (even if the client closes its TCP connection to the server) and SHOULD maintain the session on behalf of the client for a limited amount of time. The client can send whatever presence it wishes before leaving the stream in an unfinished state.
+The following scenarios illustrate several different uses of stream management. The examples are that of a client and a server, but stream management can also be used for server-to-server streams.
@@ -325,7 +336,7 @@ S:This is enough of an implementation to minimally satisfy the peer, and allows basic tracking of each outbound stanza. If the stream connection is broken, the application has a queue of unacknowledged stanzas that it can choose to handle appropriately (e.g., warn a human user or silently send after reconnecting).
The following examples illustrate basic acking (here the client automatically acks each stanza it has received from the server, without first being prompted via an <r/> element).
@@ -633,7 +644,7 @@ S:Thanks to Dave Cridland, Jack Erwin, Philipp Hancke, Curtis King, Tobias Markmann, Alexey Melnikov, Pedro Melo, Robin Redeker, and Mickaël Rémond for their feedback.
+Thanks to Dave Cridland, Jack Erwin, Philipp Hancke, Curtis King, Tobias Markmann, Alexey Melnikov, Pedro Melo, Robin Redeker, Mickaël Rémond, and Matthew Wild for their feedback.