-
Notifications
You must be signed in to change notification settings - Fork 122
/
xep-0059.xml
561 lines (556 loc) · 29.4 KB
/
xep-0059.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Result Set Management</title>
<abstract>This document defines an XMPP protocol extension to enable entities to page through and otherwise manage the receipt of large result sets.</abstract>
&LEGALNOTICE;
<number>0059</number>
<status>Draft</status>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
<spec>XEP-0030</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>rsm</shortname>
<schemaloc>
<url>http://www.xmpp.org/schemas/rsm.xsd</url>
</schemaloc>
&ianpaterson;
&stpeter;
&val;
<author>
<firstname>Jean-Louis</firstname>
<surname>Seguineau</surname>
<email>[email protected]</email>
<jid>[email protected]</jid>
</author>
<revision>
<version>1.0</version>
<date>2006-09-20</date>
<initials>psa</initials>
<remark><p>Per a vote of the Jabber Council, advanced status to Draft.</p></remark>
</revision>
<revision>
<version>0.14</version>
<date>2006-09-13</date>
<initials>ip</initials>
<remark><p>Clarified terminology regarding pages and result sets.</p></remark>
</revision>
<revision>
<version>0.13</version>
<date>2006-09-07</date>
<initials>ip/psa</initials>
<remark><p>Reverted to v0.11 with slight wording changes.</p></remark>
</revision>
<revision>
<version>0.12</version>
<date>2006-09-06</date>
<initials>psa/vm</initials>
<remark><p>Added index attribute to before element; removed index element (use after or before instead).</p></remark>
</revision>
<revision>
<version>0.11</version>
<date>2006-08-25</date>
<initials>ip</initials>
<remark><p>Made count and index optional, changed protocol for getting count, more clarifications and examples.</p></remark>
</revision>
<revision>
<version>0.10</version>
<date>2006-08-24</date>
<initials>ip</initials>
<remark><p>Added before and first elements, specified how to return an empty page and how to request the last page, removed reverse order sets, added out-of-order page access.</p></remark>
</revision>
<revision>
<version>0.9</version>
<date>2006-08-23</date>
<initials>ip</initials>
<remark><p>Eliminated static result sets, justified expanded and clarified dynamic result sets, added page-not-found error, described when minimal state is necessary, added reverse order sets.</p></remark>
</revision>
<revision>
<version>0.8</version>
<date>2006-08-22</date>
<initials>psa</initials>
<remark><p>Added optional method for handling dynamic result sets.</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2006-08-10</date>
<initials>psa</initials>
<remark><p>Updated implementation note to clarify handling of result sets (static vs. dynamic).</p></remark>
</revision>
<revision>
<version>0.6</version>
<date>2006-07-12</date>
<initials>psa</initials>
<remark><p>Updated implementation note to clarify handling of result sets (static vs. dynamic).</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2006-05-02</date>
<initials>psa</initials>
<remark><p>Clarified error handling, determination of support in the context of using protocols, and security considerations.</p></remark>
</revision>
<revision>
<version>0.4</version>
<date>2006-04-24</date>
<initials>psa</initials>
<remark><p>Specified that an item count may be approximate; specified that an item count may be returned with a page of results.</p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2006-04-21</date>
<initials>psa/vm</initials>
<remark><p>Added <end/> element to specify last result set; added service discovery information; added more examples.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2005-12-22</date>
<initials>psa/vm</initials>
<remark><p>Revived and renamed the XEP; modified syntax; added use case for getting number of items; defined XML schema.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-11-12</date>
<initials>jls</initials>
<remark><p>Initial version.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>In &xep0055;, &xep0030;, &xep0060;, &xep0136;, and probably other future XMPP extensions, it is possible to receive large dynamic result sets in response to information requests (e.g., a user directory search on a common first name or a service discovery items request sent to a &xep0045; service). This XMPP protocol extension enables the following functionality for use by other XMPP protocols:</p>
<ol>
<li>Limit the number of items returned.</li>
<li>Page forwards or backwards through a result set by retrieving the items in smaller subsets.</li>
<li>Discover the size of a result set without retrieving the items themselves.</li>
<li>Retrieve a page (subset) of items starting at any point in a result set.</li>
</ol>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Limiting the Number of Items' anchor='limit'>
<p>In order to limit the number of items of a result set to be returned, the requesting entity specifies a request type of "set" and the maximum size of the desired subset (via the XML character data of the <max/> element):</p>
<example caption='Requesting a Limit to the Result Set'><![CDATA[
<iq type='get' from='[email protected]/roundabout' to='users.jabber.org' id='limit1'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
</set>
</query>
</iq>
]]></example>
<p>The responding entity then returns the first items of the result set in order. The number of items is limited to the requested size:</p>
<example caption='Returning a Limited Result Set'><![CDATA[
<iq type='result' from='users.jabber.org' to='[email protected]/roundabout' id='limit1'>
<query xmlns='jabber:iq:search'>
<item jid='[email protected]'>
<first>Peter</first>
<last>Saint-Andre</last>
<nick>Pete</nick>
</item>
.
[8 more items]
.
<item jid='[email protected]'>
<first>Peter</first>
<last>Pan</last>
<nick>Pete</nick>
</item>
</query>
</iq>
]]></example>
</section2>
<section2 topic='Paging Forwards Through a Result Set' anchor='forwards'>
<p>An entity often needs to retrieve a page of items adjacent to a page it has already received. For examples, when retrieving a complete result set in order page by page, or when a user 'scrolls' forwards one page.</p>
<p>The set of items that match a query MAY change over time, even during the time that a requesting entity pages through the result set (e.g., a set of chatrooms, since rooms can be created and destroyed at any time). The paging protocol outlined in this section is designed so that entities MAY provide the following features:</p>
<ul>
<li>Each page of the result set is up-to-date at the time it is sent (not just at the time the first page was sent).</li>
<li>No items will be omitted from pages not yet sent (even if, after earlier pages were sent, some of the items they contained were removed from the set).</li>
<li>When paging through the list in order, duplicate items are never received.</li>
<li>The responding entity maintains no state (or a single minimal state for all requesting entities containing the positions of all recently deleted items).</li>
<li>Rapid calculation of which items should appear on a requested page by responding entity (even for large result sets).</li>
</ul>
<p>Note: If a responding entity implements dynamic result sets then receiving entities paging through the complete result set should be aware that it may not correspond to the result set as it existed at any one point in time.</p>
<p>The request for the first page is the same as when <link url='#limit'>Limiting the Number of Items</link>:</p>
<example caption='Requesting the First Page of a Result Set'><![CDATA[
<iq type='get' from='[email protected]/roundabout' to='users.jabber.org' id='page1'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
</set>
</query>
</iq>
]]></example>
<p>Responding entity support for paging through a result set is optional. If it does support paging (not just <link url='#limit'>Limiting the Number of Items</link>), then in each page it returns, the responding entity MUST include <first/> and <last/> elements that specify the unique ID (UID) for the first and last items in the page. If there is only one item in the page, then the first and last UIDs MUST be the same. If there are no items in the page, then the <first/> and <last/> elements MUST NOT be included.</p>
<p>The responding entity may generate these UIDs in any way, as long as the UIDs are unique in the context of all possible members of the full result set. Each UID MAY be based on part of the content of its associated item, as shown below, or on an internal table index. Another possible method is to serialize the XML of the item and then hash it to generate the UID. Note: The requesting entity MUST treat all UIDs as opaque.</p>
<p>The responding entity SHOULD also include the number of items in the full result set (which MAY be approximate) encapsulated in a <count/> element. The <first/> element SHOULD include an 'index' attribute. This integer specifies the position within the full set (which MAY be approximate) of the first item in the page. If that item is the first in the full set, then the index SHOULD be '0'. If the last item in the page is the last item in the full set, then the value of the <first/> element's 'index' attribute SHOULD be the specified count minus the number of items in the last page.</p>
<p>Note: The <count/> element and 'index' attribute enable important functionality for requesting entities (for example, a scroll-bar user-interface component). They MAY be omitted, but <em>only</em> if it would be either impossible or exceptionally resource intensive to calculate reasonably accurate values.</p>
<example caption='Returning the First Page of a Result Set'><![CDATA[
<iq type='result' from='users.jabber.org' to='[email protected]/roundabout' id='page1'>
<query xmlns='jabber:iq:search'>
<item jid='[email protected]'>
<first>Peter</first>
<last>Saint-Andre</last>
<nick>Pete</nick>
</item>
.
[8 more items]
.
<item jid='[email protected]'>
<first>Peter</first>
<last>Pan</last>
<nick>Pete</nick>
</item>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='0'>[email protected]</first>
<last>[email protected]</last>
<count>800</count>
</set>
</query>
</iq>
]]></example>
<p>The requesting entity can then ask for the next page in the result set by including in its request the UID of the <em>last</em> item from the previous page (encapsulated in an <after/> element), along with the maximum number of items to return. Note: If no <after/> element is specified, then the UID defaults to "before the first item in the result set" (i.e., effectively an index of negative one).</p>
<example caption='Requesting the Second Page of a Result Set'><![CDATA[
<iq type='get' from='[email protected]/roundabout' to='users.jabber.org' id='page2'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<after>[email protected]</after>
</set>
</query>
</iq>
]]></example>
<p>The <em>first</em> item in the page returned by the responding entity MUST be the item that immediately <em>follows</em> the item that the requesting entity indicated in the <after/> element:</p>
<example caption='Returning the Second Page of a Result Set'><![CDATA[
<iq type='result' from='users.jabber.org' to='[email protected]/roundabout' id='page2'>
<query xmlns='jabber:iq:search'>
<item jid='[email protected]'>
<first>Peter</first>
<last>Pan</last>
<nick>Pete</nick>
</item>
.
[8 more items]
.
<item jid='[email protected]'>
<first>Peter</first>
<last>Rabbit</last>
<nick>Pete</nick>
</item>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='10'>[email protected]</first>
<last>[email protected]</last>
<count>800</count>
</set>
</query>
</iq>
]]></example>
<p>It may sometimes be necessary to return an empty <em>page</em> to the requesting entity. For example, with dynamic result sets the responding entity MAY delete some items from the full result set between requests. Another example occurs when the requesting entity specifies "0" for the maximum number items to return (see <link url='#count'>Getting the Item Count</link>).</p>
<example caption='Returning an Empty Page'><![CDATA[
<iq type='result' from='users.jabber.org' to='[email protected]/roundabout' id='page80'>
<query xmlns='jabber:iq:search'>
<set xmlns='http://jabber.org/protocol/rsm'>
<count>790</count>
</set>
</query>
</iq>
]]></example>
<p>If there are no items whatsoever in the <em>full</em> result set, the responding entity MUST return a response that adheres to the definition of the wrapper protocol (e.g., "jabber:iq:search", "http://jabber.org/protocol/disco#items", or "http://jabber.org/protocol/pubsub"). For both <cite>XEP-0055</cite> and <cite>XEP-0030</cite>, that means the responding entity shall return an empty &QUERY; element; for <cite>XEP-0060</cite>, that means the responding entity shall return an empty <pubsub/> element; for <cite>XEP-0136</cite>, that means the responding entity shall return an empty <list/> or <store/> element.</p>
</section2>
<section2 topic='Paging Backwards Through a Result Set' anchor='backwards'>
<p>The requesting entity MAY ask for the previous page in a result set by including in its request the UID of the <em>first</em> item from the page that has already been received (encapsulated in a <before/> element), along with the maximum number of items to return.</p>
<example caption='Requesting the Previous Page of a Result Set'><![CDATA[
<iq type='get' from='[email protected]/roundabout' to='users.jabber.org' id='back1'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<before>[email protected]</before>
</set>
</query>
</iq>
]]></example>
<p>The <em>last</em> item in the page returned by the responding entity MUST be the item that immediately <em>preceeds</em> the item that the requesting entity indicated it has already received:</p>
<example caption='Returning the Previous Page of a Result Set'><![CDATA[
<iq type='result' from='users.jabber.org' to='[email protected]/roundabout' id='back1'>
<query xmlns='jabber:iq:search'>
<item jid='[email protected]'>
<first>Peter</first>
<last>Saint-Andre</last>
<nick>Pete</nick>
</item>
.
[8 more items]
.
<item jid='[email protected]'>
<first>Peter</first>
<last>Pan</last>
<nick>Pete</nick>
</item>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='0'>[email protected]</first>
<last>[email protected]</last>
<count>800</count>
</set>
</query>
</iq>
]]></example>
</section2>
<section2 topic='Page Not Found' anchor='notfound'>
<p>The responding entity MUST reply with an 'item-not-found' error if <em>all</em> the following circumstances apply:</p>
<ol>
<li><p>The item specified by the requesting entity via the UID in the <after/> or <before/> element no longer exists (it was deleted after the previous page was sent).</p></li>
<li><p>The UID itself cannot be used to derive directly the next item within the set (e.g. the alphabetical or numerical order of the UIDs do not specify the order of the items).</p></li>
<li><p>The responding entity does not remember the position of the deleted item within the full list. (Even if the responding entity bothers to remember the position of each deleted item, it will typically be necessary to expire that 'state' after an implementation-specific period of time.)</p></li>
</ol>
<example caption='Returning a Page-Not-Found Error'><![CDATA[
<iq type='error' from='users.jabber.org' to='[email protected]/roundabout' id='page2'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<after>[email protected]</after>
</set>
</query>
<error type='cancel'>
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section2>
<section2 topic='Requesting the Last Page in a Result Set' anchor='last'>
<p>The requesting entity MAY ask for the last page in a result set by including in its request an empty <before/> element, and the maximum number of items to return.</p>
<example caption='Requesting the Last Page of a Result Set'><![CDATA[
<iq type='get' from='[email protected]/roundabout' to='users.jabber.org' id='page1'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<before/>
</set>
</query>
</iq>
]]></example>
</section2>
<section2 topic='Retrieving a Page Out of Order' anchor='jump'>
<p>The requesting entity MAY choose not to retrieve pages from the result set in order. (For example, when its user drags a user-interface slider to a radically new position within a very large result set.)</p>
<p>Only if the UID before the start (or after the end) of a desired result set page is not known, then the requesting entity MAY request the page that <em>starts</em> at a particular index within the result set. It does that by including in its request the index of the <em>first</em> item to be returned (encapsulated in an <index/> element), as well as the maximum number of items to return. Note: For reasons mentioned in <link url='#forwards'>Paging Forwards Through a Result Set</link> requesting entities SHOULD, where possible, specify pages using a UID instead of an index.</p>
<p>Note: If the responding entity omitted the <count/> element from previous responses for this result set, then the requesting entity SHOULD assume that the responding entity does not support page retrieval by index for this result set (see error below).</p>
<example caption='Requesting a Result Page by Index'><![CDATA[
<iq type='get' from='[email protected]/roundabout' to='users.jabber.org' id='index10'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<index>371</index>
</set>
</query>
</iq>
]]></example>
<p>The responding entity SHOULD derive the first UID from the specified index (the method used MAY be approximate) before returning the requested result set page in the normal way. If the specified index was "0" then the responding entity SHOULD derive the UID that is the first in the full result set.</p>
<p>Note: The 'index' attribute of the <first/> element MUST be the same as the index specified in the request. If the index specified by the requesting entity is greater than or equal to the number of items in the full set then the responding entity MUST return an empty page (see <link url='#forwards'>Paging Forwards Through a Result Set</link>).</p>
<example caption='Returning a Result Page at an Index'><![CDATA[
<iq type='result' from='users.jabber.org' to='[email protected]/roundabout' id='index10'>
<query xmlns='jabber:iq:search'>
<item jid='[email protected]'>
<first>Peter</first>
<last>Pan</last>
<nick>Pete</nick>
</item>
.
[8 more items]
.
<item jid='[email protected]'>
<first>Peter</first>
<last>Rabbit</last>
<nick>Pete</nick>
</item>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='10'>[email protected]</first>
<last>[email protected]</last>
<count>800</count>
</set>
</query>
</iq>
]]></example>
<p>If it would be either impossible or exceptionally resource intensive for the responding entity to derive the first UID from the specified index with reasonable accuracy then the responding entity MAY return a &e501; error.</p>
<example caption='Returning a Feature-not-Implemented Error'><![CDATA[
<iq type='error' from='users.jabber.org' to='[email protected]/roundabout' id='index10'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>10</max>
<index>371</index>
</set>
</query>
<error type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section2>
<section2 topic='Getting the Item Count' anchor='count'>
<p>In order to get the item count of a result set without retrieving the items themselves, the requesting entity simply specifies zero for the maximum size of the result set page:</p>
<example caption='Requesting the Item Count'><![CDATA[
<iq type='get' from='[email protected]/roundabout' to='users.jabber.org' id='count1'>
<query xmlns='jabber:iq:search'>
<nick>Pete</nick>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>0</max>
</set>
</query>
</iq>
]]></example>
<p>The responding entity then returns the item count, which MAY be approximate rather than precise if determining the exact number of items would be resource-intensive:</p>
<example caption='Returning the Item Count'><![CDATA[
<iq type='result' from='users.jabber.org' to='[email protected]/roundabout' id='count1'>
<query xmlns='jabber:iq:search'>
<set xmlns='http://jabber.org/protocol/rsm'>
<count>800</count>
</set>
</query>
</iq>
]]></example>
<p>Note: The <count/> element MAY be omitted, but <em>only</em> if it would be either impossible or exceptionally resource intensive to calculate reasonably accurate values.</p>
<p>Note: If there are no items in the <em>full</em> result set then the responding entity MUST return a response that adheres to the definition of the wrapper protocol (see <link url='#forwards'>Paging Forwards Through a Result Set</link>).</p>
</section2>
</section1>
<section1 topic='Examples' anchor='examples'>
<p>The foregoing examples show the use of result set management in the context of <cite>Jabber Search</cite>. In the following examples we show the use of this protocol in the context of <cite>Service Discovery</cite>. <cite>XEP-0136</cite> ("Message Archiving") includes more examples. A future version of this document may also include examples from <cite>Publish-Subscribe</cite> and other XMPP protocol extensions.</p>
<example caption='Requesting a Limit to the Result Set'><![CDATA[
<iq type='get' from='[email protected]/roundabout' to='conference.jabber.org' id='ex2'>
<query xmlns='http://jabber.org/protocol/disco#items'>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>20</max>
</set>
</query>
</iq>
]]></example>
<example caption='Returning a Limited Result Set'><![CDATA[
<iq type='result' from='conference.jabber.org' to='[email protected]/roundabout' id='ex2'>
<query xmlns='http://jabber.org/protocol/disco#items'>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<item jid='[email protected]'/>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='0'>acc3594e844c77696f7a7ba9367ae324b6b958ad</first>
<last>4da91d4b330112f683dddaebf93180b1bd25e95f</last>
<count>150</count>
</set>
</query>
</iq>
]]></example>
<example caption='Requesting a Page Beginning After the Last Item Received'><![CDATA[
<iq type='get' from='[email protected]/roundabout' to='conference.jabber.org' id='ex3'>
<query xmlns='http://jabber.org/protocol/disco#items'>
<set xmlns='http://jabber.org/protocol/rsm'>
<max>20</max>
<after>4da91d4b330112f683dddaebf93180b1bd25e95f</after>
</set>
</query>
</iq>
]]></example>
</section1>
<section1 topic='Determining Support' anchor='disco'>
<p>In order for a requesting entity to determine if a responding entity supports result set management, it SHOULD send a <cite>Service Discovery</cite> information request to the responding entity:</p>
<example caption='Requesting entity queries responding entity regarding protocol support'><![CDATA[
<iq from='[email protected]/roundabout'
to='conference.jabber.org'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption='Responding entity communicates protocol support'><![CDATA[
<iq from='conference.jabber.org'
to='[email protected]/roundabout'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='http://jabber.org/protocol/rsm'/>
...
</query>
</iq>
]]></example>
<p>An entity SHOULD NOT include the result set management extensions defined in this document in its requests if it does not have positive knowledge that the responding entity supports the protocol defined herein. If the responding entity does not understand result set management, it MUST ignore such extensions.</p>
<p>Note: Even if a responding entity understands the result set management protocol, its support for result set management in the context of any given "using protocol" is OPTIONAL (e.g., an implementation could support it in the context of the 'jabber:iq:search' namespace but not in the context of the 'http://jabber.org/protocol/disco#items' namespace). Currently the only way for a requesting entity to determine if a responding entity supports result set management in the context of a given "using protocol" is to include result set management extensions in its request. If the responding entity does not include result set management extensions in its response, then the requesting entity SHOULD NOT include such extensions in future requests wrapped by the "using protocol" namespace.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>Security considerations are the responsibility of the using ("wrapper") protocol, such as <cite>XEP-0030</cite> for the 'http://jabber.org/protocol/disco#items' namespace, <cite>XEP-0055</cite> for the 'jabber:iq:search' namespace, and <cite>XEP-0136</cite> for the 'http://jabber.org/protocol/archive' namespace.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>The ®ISTRAR; includes 'http://jabber.org/protocol/rsm' in its registry of protocol namespaces.</p>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/rsm'
xmlns='http://jabber.org/protocol/rsm'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
XEP-0059: http://www.xmpp.org/extensions/xep-0059.html
</xs:documentation>
</xs:annotation>
<xs:element name='set'>
<xs:complexType>
<xs:sequence>
<xs:element name='after' type='xs:string' minOccurs='0' maxOccurs='1'/>
<xs:element name='before' type='xs:string' minOccurs='0' maxOccurs='1'/>
<xs:element name='count' type='xs:int' minOccurs='0' maxOccurs='1'/>
<xs:element ref='first' minOccurs='0' maxOccurs='1'/>
<xs:element name='index' type='xs:int' minOccurs='0' maxOccurs='1'/>
<xs:element name='last' type='xs:string' minOccurs='0' maxOccurs='1'/>
<xs:element name='max' type='xs:int' minOccurs='0' maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='first'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='index' type='xs:int' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Olivier Goffart, Jon Perlow, and Andrew Plotkin for their feedback.</p>
</section1>
</xep>