ldap_get_next_page

The ldap_get_next_page function returns the next page in a sequence of asynchronous paged search results. This function is available in LDAP 3 and later.

ULONG ldap_get_next_page(
  PLDAP ExternalHandle,
  PLDAPSearch SearchHandle,
  ULONG PageSize,
  ULONG* MessageNumber
);

Parameters

ExternalHandle

[in] The session handle.

SearchHandle

[in] Handle to the search block.

PageSize

[in] The number of entries to return in a single page.

MessageNumber

[out] The message ID for the request.

Return Values

If the function succeeds, the return value is LDAP_SUCCESS.

If the function fails, it returns an error code. For more information, see Return Values.

Remarks

The ldap_get_next_page function is part of the interface for simple, asynchronous 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 abandon a search.

Be aware that after each call to ldap_get_next_page, you must call ldap_get_paged_count for each set of results returned from the server via ldap_result. This allows the LDAP run time to save off the cookie that the server passed back to maintain the state of the search. Other than calling ldap_get_paged_count, the results you get back from ldap_get_next_page can be treated as any other search result, and must be freed when complete by calling ldap_msgfree.

When parsing the results set, be aware that it is possible for the server to return an empty page of results and yet still respond legitimately 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 is not yet finished with the search request. The proper behavior in this instance is to continue to call ldap_get_next_page until either another page of results are successfully retrieved, an error code is returned, or LDAP_NO_RESULTS_RETURNED is returned to indicate the end of the search has been reached.

If you prefer to retrieve paged search results synchronously, use ldap_get_next_page_s.

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Header: Declared in Winldap.h.
Library: Use Wldap32.lib.

See Also

Functions, LDAP, ldap_get_next_page_s, ldap_get_paged_count, ldap_msgfree, ldap_result, ldap_search_init_page, Return Values