LDAP Control Extension for Simple Paged Results Manipulation
RFC 2696

• Status
• IESG evaluation record
• IESG writeups
• Email expansions
• History

• Versions
• 03

Network Working Group                                        C. Weider
Request for Comments: 2696                                   A. Herron
Category: Informational                                     A. Anantha
                                                             Microsoft
                                                              T. Howes
                                                              Netscape
                                                        September 1999

      LDAP Control Extension for Simple Paged Results Manipulation

Status of this Memo

   This memo provides information for the Internet community.  It does
   not specify an Internet standard of any kind.  Distribution of this
   memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (1999).  All Rights Reserved.

1. 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].

2. The Control

   This control is included in the searchRequest and searchResultDone
   messages 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, 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    searchControlValue
}

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

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

3. Client-Server Interaction

   An LDAP client application that needs to control the rate at which
   results are returned MAY specify on the searchRequest a
   pagedResultsControl 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, the
   server should ignore the control as the request can be satisfied in a
   single page. If the server does not support this control, 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
   processing a search request containing the pagedResultsControl, the
   server includes the pagedResultsControl control in the
   searchResultDone message. 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, if there are more entries
   to return, 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

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 the
   initial request with the exception of the messageID, the cookie, and
   optionally a modified pageSize. The cookie MUST be the octet string
   on the last searchResultDone 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