7.1.16 Managing Discussion History

A user MAY want to manage the amount of discussion history provided on entering a room (perhaps because the user is on a low-bandwidth connection or is using a small-footprint client). This MUST be accomplished by including a <history/> child in the initial presence stanza sent when joining the room. There are four allowable attributes for this element:

Table 8: History Management Attributes
Attribute 	Datatype 	Meaning
maxchars 	int 	Limit the total number of characters in the history to "X" (where the character count is the characters of the complete XML stanzas, not only their XML character data).
maxstanzas 	int 	Limit the total number of messages in the history to "X".
seconds 	int 	Send only the messages received in the last "X" seconds.
since 	dateTime 	Send only the messages received since the datetime specified (which MUST conform to the DateTime profile specified in XMPP Date and Time Profiles [13]).

The service MUST send the smallest amount of traffic that meets any combination of the above criteria, taking into account service-level and room-level defaults. The service MUST send complete message stanzas only (i.e., it MUST not literally truncate the history at a certain number of characters, but MUST send the largest number of complete stanzas that results in a number of characters less than or equal to the &#039;maxchars&#039; value specified). If the client wishes to receive no history, it MUST set the &#039;maxchars&#039; attribute to a value of "0" (zero).

The following examples illustrate the use of this protocol.

Example 34. User Requests Limit on Number of Messages in History

<presence
    from=&#039;[email protected]/pda&#039;
    to=&#039;[email protected]/thirdwitch&#039;>
  <x xmlns=&#039;http://jabber.org/protocol/muc&#039;>
    <history maxstanzas=&#039;20&#039;/>
  </x>
</presence>
      

Example 35. User Requests History in Last 3 Minutes

<presence
    from=&#039;[email protected]/pda&#039;
    to=&#039;[email protected]/thirdwitch&#039;>
  <x xmlns=&#039;http://jabber.org/protocol/muc&#039;>
    <history seconds=&#039;180&#039;/>
  </x>
</presence>
      

Example 36. User Requests All History Since the Beginning of the Unix Era

<presence
    from=&#039;[email protected]/pda&#039;
    to=&#039;[email protected]/thirdwitch&#039;>
  <x xmlns=&#039;http://jabber.org/protocol/muc&#039;>
    <history since=&#039;1970-01-01T00:00:00Z&#039;/>
  </x>
</presence>
      

Obviously the service SHOULD NOT return all messages sent in the room since the beginning of the Unix era, and SHOULD appropriately limit the amount of history sent to the user based on service or room defaults.

Example 37. User Requests No History

<presence
    from=&#039;[email protected]/pda&#039;
    to=&#039;[email protected]/thirdwitch&#039;>
  <x xmlns=&#039;http://jabber.org/protocol/muc&#039;>
    <history maxchars=&#039;0&#039;/>
  </x>
</presence>

Add a code snippet to your website: www.paste.org