As per Relevance of the word returned, we have this rfc below:
Network Working Group C.
Request for Comments: 2696 A.
Category: Informational A.
T.
September 1999
LDAP Control Extension for Simple Paged Results
Status of this
This memo provides information for the Internet community. It
not specify an Internet standard of any kind. Distribution of
memo is unlimited
Copyright
Copyright (C) The Internet Society (1999). All Rights Reserved
1.
This document describes an LDAPv3 control extension for simple
of search results. This control extension allows a client to
the rate at which an LDAP server returns the results of an
search operation. This control may be useful when the LDAP client
limited resources and may not be able to process the entire
set from a given LDAP query, or when the LDAP client is
over a low-bandwidth connection. Other operations on the result
are not defined in this extension. This extension is not designed
provide more sophisticated result set management
The key words "MUST", "SHOULD", and "MAY" used in this document
to be interpreted as described in [bradner97].
2. The
This control is included in the searchRequest and
messages as part of the controls field of the LDAPMessage, as
in Section 4.1.12 of [LDAPv3]. The structure of this control is
follows
Weider, et al. Informational [Page 1]
RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999
pagedResultsControl ::= SEQUENCE {
controlType 1.2.840.113556.1.4.319,
criticality BOOLEAN DEFAULT FALSE
controlValue
The searchControlValue is an OCTET STRING wrapping the BER-
version of the following SEQUENCE
realSearchControlValue ::= SEQUENCE {
size INTEGER (0..maxInt),
-- requested page size from
-- result set size estimate from
cookie OCTET
3. Client-Server
An LDAP client application that needs to control the rate at
results are returned MAY specify on the searchRequest
pagedResultsControl with size set to the desired page size and
set to the zero-length string. The page size specified MAY be
than zero and less than the sizeLimit value specified in
searchRequest
If the page size is greater than or equal to the sizeLimit value,
server should ignore the control as the request can be satisfied in
single page. If the server does not support this control, the
MUST return an error of unsupportedCriticalExtension if the
requested it as critical, otherwise the server SHOULD ignore
control. The remainder of this section assumes the server does
ignore the client's pagedResultsControl
Each time the server returns a set of results to the client
processing a search request containing the pagedResultsControl,
server includes the pagedResultsControl control in
searchResultDone message. In the control returned to the client,
size MAY be set to the server's estimate of the total number
entries in the entire result set. Servers that cannot provide such
estimate MAY set this size to zero (0). The cookie MUST be set to
empty value if there are no more entries to return (i.e., the page
search results returned was the last), or, if there are more
to return, to an octet string of the server's choosing,used to
the search
The client MUST consider the cookie to be an opaque structure
make no assumptions about its internal organization or value.
the client wants to retrieve more entries for the result set, it
Weider, et al. Informational [Page 2]
RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999
send to the server a searchRequest with all values identical to
initial request with the exception of the messageID, the cookie,
optionally a modified pageSize. The cookie MUST be the octet
on the last searchResultDone response returned by the server
Returning cookies from previous searchResultDone responses
the last one is undefined, as the server implementation may
cookies from being reused
The server will then return the next set of results from the
result set. This interaction will continue until the client
retrieved all the results, in which case the cookie in
searchResultDone field will be empty, or until the client
the search sequence as described below. Once the paged
sequence has been completed, the cookie is no longer valid and
NOT be used
A sequence of paged search requests is abandoned by the
sending a search request containing a pagedResultsControl with
size set to zero (0) and the cookie set to the last cookie
by the server. A client MAY use the LDAP Abandon operation
abandon one paged search request in progress, but this is
as it MAY invalidate the client's cookie
If, for any reason, the server cannot resume a paged search
for a client, then it SHOULD return the appropriate error in
searchResultDone entry. If this occurs, both client and server
assume the paged result set is closed and no longer resumable
A client may have any number of outstanding search requests pending
any of which may have used the pagedResultsControl. A
implementation which requires a limit on the number of
paged search requests from a given client MAY either
unwillingToPerform when the client attempts to create a new
search request, or age out an older result set. If the
implementation ages out an older paged search request, it
return "unwilling to perform" if the client attempts to resume
paged search that was aged out
A client may safely assume that all entries that satisfy a
search query are returned once and only once during the set of
search requests/responses necessary to enumerate the entire
set, unless the result set for that query has changed since
searchRequest starting the request/response sequence was processed
In that case, the client may receive a given entry multiple
and/or may not receive all entries matching the given
criteria
Weider, et al. Informational [Page 3]
RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999
4.
The following example illustrates the client-server
between a client doing a search requesting a page size limit of 3.
The entire result set returned by the server contains 5 entries
Lines beginning with "C:" indicate requests sent from client
server. Lines beginning with "S:" indicate responses sent from
to client. Lines beginning with "--" are comments to help explain
example
-- Client sends a search request asking for paged
-- with a page size of 3.
C: SearchRequest + pagedResultsControl(3,"")
-- Server responds with three entries plus an
-- of 5 total entries in the search result and an
-- cooking to be used by the client when retrieving
-- pages
S:
S:
S:
S: SearchResultDone + pagedResultsControl(5, "opaque")
-- Client sends an identical search request (except
-- message id), returning the opaque cooking, asking
-- the next page
C: SearchRequest + PagedResultsControl(3, "opaque")
-- Server responds with two entries plus an
-- that there are no more entries (null cookie).
S:
S:
S: SearchResultDone + pagedResultsControl(5,"")
5. Relationship to X.500
For LDAP servers providing a front end to X.500 (93) directories,
paged results control defined in this document may be mapped
onto the X.500 (93) PagedResultsRequest defined in X.511 [x500].
size parameter may be mapped onto pageSize. The cookie parameter
be mapped onto queryReference. The sortKeys and reverse fields
the X.500 PagedResultsRequest are excluded
Weider, et al. Informational [Page 4]
RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999
6. Security
Server implementors should consider the resources used when
send searches with the simple paged control, to ensure that
client's misuse of this control does not lock out other
operations
Servers implementations may enforce an overriding sizelimit,
prevent the retrieval of large portions of a publically-
directory
Clients can, using this control, determine how many entries match
particular filter, before the entries are returned to the client
This may require special processing in servers which perform
control checks on entries to determine whether the existence of
entry can be disclosed to the client
7.
[LDAPv3] Wahl, M., Howes, T. and S. Kille, "Lightweight
Access Protocol (v3)", RFC 2251, December 1997.
[Bradner97] Bradner, S., "Key Words for use in RFCs to
Requirement Levels", BCP 14, RFC 2119, March 1997.
Weider, et al. Informational [Page 5]
RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999
8. Authors'
Chris
Microsoft Corp
1 Microsoft
Redmond, WA 98052
Phone: +1 425 882-8080
EMail: cweider@microsoft.
Andy
Microsoft Corp
1 Microsoft
Redmond, WA 98052
Phone: +1 425 882-8080
EMail: andyhe@microsoft.
Anoop
Microsoft Corp
1 Microsoft
Redmond, WA 98052
Phone: +1 425 882-8080
EMail: anoopa@microsoft.
Tim
Netscape Communications Corp
501 E. Middlefield
Mountain View, CA 94043
Phone: +1 415 937-2600
EMail: howes@netscape.
Weider, et al. Informational [Page 6]
RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999
9. Full Copyright
Copyright (C) The Internet Society (1999). All Rights Reserved
This document and translations of it may be copied and furnished
others, and derivative works that comment on or otherwise explain
or assist in its implementation may be prepared, copied,
and distributed, in whole or in part, without restriction of
kind, provided that the above copyright notice and this paragraph
included on all such copies and derivative works. However,
document itself may not be modified in any way, such as by
the copyright notice or references to the Internet Society or
Internet organizations, except as needed for the purpose
developing Internet standards in which case the procedures
copyrights defined in the Internet Standards process must
followed, or as required to translate it into languages other
English
The limited permissions granted above are perpetual and will not
revoked by the Internet Society or its successors or assigns
This document and the information contained herein is provided on
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE
Funding for the RFC Editor function is currently provided by
Internet Society
Weider, et al. Informational [Page 7]
if you see any problems within the linking, don't worry be happy,
this is version 0.1 of the Relevance System and you gotta expect some crappy subroutines sometimes,
just be content we did not write this in Java, which would have made this "bigger and better" HAHAHHA.
RFC documents can be found at I.E.T.F.
Relevance System Copyright © 2002 Spectrum WorldResearch
other technical nosh by ServerMasters Corporation
collaboration of BobX
