mirror of https://github.com/moparisthebest/xeps
Merge branch 'xep-0313' into premerge
This commit is contained in:
Jonas Schäfer
commit
bbd3257491
65
xep-0313.xml
65
xep-0313.xml
|
|
@ -29,6 +29,17 @@
|
|||
</schemaloc>
|
||||
&mwild;
|
||||
&ksmith;
|
||||
<revision>
|
||||
<version>1.0.1</version>
|
||||
<date>2022-02-16</date>
|
||||
<initials>egp</initials>
|
||||
<remark>
|
||||
<ul>
|
||||
<li>Fix inconsistency in example namespaces.</li>
|
||||
<li>Fix indentation, especially in examples.</li>
|
||||
</ul>
|
||||
</remark>
|
||||
</revision>
|
||||
<revision>
|
||||
<version>1.0.0</version>
|
||||
<date>2021-11-02</date>
|
||||
|
|
@ -230,8 +241,10 @@
|
|||
</section1>
|
||||
|
||||
<section1 topic='Message archives' anchor='archives'>
|
||||
<p>An archive contains a collection of messages relevant to a particular XMPP address, e.g. a user, MUC, pubsub node, server. Note: while a service might have many "archives" as defined here (one per JID capable of being queried) this is a conceptual distinction,
|
||||
and a server is not bound to any particular implementation or arrangement of data stores.</p>
|
||||
<p>An archive contains a collection of messages relevant to a particular XMPP address, e.g. a user, MUC,
|
||||
pubsub node, server. Note: while a service might have many "archives" as defined here (one per JID
|
||||
capable of being queried) this is a conceptual distinction, and a server is not bound to any particular
|
||||
implementation or arrangement of data stores.</p>
|
||||
<p>Exactly which messages a server archives is up to implementation and deployment policy,
|
||||
but it is expected that all messages that hold meaningful content, rather than state changes such as Chat State Notifications, would be archived. Rules are specified later in this document.</p>
|
||||
<p>A stored message consists of at least the following pieces of information:</p>
|
||||
|
|
@ -379,7 +392,7 @@
|
|||
</x>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
<p>If (and only if) the supplied JID is a bare JID (i.e. no resource is present), then
|
||||
the server SHOULD return messages if their bare to/from address for a user archive, or from address otherwise, would match it. For example,
|
||||
if the client supplies a 'with' of "juliet@capulet.lit" a query to their own archive would also match messages to
|
||||
|
|
@ -414,7 +427,7 @@
|
|||
</x>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
<example caption='Querying the archive for all messages after a certain time'><![CDATA[
|
||||
<iq type='set' id='juliet1'>
|
||||
<query xmlns='urn:xmpp:mam:2'>
|
||||
|
|
@ -428,7 +441,7 @@
|
|||
</x>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
</section3>
|
||||
<section3 topic='Limiting results by id' anchor='query-limit-id'>
|
||||
<p>If the client has already seen some messages, it may choose to restrict its query to
|
||||
|
|
@ -451,7 +464,7 @@
|
|||
</x>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
|
||||
<example caption='Querying the archive for all messages between two known messages'><![CDATA[
|
||||
<iq type='set' id='juliet1'>
|
||||
|
|
@ -469,7 +482,7 @@
|
|||
</x>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
|
||||
<p>If the client already knows the UID of one or more messages it wants to fetch, it can use
|
||||
the 'ids' field:</p>
|
||||
|
|
@ -487,7 +500,7 @@
|
|||
</x>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
|
||||
<p>If any UID requested by the client in any of the 'before-id', 'after-id' or 'ids' form fields is not present in the archive, the server MUST return an item-not-found error in response to the query.</p>
|
||||
|
||||
|
|
@ -509,7 +522,7 @@
|
|||
</x>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
<p>If the server advertises that it includes groupchat messages in the archive, or it advertises that it doesn't, a client may request that they not be included by setting the 'include-groupchat' field to 'false'.</p>
|
||||
<example caption='Querying the archive and excluding groupchat messages from results'><![CDATA[
|
||||
<iq type='set' id='juliet1'>
|
||||
|
|
@ -525,7 +538,7 @@
|
|||
</x>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
<p>Note that where the client doesn't specify the 'include-groupchat' field, it is implementation-defined whether groupchat messages are included in the results (see <link url='#business_rules'>Business Rules</link>). Clients MUST NOT include this field where servers don't advertise support, as the server would reject such a form.</p>
|
||||
</section3>
|
||||
<section3 topic='Retrieving form fields' anchor='query-form'>
|
||||
|
|
@ -570,10 +583,10 @@
|
|||
<field type='hidden' var='FORM_TYPE'>
|
||||
<value>urn:xmpp:mam:2</value>
|
||||
</field>
|
||||
<field type='text-single' var='urn:example:xmpp:free-text-search'>
|
||||
<field type='text-single' var='{http://example.com/}free-text-search'>
|
||||
<value>Where arth thou, my Juliet?</value>
|
||||
</field>
|
||||
<field type='text-single' var='urn:example:xmpp:stanza-content'>
|
||||
<field type='text-single' var='{http://example.com/}stanza-content'>
|
||||
<value>{http://jabber.org/protocol/mood}mood/lonely</value>
|
||||
</field>
|
||||
</x>
|
||||
|
|
@ -629,7 +642,7 @@
|
|||
</forwarded>
|
||||
</result>
|
||||
</message>
|
||||
]]></example>
|
||||
]]></example>
|
||||
</section2>
|
||||
|
||||
<section2 topic='Paging through results' anchor='query-paging'>
|
||||
|
|
@ -656,7 +669,7 @@
|
|||
</set>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
<p>To conserve resources, a server MAY place a reasonable limit on how many stanzas may be
|
||||
pushed to a client in one request. Whether or not the client query included a <set/> element, the server MAY simply return
|
||||
its limited results, modifying the <set/> element it returns appropriately.</p>
|
||||
|
|
@ -671,7 +684,7 @@
|
|||
</set>
|
||||
</fin>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
</section3>
|
||||
<section3 topic='Requesting pages' anchor='query-paging-request'>
|
||||
<p>The <first> and <last> elements specify the UID of the first and last returned
|
||||
|
|
@ -697,7 +710,7 @@
|
|||
</set>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
<p>Note: There is no concept of an "open query", and servers MUST be prepared to receive arbitrary page requests at any time.</p>
|
||||
<p>RSM does not define the behaviour of including both <before> and <after> in the same request. To retrieve a range of items between two known ids, use before-id and after-id in the query form instead.</p>
|
||||
<p>If the UID contained within an <after> or <before> element is not present in the archive, the server MUST return an item-not-found error in response to the query.</p>
|
||||
|
|
@ -707,7 +720,7 @@
|
|||
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
||||
</error>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
<p>When the results returned by the server are complete (that is: when they have not been limited by the maximum size of the result page (either as specified or enforced by the server)), the server MUST include a 'complete' attribute on the <fin> element, with a value of 'true'; this informs the client that it doesn't need to perform further paging to retreive the requested data. If it is not the last page of the result set, the server MUST either omit the 'complete' attribute, or give it a value of 'false'.</p>
|
||||
<example caption='Server completes a result with the last page of messages'><![CDATA[
|
||||
<!-- result messages -->
|
||||
|
|
@ -720,7 +733,7 @@
|
|||
</set>
|
||||
</fin>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
<p>Sometimes (e.g. due to network or storage partitioning, or other transient errors) the server might return results to a client that are unstable (e.g. they might later change in sequence or content). In such a situation the server MUST stamp the <fin> element with a 'stable' attribute with a value of 'false'. If the server knows that the data it's serving are stable it MUST either stamp a 'stable' attribute with a value of 'true', or no such attribute. An example of when unstable might legitimately be returned is if the MAM service uses a clustered data store and a query covers a time period for which the data store has not yet converged; it the server could return best-guess results and tell the client that they may be unstable. A client SHOULD NOT cache unstable results long-term without later confirming (by reissuing appropriate queries) that they have become stable.</p>
|
||||
</section3>
|
||||
<section3 topic='Requesting the last page'>
|
||||
|
|
@ -738,7 +751,7 @@
|
|||
</set>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
<p>Within the returned page, all results are still in chronological order, that is, the first result you receive will be the oldest item in the page, and the last result you receive will be the last item in the archive.</p>
|
||||
</section3>
|
||||
<section3 topic='Flipped pages' anchor='query-paging-flip'>
|
||||
|
|
@ -760,7 +773,7 @@
|
|||
<flip-page/>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
<p>It is important to note that flipping a page does not affect what results are returned in response to the query. It only affects the
|
||||
order in which they are transmitted from the server to the client.</p>
|
||||
<p>A client that wishes to use flipped pages MUST ensure that the server advertises the 'urn:xmpp:mam:2#extended' feature.</p>
|
||||
|
|
@ -779,7 +792,7 @@
|
|||
<iq type='get' id='jui8921rr9'>
|
||||
<metadata xmlns='urn:xmpp:mam:2'/>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
|
||||
<example caption='Server returns archive metadata'><![CDATA[
|
||||
<iq type='result' id='jui8921rr9'>
|
||||
|
|
@ -788,7 +801,7 @@
|
|||
<end id='b21lZ2Eg' timestamp='2020-04-20T14:34:21Z' />
|
||||
</metadata>
|
||||
</iq>
|
||||
]]></example>
|
||||
]]></example>
|
||||
|
||||
<p>The server response includes a <metadata/> element containing information about the archive. This element MUST include <start/> and <end/>
|
||||
elements, which each have an 'id' and XEP-0082 formatted 'timestamp of the first and last messages in the archive respectively.</p>
|
||||
|
|
@ -851,7 +864,7 @@
|
|||
</forwarded>
|
||||
</result>
|
||||
</message>
|
||||
]]></example>
|
||||
]]></example>
|
||||
</section3>
|
||||
<section3 topic='Pubsub archives' anchor='business-storeret-pubsub-archives'>
|
||||
<p>
|
||||
|
|
@ -942,9 +955,9 @@
|
|||
access. For example authorized parties for a user's archive would likely include
|
||||
just the user, and a MUC archive for a private room might be restricted
|
||||
to room members. An implementation MAY choose to allow access to any archive
|
||||
by server administrators. If a client
|
||||
requests access to an archive it does not have permissions for the server MUST
|
||||
return an iq with type error, and the error condition SHOULD be 'forbidden'.</p>
|
||||
by server administrators. If a client requests access to an archive it does not
|
||||
have permissions for the server MUST return an iq with type error, and the error
|
||||
condition SHOULD be 'forbidden'.</p>
|
||||
<p>A server SHOULD provide a mechanism for a user to disable archiving of
|
||||
messages with all or specific contacts, such as via the configuration
|
||||
protocol described in &xep0441;. This allows the user to prevent the
|
||||
|
|
|
|||
Loading…
Reference in New Issue