ldap_get_next_page_s

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

ULONG ldap_get_next_page_s(
  PLDAP ExternalHandle,
  PLDAPSearch SearchHandle,
  struct l_timeval* timeout,
  ULONG PageSize,
  ULONG* TotalCount,
  LDAPMessage** Results
);

Parameters

ExternalHandle

[in] The session handle.

SearchHandle

[in] Handle to the search block.

timeout

[in] The length of time, in seconds, that the client will wait for the call to return.

PageSize

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

TotalCount

[out] The server's estimate of the total number of entries in the entire result set. A value of zero means that the server cannot provide an estimate.

Results

[out] A pointer to the LDAPMessage structure that contains the results of the operation.

Return Values

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 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 abandon a search.

The results you get back from ldap_get_next_page_s can be treated as any other search result, and should be freed when you're done 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_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 end of the search has been reached.

To retrieve paged search result asychronously, use ldap_get_next_page.

Using ldap_get_next_page_s eliminates the need to call ldap_get_paged_count to record the number of paged results returned by a server.

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_get_next_page, ldap_get_paged_count, LDAPMessage, ldap_msgfree, ldap_search_init_page, Return Values