From 994bc891a5a31f808f70523c386be7570d31ab02 Mon Sep 17 00:00:00 2001 From: Peter Saint-Andre Date: Thu, 17 Jul 2008 02:47:00 +0000 Subject: [PATCH] 1.0 DRAFT git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2088 4b5297f7-1745-476d-ba37-a9c6900126ab --- xep-0136.xml | 156 +++++++++++++++++++++++++++++---------------------- 1 file changed, 88 insertions(+), 68 deletions(-) diff --git a/xep-0136.xml b/xep-0136.xml index 2ab415b0..ff2b7dd1 100644 --- a/xep-0136.xml +++ b/xep-0136.xml @@ -10,7 +10,7 @@ This document defines mechanisms and preferences for the archiving and retrieval of XMPP messages. &LEGALNOTICE; 0136 - Proposed + Draft Standards Track Standards @@ -22,7 +22,10 @@ - NOT_YET_ASSIGNED + archive + + http://www.xmpp.org/schemas/archive.xsd + &ianpaterson; Jon @@ -32,6 +35,12 @@ &stpeter; &infiniti; + + 1.0 + 2008-07-16 + psa +

Per a vote of the XMPP Council, advanced status to Draft; concurrently, the XMPP Registrar issued the urn:xmpp:archive namespace.

 + 0.18 2008-05-19 @@ -177,7 +186,7 @@

An example follows.

- + @@ -274,16 +283,16 @@ -

In order to determine its user's current Save Mode(s) and OTR Mode(s), a client sends to its server an IQ-get containing an empty <pref/> element qualified by the 'urn:xmpp:tmp:archive' namespace &NSNOTE;.

+

In order to determine its user's current Save Mode(s) and OTR Mode(s), a client sends to its server an IQ-get containing an empty <pref/> element qualified by the 'urn:xmpp:archive' namespace.

- + ]]>

The server responds with the default Save Mode and OTR Mode (a single <default/> element) and any specific Save Modes and OTR Modes for individual contacts (zero or more <item/> elements).

- + @@ -306,7 +315,7 @@

If the user has never set the default Modes, the 'save' and 'otr' attributes SHOULD specify the server's default settings, and the 'unset' attribute SHOULD be set to 'true'. Note: The 'unset' attribute defaults to 'false'.

- + @@ -321,7 +330,7 @@

A client may set the default Modes:

- + @@ -333,13 +342,13 @@

The server then MUST inform all of the user's connected resources that have previously requested the user's archiving preferences:

- + - + @@ -351,7 +360,7 @@

A client may use a similar protocol to set the Modes for a particular contact or domain of contacts (bare JID, full JID or domain). Note: It is STRONGLY RECOMMENDED for the value of the 'jid' attribute to be a bare JID &LOCALBARE; rather than a full JID &LOCALFULL;.

- + @@ -361,13 +370,13 @@ ]]> - + - + @@ -376,7 +385,7 @@

In order to remove all preferences for a contact, the client shall send an <itemremove/> element to the server.

- + @@ -389,7 +398,7 @@

The client can set one or more method preferences by sending an IQ-set containing a <pref/> element that in turn contains one or more <method/> elements.

- + @@ -402,7 +411,7 @@

If the client includes less than three <method/> elements, the server MUST NOT modify the unspecified methods and MUST leave them as currently stored on the server. However, when the server pushes the method preferences it MUST include all of the preferences, not only those that were set by the client.

- + @@ -410,7 +419,7 @@ - + @@ -578,7 +587,7 @@

A collection of messages and notes is uploaded to the server encapsulated in a <save/> element.

- + If the collection does not exist then the server MUST create a new collection and inform the client that the collection version number is zero.

- + If the collection already exists then the server MUST append the messages to the existing collection (which MAY involve adding messages that appear to be duplicates, i.e., messages that have identical <from/> elements, <to/> elements, and dateTimes).

- + If the client specifies a new value for the 'subject' attribute of any existing collection then the server MUST update the existing value and increment the collection version. Note: The client cannot specify new values for the 'with' or 'start' attributes. The only way to change these values is to delete the collection (see Removing a Collection) and then create a new one.

- + @@ -640,7 +649,7 @@ ]]> - + The client MAY specify an absolute time for any message by providing a 'utc' attribute (which MUST be UTC and adhere to the DateTime format specified in XEP-0082) instead of a 'secs' attribute. The absolute time MAY be earlier than the start time of the collection:

- + @@ -670,7 +679,7 @@

A client MAY archive messages that it receives from &xep0045; rooms. The 'with' attribute MUST be the bare JID of the room. The client MUST include a 'name' attribute for each <from/> element to specify the room nickname of the message sender and MAY include a 'jid' attribute to specify the full or bare JID of the sender (if available).

- + She will invite him to some supper. @@ -685,7 +694,7 @@

Collections MAY be linked together by including a <previous/> and/or <next/> element. Each such element MUST include both a 'with' and a 'start' element to identify the other collection to which the collection is linked. For example, the <previous/> and <next/> elements in the two examples below are being used to link a groupchat between Romeo, Benvolio and Mercutio to a private chat that Romeo was having with Benvolio before they invited Mercutio to join them. Note: Collections MAY be linked in only one direction, they are not required to be double-linked in the way the examples below are.

- + @@ -697,7 +706,7 @@ ]]> - + @@ -713,7 +722,7 @@

<previous/> and <next/> elements MAY be removed from a collection simply by uploading a <previous/> and/or <next/> element without any 'with' or 'start' attributes. Note: The server SHOULD NOT return an error if it finds that a link to be deleted does not exist.

- + @@ -729,7 +738,7 @@

Any data forms for associating attributes are application-specific and are to be defined outside this specification. The following example shows attributes generated by a fictional application.

- + O, I am fortune's fool! @@ -771,7 +780,7 @@

The client can enable auto-archiving by setting the 'save' attribute to "true" or "1".

- + ]]>

If the server does not support the saving of full message stanza or stream content and the user has specified the 'message' or 'stream' Save Mode in one of its Archiving Preferences, the server MUST return a &feature; error.

@@ -785,7 +794,7 @@

The client can disable auto-archiving by setting the 'save' attribute to "false" or "0".

- + ]]>

If service policies require that every message is logged automatically, the server MUST return a ¬allowed; error.

@@ -813,7 +822,7 @@

The client SHOULD use Result Set Management to limit the number of collections returned by the server in a single stanza, taking care not to request a page of collections that is so big it might exceed rate limiting restrictions.

- 30 @@ -823,7 +832,7 @@ ]]> - @@ -835,7 +844,7 @@ ]]> - 30 @@ -848,12 +857,12 @@

If no collections correspond to the request the server MUST return an empty <list/> element:

- + ]]> - 30 @@ -870,7 +879,7 @@

The client SHOULD use Result Set Management to limit the number of messages returned by the server in a single stanza, taking care not to request a page of messages that is so big it might exceed rate limiting restrictions.

- @@ -881,7 +890,7 @@ ]]> - If the specified collection does not exist then the server MUST return an ¬found; error:

- @@ -919,7 +928,7 @@

If the requested collection is empty the server MUST return an empty <chat/> element:

- - @@ -944,7 +953,7 @@

To request the removal of a single collection the client sends an empty <remove/> element. The 'with' and 'start' attributes MUST be included to uniquely identify the collection.

- @@ -953,7 +962,7 @@

In addition, the client MAY match an exact bare JID &BAREJID; by setting the boolean 'exactmatch' attribute to a value of "true" or "1" &BOOLEANNOTE; -- for details, refer to the Exact JID Matching section of this document.

- @@ -963,7 +972,7 @@

If the end date is in the future then all collections on or after the start date are removed.

- @@ -971,34 +980,34 @@

If the start date is before all the collections in the archive then all collections prior to the end date are removed.

- ]]> - + ]]>

If the value of the optional 'open' attribute is set to 'true' then only collections that are currently being recorded automatically by the server (see Automatic Archiving) are removed.

- ]]> - ]]>

If the specified collection (or collections) do not exist then the server MUST return an ¬found; error:

- @@ -1016,7 +1025,7 @@

When requesting the list of modified collections, the client MUST embed appropriate Result Set Management data in the <modified/> element. The <modified/> element MUST include a 'start' attribute that specifies a UTC datetime (see XEP-0082) that it has previously received from the server or that it has determined locally (e.g., when synchronizing for the first time the client SHOULD choose a suitable time for the first page request, such as 1970-01-01T00:00:00Z).

- @@ -1028,7 +1037,7 @@

The server MUST return the changed collections in the chronological order that they were changed (most recent last). If a collection has been modified, created, or removed after the time specified by the 'start' attribute, then the server MUST include it in the returned result set page of collections (unless the specified maximum page size would be exceeded). Each <changed/> or <removed/> collection element (for modified/created, or removed collections respectively) in the returned list MUST include the 'with' and 'start' attribues (and MAY include the 'exactmatch' attribute if that was specified in the request). The XML character data of the <last/> element is a unique, persistent identifier created by the server, which MUST be treated as opaque by the client.

- + @@ -1047,7 +1056,7 @@

Note: Along with its copy of the archive the client SHOULD save the most recent <last/> identifier that it received from the server. The next time it synchronizes with the server it SHOULD specify that identifier when requesting the first result set page by including it as the XML character data of the <after/> element in Result Set Management.

- @@ -1071,7 +1080,7 @@ ]]> -

For each feature defined herein, if the server supports that feature it MUST return a <feature/> element with the 'var' attribute set to 'urn:xmpp:tmp:archive:name' &NSNOTE;, where 'name' is 'auto' for the Automatic Archiving feature, 'manage' for the Archive Management feature, 'manual' for the Manual Archiving feature, and 'pref' for the Archiving Preferences feature.

+

For each feature defined herein, if the server supports that feature it MUST return a <feature/> element with the 'var' attribute set to 'urn:xmpp:archive:[name]', where '[name]' is 'auto' for the Automatic Archiving feature, 'manage' for the Archive Management feature, 'manual' for the Manual Archiving feature, and 'pref' for the Archiving Preferences feature.

... - - - - - + + + + + ... @@ -1108,12 +1117,15 @@ -

Although message archiving is not negotiated between a client and its server as part of stream negotiation, a server MAY advertise a stream feature of "urn:xmpp:tmp:archive" &NSNOTE; during stream setup (via the <feature/> element, which MUST NOT contain a <required/> child), and MUST do so if automatic archiving is on by default (if so, the <feature/> element MUST include a <default/> child).

+

Although message archiving is not negotiated between a client and its server as part of stream negotiation, a server MAY advertise a stream feature of "urn:xmpp:archive" during stream setup (via the <feature/> element, which MUST contain an empty <optional/> child), and MUST do so if automatic archiving is on by default (if so, the <feature/> element MUST include an empty <default/> child).

+ + + ]]> + + ]]> @@ -1137,15 +1149,15 @@ -

Until this specification advances to a status of Draft, its associated namespace shall be "urn:xmpp:tmp:archive"; upon advancement of this specification, the ®ISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;. The namespace "urn:xmpp:archive" is requested, and is thought to be unique per the XMPP Registrar's requirements.

+

The ®ISTRAR; includes "urn:xmpp:archive:data" in its registry of protocol namespaces (see &NAMESPACES;).

 -

The XMPP Registrar shall include the following features in its registry of service discovery features (see &DISCOFEATURES;), where the string "urn:xmpp:tmp:archive" shall be replaced with the URN issued by the XMPP Registrar:

+

The XMPP Registrar includes the following features in its registry of service discovery features (see &DISCOFEATURES;):

    -
  • urn:xmpp:tmp:archive:auto
    • -
  • urn:xmpp:tmp:archive:manage
    • -
  • urn:xmpp:tmp:archive:manual
    • -
  • urn:xmpp:tmp:archive:pref
    • +
  • urn:xmpp:archive:auto
    • +
  • urn:xmpp:archive:manage
    • +
  • urn:xmpp:archive:manual
    • +
  • urn:xmpp:archive:pref
 @@ -1156,10 +1168,17 @@ + + + The protocol documented by this schema is defined in + XEP-0136: http://www.xmpp.org/extensions/xep-0136.html + + + The allowable root elements for the namespace defined @@ -1272,6 +1291,7 @@ +