ldap_search_init_page

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

PLDAPSearch ldap_search_init_page(
  PLDAP ExternalHandle,
  PCHAR DistinguishedName,
  ULONG ScopeOfSearch,
  PCHAR SearchFilter,
  PCHAR AttributeList[],
  ULONG AttributesOnly,
  PLDAPControl* ServerControls,
  PLDAPControl* ClientControls,
  ULONG PageTimeLimit,
  ULONG TotalSizeLimit,
  PLDAPSortKey* SortKeys
);

Parameters

ExternalHandle

[in] The session handle.

DistinguishedName

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

ScopeOfSearch

[in] Specifies one of the following values to indicate the scope of the search.

Value	Meaning
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.

SearchFilter

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

AttributeList

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

AttributesOnly

[in] A boolean value that should be zero if both attribute types and values are to be returned, nonzero if only types are wanted.

ServerControls

[in] A list of LDAP server controls.

ClientControls

[in] A list of client controls.

PageTimeLimit

[in] The amount of time the client will wait for the server to return a page.

TotalSizeLimit

[in] The maximum number of entries the client will accept .

SortKeys

[in] Pointer to an LDAPSortKey structure, which specifies the attribute type, the ordering rule, and the direction for the search.

Return Values

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.

Remarks

Call ldap_search_init_page to begin a paged-results search. When the function returns, use the returned handle to call.

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

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.
Unicode: Implemented as Unicode and ANSI versions on all platforms.
Header: Declared in Winldap.h.
Library: Use Wldap32.lib.

See Also

Functions, GetLastError, LdapGetLastError, LDAPSearch, ldap_get_next_page, ldap_get_next_page_s, ldap_search_abandon_page, LDAPSortKey