moparisthebest
/
xeps
mirror of https://github.com/moparisthebest/xeps
1
0
Fork 0
Code Issues Releases Wiki Activity

XEP-0313 v0.4 - See Revision

This commit is contained in:
Matthew A. Miller 2015-09-21 09:42:28 -06:00
parent 611eb46c65
commit f8890be4ad
1 changed files with 36 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
xep-0313.xml
View File

@ -29,10 +29,12 @@
&ksmith;
<revision>
<version>0.4</version>
<date>2015-01-23</date>
<date>2015-09-21</date>
<initials>ks/mw</initials>
<remark><p>Switch the sentinel message back to the iq result.
Various small fixes to the document.</p></remark>
<remark>
<p>Switch the sentinel message back to the iq result.</p>
<p>Various small fixes to the document.</p>
</remark>
</revision>
<revision>
<version>0.3</version>
@ -157,12 +159,12 @@
allows clients to accurately page through messages.</p>
<example caption='A user queries their archive for messages'><![CDATA[
<iq type='set' id='juliet1'>
<query xmlns='urn:xmpp:mam:0' queryid='f27' />
<query xmlns='urn:xmpp:mam:1' queryid='f27' />
</iq>]]></example>
<example caption='Their server sends the matching messages'><![CDATA[
<message id='aeb213' to='juliet@capulet.lit/chamber'>
<result xmlns='urn:xmpp:mam:0' queryid='f27' id='28482-98726-73623'>
<result xmlns='urn:xmpp:mam:1' queryid='f27' id='28482-98726-73623'>
<forwarded xmlns='urn:xmpp:forward:0'>
<delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:08:25Z'/>
<message from="witch@shakespeare.lit" to="macbeth@shakespeare.lit">
@ -178,13 +180,13 @@
<p>When querying a pubsub node's archive, the 'node' attribute is added to the &lt;query&gt; element.</p>
<example caption="A user queries a pubsub node's archive for messages"><![CDATA[
<iq to='pubsub.shakespeare.lit' type='set' id='juliet1'>
<query xmlns='urn:xmpp:mam:0' queryid='f28' node='fdp/submitted/capulet.lit/sonnets'/>
<query xmlns='urn:xmpp:mam:1' queryid='f28' node='fdp/submitted/capulet.lit/sonnets'/>
</iq>
]]></example>
<section2 topic='Filtering results' anchor='filter'>
<p>By default all messages match a query, and filters are used to request a subset of the archived
messages. Filters are specified in a &xep0004; data form included with the query. The hidden FORM_TYPE field
MUST be set to this protocol's namespace, 'urn:xmpp:mam:0'. Three further fields are defined by this
MUST be set to this protocol's namespace, 'urn:xmpp:mam:1'. Three further fields are defined by this
XEP and MUST be supported by servers, though all of them are optional for the client. These fields are:
<ul>
<li>start</li>
@ -203,10 +205,10 @@
regardless of the to/from addresses on each message.</p>
<example caption='Querying for all messages to/from a particular JID'><![CDATA[
<iq type='set' id='juliet1'>
<query xmlns='urn:xmpp:mam:0'>
<query xmlns='urn:xmpp:mam:1'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mam:0</value>
<value>urn:xmpp:mam:1</value>
</field>
<field var='with'>
<value>juliet@capulet.lit</value>
@ -235,10 +237,10 @@
date/time of the most recent message stored in the archive.</p>
<example caption='Querying the archive for all messages in a certain timespan'><![CDATA[
<iq type='set' id='juliet1'>
<query xmlns='urn:xmpp:mam:0'>
<query xmlns='urn:xmpp:mam:1'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mam:0</value>
<value>urn:xmpp:mam:1</value>
</field>
<field var='start'>
<value>2010-06-07T00:00:00Z</value>
@ -252,10 +254,10 @@
]]></example>
<example caption='Querying the archive for all messages after a certain time'><![CDATA[
<iq type='set' id='juliet1'>
<query xmlns='urn:xmpp:mam:0'>
<query xmlns='urn:xmpp:mam:1'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mam:0</value>
<value>urn:xmpp:mam:1</value>
</field>
<field var='start'>
<value>2010-08-07T00:00:00Z</value>
@ -273,10 +275,10 @@
stanzas stored in the archive.</p>
<example caption='A query using Result Set Management'><![CDATA[
<iq type='set' id='q29302'>
<query xmlns='urn:xmpp:mam:0'>
<query xmlns='urn:xmpp:mam:1'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mam:0</value>
<value>urn:xmpp:mam:1</value>
</field>
<field var='start'>
<value>2010-08-07T00:00:00Z</value>
@ -294,7 +296,7 @@
<example caption='Server responds to client with limited results using RSM'><![CDATA[
<!-- result messages -->
<iq type='result' id='q29302'>
<fin xmlns='urn:xmpp:mam:0'>
<fin xmlns='urn:xmpp:mam:1'>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='0'>28482-98726-73623</first>
<last>09af3-cc343-b409f</last>
@ -317,9 +319,9 @@
from the previous query.</p>
<example caption='A page query using Result Set Management'><![CDATA[
<iq type='set' id='q29303'>
<query xmlns='urn:xmpp:mam:0'>
<query xmlns='urn:xmpp:mam:1'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'><value>urn:xmpp:mam:0</value></field>>
<field var='FORM_TYPE' type='hidden'><value>urn:xmpp:mam:1</value></field>>
<field var='start'><value>2010-08-07T00:00:00Z</value></field>
</x>
<set xmlns='http://jabber.org/protocol/rsm'>
@ -334,7 +336,7 @@
<example caption='Server completes a result with the last page of messages'><![CDATA[
<!-- result messages -->
<iq type='result' id='u29303'>
<fin xmlns='urn:xmpp:mam:0' complete='true'>
<fin xmlns='urn:xmpp:mam:1' complete='true'>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='0'>23452-4534-1</first>
<last>390-2342-22</last>
@ -349,14 +351,14 @@
<p>In order for the client find out about additional fields the server might support, it can send an iq stanza of type='get' addressed to the archive like this:</p>
<example><![CDATA[
<iq type='get' id='form1'>
<query xmlns='urn:xmpp:mam:0'/>
<query xmlns='urn:xmpp:mam:1'/>
</iq>
<iq type='result' id='form1'>
<query xmlns='urn:xmpp:mam:0'>
<query xmlns='urn:xmpp:mam:1'>
<x xmlns='jabber:x:data' type='form'>
<field type='hidden' var='FORM_TYPE'>
<value>urn:xmpp:mam:0</value>
<value>urn:xmpp:mam:1</value>
</field>
<field type='jid-single' var='with'/>
<field type='text-single' var='start'/>
@ -370,10 +372,10 @@
<p>If it understands any of the additional fields, it can use them in subsequent queries.</p>
<example><![CDATA[
<iq type='set' id='query4'>
<query xmlns='urn:xmpp:mam:0'>
<query xmlns='urn:xmpp:mam:1'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>urn:xmpp:mam:0</value>
<value>urn:xmpp:mam:1</value>
</field>
<field type='text-single' var='urn:example:xmpp:free-text-search'>
<value>Where arth thou, my Juliet?</value>
@ -406,7 +408,7 @@
</p>
<example caption='Server returns two matching messages'><![CDATA[
<message id='aeb213' to='juliet@capulet.lit/chamber'>
<result xmlns='urn:xmpp:mam:0' queryid='f27' id='28482-98726-73623'>
<result xmlns='urn:xmpp:mam:1' queryid='f27' id='28482-98726-73623'>
<forwarded xmlns='urn:xmpp:forward:0'>
<delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:08:25Z'/>
<message xmlns='jabber:client'
@ -420,7 +422,7 @@
</message>
<message id='aeb214' to='juliet@capulet.lit/chamber'>
<result xmlns='urn:xmpp:mam:0' queryid='f27' id='5d398-28273-f7382'>
<result xmlns='urn:xmpp:mam:1' queryid='f27' id='5d398-28273-f7382'>
<forwarded xmlns='urn:xmpp:forward:0'>
<delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:09:32Z'/>
<message xmlns='jabber:client'
@ -453,10 +455,10 @@
<p>A MUC archive MUST NOT include 'private message' results (those sent directly between occupants, not shared in the room) in the results</p>
</section3>
<section3 topic="Pubsub Archives">
<p>A PubSub service offering MAM SHOULD store each of the items published to each node. When responding to MAM requests it MUST construct the message stanza within the &lt;forwarded&gt; element in the same manner as the notifications sent to subscribers for the item, except that specifying the 'from' 'to' and 'id' attributes are OPTIONAL. Pubsub items must be returned one per message stanza (i.e. there MUST NOT be multiple &lt;item&gt; elemetns within the &lt;items&gt; element).</p>
<p>A PubSub service offering MAM SHOULD store each of the items published to each node. When responding to MAM requests it MUST construct the message stanza within the &lt;forwarded&gt; element in the same manner as the notifications sent to subscribers for the item, except that specifying the 'from' 'to' and 'id' attributes are OPTIONAL. Pubsub items must be returned one per message stanza (i.e. there MUST NOT be multiple &lt;item&gt; elements within the &lt;items&gt; element).</p>
<example caption='Server returns a pubsub messages'><![CDATA[
<message id='iasd208' to='juliet@capulet.lit/chamber'>
<result xmlns='urn:xmpp:mam:0' queryid='g28' id='28482-20987-73623'>
<result xmlns='urn:xmpp:mam:1' queryid='g28' id='28482-20987-73623'>
<forwarded xmlns='urn:xmpp:forward:0'>
<delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:08:25Z'/>
<message xmlns="jabber:client">
@ -507,7 +509,7 @@
</ul>
<example caption='Retrieving archiving preferences'><![CDATA[
<iq type='get' id='juliet2'>
<prefs xmlns='urn:xmpp:mam:0'/>
<prefs xmlns='urn:xmpp:mam:1'/>
</iq>
]]></example>
@ -517,7 +519,7 @@
<example caption='Server responds with current preferences'><![CDATA[
<iq type='result' id='juliet2'>
<prefs xmlns='urn:xmpp:mam:0' default='roster'>
<prefs xmlns='urn:xmpp:mam:1' default='roster'>
<always/>
<never/>
</prefs>
@ -539,7 +541,7 @@
<example caption='Updating archiving preferences'><![CDATA[
<iq type='set' id='juliet3'>
<prefs xmlns='urn:xmpp:mam:0' default='roster'>
<prefs xmlns='urn:xmpp:mam:1' default='roster'>
<always>
<jid>romeo@montague.lit</jid>
</always>
@ -553,7 +555,7 @@
MAY be different to the preferences sent by the client):</p>
<example caption='Server responds with updated preferences'><![CDATA[
<iq type='result' id='juliet3'>
<prefs xmlns='urn:xmpp:mam:0' default='roster'>
<prefs xmlns='urn:xmpp:mam:1' default='roster'>
<always>
<jid>romeo@montague.lit</jid>
</always>
@ -645,7 +647,7 @@
<section1 topic='Determining support' anchor='support'>
<p>If a server or other entity hosts archives and supports MAM queries, it MUST advertise
the 'urn:xmpp:mam:0' feature in response to &xep0030; requests made to archiving JIDs
the 'urn:xmpp:mam:1' feature in response to &xep0030; requests made to archiving JIDs
(i.e. JIDs hosting an archive, such as users' bare JIDs):
</p>
<example caption='Client queries for server features'><![CDATA[
@ -658,7 +660,7 @@
<iq type='result' id='disco1' from='juliet@capulet.lit' to='juliet@capulet.lit/balcony'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='urn:xmpp:mam:0'/>
<feature var='urn:xmpp:mam:1'/>
...
</query>
</iq>