ldap_get_next_page_s function (winldap.h)

Article
10/13/2021

The ldap_get_next_page_s function returns the next page in a sequence of synchronous paged search results.

Syntax

WINLDAPAPI ULONG LDAPAPI ldap_get_next_page_s(
  [in]  PLDAP       ExternalHandle,
  [in]  PLDAPSearch SearchHandle,
  [in]  l_timeval   *timeout,
  [in]  ULONG       PageSize,
  [out] ULONG       *TotalCount,
  [out] LDAPMessage **Results
);

Parameters

[in] ExternalHandle

Session handle.

[in] SearchHandle

Search block handle.

[in] timeout

The time value, in seconds, that the client will wait for the call to return.

[in] PageSize

The number of entries to return in a single page.

[out] TotalCount

The server estimate of the total number of entries in the entire result set. A value of zero indicates that the server cannot provide an estimate.

[out] Results

A pointer to the LDAPMessage structure that contains the results.

Return value

If the server returns a null cookie (non-continuation), the value is LDAP_NO_RESULTS_RETURNED. Otherwise, the client signals a continuation (more data available) by returning LDAP_SUCCESS.

If the function otherwise fails, it returns the error code return value related to the failure. For more information, see Return Values.

Remarks

The ldap_get_next_page_s function is part of the interface for simple, synchronous paging of search results. Use the search handle returned from an initial call to ldap_search_init_page and specify, in the PageSize parameter, the number of entries to be returned in a page. Set PageSize to zero to quit a search.

The results returned from ldap_get_next_page_s can be handled as any other search result, and should be freed, when finished, by calling ldap_msgfree.

When parsing the results set, it is possible for the server to return an empty page of results and yet still respond with an LDAP_SUCCESS return code. This indicates that the server was unable to retrieve a page of results, due to a timeout or other reason, but has not completed the search request. The proper behavior in this instance is to continue to call ldap_get_next_page_s until either another page of results are successfully retrieved, an error code is returned, or LDAP_NO_RESULTS_RETURNED is returned to indicate the search is complete.

To retrieve paged search result asynchronously, use ldap_get_next_page.

If ldap_get_next_page_s is used, it is not required that ldap_get_paged_count is called to record the number of paged results returned by a server.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	winldap.h
Library	Wldap32.lib
DLL	Wldap32.dll