Paging Search Results

When an LDAP client is accessing a server across a slow connection, or if the client suspects that the result set from a given query may be very large, the client should be able to retrieve a result set in small pieces. The Simple Paged Result extended control (defined in RFC 2696) allows this type of retrieval by allowing a one-way walk through a result set. Options on this control allow the client to set the initial page size and reset the page size with each subsequent request to the server.

The Simple Paged Result control is also used to access all of a large result set when there is a server-side administrative limit to the number of items returned from a query. For example, Active Directory servers have a default server-side limit of 1000 entries (LDAP policy MaxPageSize) as the maximum number of results that are returned in a single request. If the results of a query exceed this limit, the Paged Results control is used with a page size equal to or less than the server-side limit in order to retrieve all of the results of the query.

The interaction between client and server is as follows.

The client sends the server a search request with the Simple Paged Results control with an empty previous Enumeration Key, also known as a cookie, and the initial page size. The server then returns the number of entries specified by the page size and also returns a cookie used on the next client request to get the next page of results. The client then issues a search with the cookie included (optionally resetting the page size) and the server then responds with up to that number of entries.

Paged results are indicated as a control on the ldap_search_ext function call. Use ldap_create_page_control to construct this control, and then call ldap_search_ext to add the control. This control structure must then be added to the list of server controls in the ldap_search_ext call. When the server returns the first page of results, it includes the resume cookie in the controls field of the SearchResultDone message. The client must then extract the cookie from the search result by retrieving the server controls by using ldap_parse_result and parsing the control with ldap_parse_page_control. The client then uses the cookie in the next call to LDAP_create_page_control to retrieve the next page of results.

Rules for using Paged query control:

• The query parameters like filter, base object, scope and controls must stay the same. The paged query continuation fails if they are modified.
• The LDAP server session must stay the same as the paged query progresses. A cookie is specific to the LDAP session, so if you keep the cookie and switch to a different session, the next paged query will fail.
• You must expect that the server rejects the cookie you pass as it has not stored the context about it on the server anymore (spelled out in RFC 2696). For details on this see: How LDAP server cookies are handled