This JEP defines a storage protocol and common disk format for archiving of messages.
WARNING: Consideration of this JEP has been Deferred by the Jabber Software Foundation. Implementation of the protocol described herein is not recommended.
Status: Deferred
Type: Standards Track
Number: 0136
Version: 0.1
Last Updated: 2004-06-04
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, XMPP IM
Supersedes: None
Superseded By: None
Short Name: archive
Email: justin@affinix.com
JID: justin@andbit.net
This Jabber Enhancement Proposal is copyright 1999 - 2004 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.php>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at <http://www.opencontent.org/openpub/>).
The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocols defined in this JEP have been developed outside the Internet Standards Process and are to be understood as extensions to XMPP rather than as an evolution, development, or modification of XMPP itself.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
This specification defines a protocol for storing and retrieving messages on a server. Each storage item consists of a collection of messages, usually the message thread. Clients are able to add/update/remove items from the server. A disk format is also specified, so that IM clients can share message archive files, similar in the way that email clients share common formats like mbox and Maildir.
All messages are stored in a message collection. The client specifies whether or not a message is part of a new collection by using a 'cid' (collection ID). If the 'cid' is omitted (unspecified), then a new collection is to be started. If the 'cid' is present, then it indicates to the server that the message is to be appended to an existing collection. Messages are encapsulated in the <archive> element. The message MUST have a 'from' or a 'to' attribute that is not the same JID as the client, and MUST contain a <body> element (other elements MAY be stored). A 'name' attribute of <archive> MAY be provided, which specifies a friendly name for this message collection. If the specified collection already has a name, then it is simply replaced.
Example 1. Storing a message in a new collection
<iq type='set' id='a1' to='server'>
<archive xmlns='http://jabber.org/protocol/archive' name='Battle for today'>
<message xmlns='jabber:client' from='zz@boyzzbrigade.org/hideout'>
<body>It's laser time!</body>
</message>
</archive>
</iq>
The server will then set up a session for this message collection, and return a suitable 'cid' for the client to use in future requests.
Example 2. Successful server reply
<iq type='result' id='a1' to='client'>
<archive xmlns='http://jabber.org/protocol/archive'
cid='fasdingainbadnfknbdlfnkalfknbldnfnnlq'/>
</iq>
Subsequent requests MUST be 'from' or 'to' the same bare-JID as the first:
Example 3. Storing another message in this collection
<iq type='set' id='a2' to='server'>
<archive xmlns='http://jabber.org/protocol/archive'
cid='fasdingainbadnfknbdlfnkalfknbldnfnnlq'>
<message xmlns='jabber:client' from='zz@boyzzbrigade.org/hideout'>
<body>Put on the 3D shades.</body>
</message>
</archive>
</iq>
The reply from the server does not need to specify the cid in this case:
Example 4. Successful server reply
<iq type='result' id='a2' to='client'>
<archive xmlns='http://jabber.org/protocol/archive'/>
</iq>
It is also possible to simply rename the collection:
Example 5. Renaming this collection
<iq type='set' id='a3' to='server'>
<archive xmlns='http://jabber.org/protocol/archive'
cid='fasdingainbadnfknbdlfnkalfknbldnfnnlq' name='Battle in 3D!"/>
</iq>
Example 6. Successful server reply
<iq type='result' id='a3' to='client'>
<archive xmlns='http://jabber.org/protocol/archive'/>
</iq>
In all types of requests, it is possible that the server might not be able to service it. In that case, it MUST return a Not Acceptable error:
Example 7. Successful server reply
<iq type='error' id='a1' to='client'>
<error code='406' type='auth'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
When a client is finished recording messages for a given collection, it SHOULD send a <done> element. The server MAY assume a collection is finished based on a timeout or if the client is disconnected.
Example 8. Closing a collection
<iq type='set' id='a4' to='server'>
<done xmlns='http://jabber.org/protocol/archive'
cid='fasdingainbadnfknbdlfnkalfknbldnfnnlq'/>
</iq>
Retrieving messages consists of two steps: 1) Obtaining a list of collections, and 2) Downloading the collection.
To request a list of collection items, use the <archive> element. The 'start' and 'end' elements can be specified to indicate a date range for the items that the client is interested in. If only 'start' is provided, then all items after that date should be returned. If only 'end' is provided, then all items prior to that date should be returned. If neither attribute is provided, then all items are to be returned.
Example 9. Requesting items
<iq type='get' id='a1' to='server'>
<archive xmlns='http://jabber.org/protocol/archive' start='20040426T00:00:00'/>
</iq>
Example 10. Server reply
<iq type='result' id='a1' to='client'>
<archive xmlns='http://jabber.org/protocol/archive'>
<item
cid='asdfsdfjsdjfsjdkfjsdjfskdjfdsfjdskfjd'
jid='ceo@example.com'
name='Meeting from yesterday'
start='20020910T23:08:25'
end='20020910T23:09:25'/>
<item
cid='fasdingainbadnfknbdlfnkalfknbldnfnnlq'
jid='zz@boyzzbrigade.org'
name='Battle in 3D!'
start='20020912T23:08:25'
end='20020912T23:09:25'/>
<item
cid='hufgipqjrejbxzcnnsheqegoppgppadnbnndd'
jid='hotgirl@classmates.com'
name='Hey what is up? I have not seen you in a long time. How are ...'
start='20020913T23:08:25'
end='20020913T23:09:25'/>
</archive>
</iq>
Each item in the reply has a 'cid' (same as the one used during the storage process), the bare-JID with which the messages were exchanged, a 'name' (also indicated during the storage process, otherwise it is a preview generated from the collection text), and the start and end dates of the collection.
At this point, the client can now request a collection:
Example 11. Requesting a collection
<iq type='get' id='a2' to='server'>
<archive xmlns='http://jabber.org/protocol/archive'
cid='fasdingainbadnfknbdlfnkalfknbldnfnnlq'/>
</iq>
Example 12. Server reply
<iq type='result' id='a2' to='client'>
<archive xmlns='http://jabber.org/protocol/archive'>
<message xmlns='jabber:client' from='zz@boyzzbrigade.org/hideout'>
<body>It's laser time!</body>
</message>
<message xmlns='jabber:client' from='zz@boyzzbrigade.org/hideout'>
<body>Put on the 3D shades.</body>
</message>
</archive>
</iq>
The file format uses the same XML constructs as the protocol.
Example 13. Example file
<?xml version='1.0'?>
<archive xmlns='http://jabber.org/protocol/archive'>
<item
cid='fasdingainbadnfknbdlfnkalfknbldnfnnlq'
jid='zz@boyzzbrigade.org'
name='Battle in 3D!'
start='20020912T23:08:25'
end='20020912T23:09:25'/>
<message xmlns='jabber:client' from='zz@boyzzbrigade.org/hideout'>
<body>It's laser time!</body>
</message>
<message xmlns='jabber:client' from='zz@boyzzbrigade.org/hideout'>
<body>Put on the 3D shades.</body>
</message>
[...]
<message/>
</item>
<item/>
<item/>
<item/>
[...]
<item/>
</archive>
Any number of items may be stored in an archive file. For efficiency, it is recommended that implementations spread out the items across many files (such as through a log rotation facility).
No interaction with the Internet Assigned Numbers Authority (IANA) [1] is required as a result of this JEP.
The Jabber Registrar [2] shall register the 'http://jabber.org/protocol/archive' namespace as a result of this JEP.
1. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.
2. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.
END