ldap_search_init_page function (winldap.h)

Article
09/22/2022

The ldap_search_init_page function initializes a search block for a simple paged-results search. This function is supported in LDAP 3.

Syntax

WINLDAPAPI PLDAPSearch LDAPAPI ldap_search_init_page(
  [in] PLDAP        ExternalHandle,
  [in] const PSTR   DistinguishedName,
  [in] ULONG        ScopeOfSearch,
  [in] const PSTR   SearchFilter,
  [in] PZPSTR       AttributeList,
  [in] ULONG        AttributesOnly,
  [in] PLDAPControl *ServerControls,
  [in] PLDAPControl *ClientControls,
  [in] ULONG        PageTimeLimit,
  [in] ULONG        TotalSizeLimit,
  [in] PLDAPSortKey *SortKeys
);

Parameters

[in] ExternalHandle

The session handle.

[in] DistinguishedName

A pointer to a null-terminated string that contains the distinguished name of the entry at which to start the search.

[in] ScopeOfSearch

A data type that specifies one of the following values to indicate the scope of the search.

LDAP_SCOPE_BASE

Search the base entry only.

LDAP_SCOPE_ONELEVEL

Search all entries in the first level below the base entry, excluding the base entry.

LDAP_SCOPE_SUBTREE

Search the base entry and all entries in the tree below the base.

[in] SearchFilter

A pointer to a null-terminated string that specifies the search filter. For more information, see Search Filter Syntax.

[in] AttributeList

A null-terminated array of null-terminated strings indicating which attributes to return for each matching entry. Pass NULL to retrieve all available attributes.

[in] AttributesOnly

A Boolean value that should be zero if both attribute types and values are to be returned, nonzero if only types are to be returned.

[in] ServerControls

A list of LDAP server controls.

[in] ClientControls

A list of client controls.

[in] PageTimeLimit

The time value, in seconds, that the client will wait for the server to return a page.

[in] TotalSizeLimit

The maximum number of entries the client will accept. The TotalSizeLimit value affects only the individual pages within the paged search (not the overall paged search). So if TotalSizeLimit is greater than page size, then TotalSizeLimit will have no effect.

[in] SortKeys

A pointer to an LDAPSortKey structure, which specifies the attribute type, the ordering rule, and the direction for the search.

Return value

If the function succeeds, it returns a pointer to an LDAPSearch structure.

If the function fails, the return value is NULL. Use LdapGetLastError or GetLastError to retrieve the error code.

Call the ldap_search_abandon_page to free the returned structure.

Remarks

The ldap_search_init_page function creates an LDAPSearch structure for managing paged searches and returns a handle to the structure. The ldap_get_next_page, ldap_get_next_page_s, and ldap_get_paged_count functions require this search handle as a parameter. When the paged search is completed, call ldap_search_abandon_page to free this structure and its handle.

To determine whether a server supports paged-results searches, check the supportedControl property off of the root for an object identifier (OID) of 1.2.840.113556.1.4.319.

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