[Search] [txt|pdf|bibtex] [Tracker] [WG] [Email] [Nits]

Versions: 00 01 02 03 rfc2696                                           
Network Working Group                          Chris Weider, Microsoft
INTERNET DRAFT                                  Andy Herron, Microsoft
Expire in six months                               Tim Howes, Netscape
                                                        February, 1997

      LDAP Control Extension for Simple Paged Results Manipulation

1.  Status of this Memo

This document is an Internet-Draft.  Internet-Drafts are  working  docu-
ments  of the Internet Engineering Task Force (IETF), its areas, and its
working groups.  Note that other  groups  may  also  distribute  working
documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum  of  six  months
and  may  be  updated,  replaced, or obsoleted by other documents at any
time.  It is inappropriate to use Internet- Drafts as reference material
or to cite them other than as ``work in progress.''

To learn the current status of  any  Internet-Draft,  please  check  the
``1id-abstracts.txt''  listing  contained in the Internet- Drafts Shadow
Directories on ds.internic.net (US East Coast), nic.nordu.net  (Europe),
ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).

2.  Abstract

This document describes an LDAPv3 control extension for simple paging of
search  results.  This  control extension allows a client to control the
rate at which an LDAP server returns  the  results  of  an  LDAP  search
operation.  This  control may be useful when the LDAP client has limited
resources and may not be able to process the entire result  set  from  a
given  LDAP  query,  or  when  the  LDAP client is connected over a low-
bandwidth connection. Other operations on the result set are not defined
in  this  extension.  This  extension  is  not  designed to provide more
sophisticated result set management.

The key words "MUST", "SHOULD", and "MAY" used in this document  are  to
be interpreted as described in [bradner97].

3.  The Control

This control is included in the searchRequest and searchResultDone  mes-
sages  as  part  of the controls field of the LDAPMessage, as defined in
Section 4.1.12 of [LDAPv3]. The structure of this control is as follows:

Weider, Herron & Howes                                          [Page 1]

INTERNET DRAFT                                             February 1997

     pagedResultsControl ::= SEQUENCE {
             controlType     1.2.840.113556.1.4.319,
             criticality     BOOLEAN DEFAULT FALSE,
             controlValue    searchControlValue

The searchControlValue is an OCTET STRING wrapping the BER-encoded  ver-
sion of the following SEQUENCE:

     realSearchControlValue ::= SEQUENCE {
             size            INTEGER (0..maxInt),
                                     -- requested page size from client
                                     -- result set size estimate from server
             cookie          OCTET STRING

4.  Client-Server Interaction

An LDAP client application that needs  to  control  the  rate  at  which
results are returned MAY specify on the searchRequest a pagedResultsCon-
trol with size set to the desired page size and cookie set to the  zero-
length string. The page size specified MAY be greater than zero and less
than the sizeLimit value specified in the searchRequest.

If the page size is greater than or equal to  the  sizeLimit  value,  or
equal  to  zero, the server should ignore the control as the request can
be satisfied in a single page. If the server does not support this  con-
trol, the server MUST return an error of unsupportedCriticalExtension if
the client requested it as critical, otherwise the server SHOULD  ignore
the  control.  The remainder of this section assumes the server does not
ignore the client's pagedResultsControl.

Each time the server returns a set of results to the  client  when  pro-
cessing  a search request containing the pagedResultsControl, the server
includes the pagedResultsControl control in  the  searchResultDone  mes-
sage.  In the control returned to the client, the size MAY be set to the
server's estimate of the total number of entries in  the  entire  result
set.  Servers  that cannot provide such an estimate MAY set this size to
zero (0).  The cookie MUST be set to an empty value if there are no more
entries  to  return  (i.e.,  the page of search results returned was the
last), or to an octet string of the server's choosing,  used  to  resume
the search.

The client MUST consider the cookie to be an opaque structure  and  make
no assumptions about its internal organization or value. When the client
wants to retrieve more entries for the result set, it MUST send  to  the
server  a searchRequest with all values identical to the initial request

Weider, Herron & Howes                                          [Page 2]

INTERNET DRAFT                                             February 1997

with the exception of the messageID, the cookie, and optionally a  modi-
fied  pageSize.  The  cookie  MUST be the octet string on the last sear-
chResultDone response returned by the  server.  Returning  cookies  from
previous  searchResultDone  responses besides the last one is undefined,
as the server implementation may restrict cookies from being reused.

The server will then return the next  set  of  results  from  the  whole
result  set.  This  interaction  will  continue  until  the  client  has
retrieved all the results, in which case the cookie in the searchResult-
Done  field  will  be empty, or the client abandons the result.  If, for
any reason, the server cannot resume a  paged  search  operation  for  a
client,  then  it SHOULD return the appropriate error in a searchResult-
Done entry. If this occurs, both client and  server  should  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 server implementation
which requires a  limit  on  the  number  of  outstanding  paged  search
requests  from  a given client MAY either return unwillingToPerform when
the client attempts to create a new paged search request, or age out  an
older  result set.  If the server implementation ages out an older paged
search request, it SHOULD return "unwilling to perform"  if  the  client
attempts to resume the paged search that was aged out.

A client may safely assume that all entries that satisfy a given  search
query  are  returned  once  and only once during the set of paged search
requests/responses necessary to enumerate the entire result set,  unless
the result set for that query has changed since the searchRequest start-
ing the request/response sequence  was  processed.  In  that  case,  the
client  may  receive a given entry multiple times and/or may not receive
all entries matching the given search criteria.

5.  Example

The following example illustrates the client-server interaction  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 to  server.
Lines beginning with "S:" indicate responses sent from server to client.
Lines beginning with "--" are comments to help explain the example.

     -- Client sends a search request asking for paged results
     -- with a page size of 3.
     C: SearchRequest + pagedResultsControl(3,"")
     -- Server responds with three entries plus an indication
     -- of 5 total entries in the search result and an opaque
     -- cooking to be used by the client when retrieving subsequent

Weider, Herron & Howes                                          [Page 3]

INTERNET DRAFT                                             February 1997

     -- pages.
     S: SearchResultEntry
     S: SearchResultEntry
     S: SearchResultEntry
     S: SearchResultDone + pagedResultsControl(5, "opaque")
     -- Client sends an identical search request (except for
     -- message id), returning the opaque cooking, asking for
     -- the next page.
     C: SearchRequest + PagedResultsControl(3, "opaque")
     -- Server responds with two entries plus an indication
     -- that there are no more entries (null cookie).
     S: SearchResultEntry
     S: SearchResultEntry
     S: SearchResultDone + pagedResultsControl(5,"")

6.  Security Considerations

Security considerations are not discussed in this document.

7.  References

     Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access  Pro-
     tocol  (v3)",  Internet  Draft, February, 1997. Available as draft-

     Bradner, Scott, "Key Words for use in RFCs to Indicate  Requirement
     Levels",   Internet  Draft,  January,  1997.  Available  as  draft-

8.  Author's Address

   Chris Weider
   Microsoft Corp.
   1 Microsoft Way
   Redmond, WA 98052
   +1 206 882-8080

   Andy Herron
   Microsoft Corp.
   1 Microsoft Way
   Redmond, WA 98052

Weider, Herron & Howes                                          [Page 4]

INTERNET DRAFT                                             February 1997

   +1 206 882-8080

   Tim Howes
   Netscape Communications Corp.
   501 E. Middlefield Road
   Mountain View, CA 94043
   +1 415 937-2600

Weider, Herron & Howes                                          [Page 5]