ldap_search_extW函数（winldap.h）

2024-11-20

ldap_search_ext 函数搜索 LDAP 目录，并为每个匹配项返回请求的属性集。

语法

WINLDAPAPI ULONG LDAPAPI ldap_search_extW(
  [in]  LDAP          *ld,
  [in]  const PWSTR   base,
  [in]  ULONG         scope,
  [in]  const PWSTR   filter,
  [in]  PZPWSTR       attrs,
  [in]  ULONG         attrsonly,
  [in]  PLDAPControlW *ServerControls,
  [in]  PLDAPControlW *ClientControls,
  [in]  ULONG         TimeLimit,
  [in]  ULONG         SizeLimit,
  [out] ULONG         *MessageNumber
);

参数

[in] ld

会话句柄。

[in] base

指向以 null 结尾的字符串的指针，该字符串包含要从中开始搜索的条目的可分辨名称。

[in] scope

指定以下值之一以指示搜索范围。

LDAP_SCOPE_BASE

仅搜索基本条目。

LDAP_SCOPE_ONELEVEL

在基本条目下方的第一个级别搜索所有条目，不包括基本条目。

LDAP_SCOPE_SUBTREE

搜索基础条目和基础下方树中的所有条目。

[in] filter

指向指定搜索筛选器的以 null 结尾的字符串的指针。有关详细信息，请参阅搜索筛选器语法。

[in] attrs

以 null 结尾的字符串的 null 终止数组，指示要为每个匹配项返回哪些属性。若要检索所有可用的属性，请传递 NULL。

[in] attrsonly

一个布尔值，如果同时返回属性类型和值，则为零;如果只返回类型，则为非零。

[in] ServerControls

LDAP 服务器控件的列表。

[in] ClientControls

客户端控件的列表。

[in] TimeLimit

指定本地搜索超时值（以秒为单位）和发送到搜索请求中的服务器的操作时间限制。

[in] SizeLimit

要从搜索返回的条目数限制。值为零表示没有限制。

[out] MessageNumber

请求消息 ID。

返回值

如果函数成功，则返回值 LDAP_SUCCESS。

如果函数失败，它将返回错误代码。有关详细信息，请参阅返回值。

言论

ldap_search_ext 函数启动异步搜索操作。 ldap_search_ext 的参数和效果包括 ldap_search的参数和效果。扩展函数包括用于支持客户端和服务器控件和线程安全性的其他参数，以及为每个搜索操作指定大小和时间限制。

将 ldap_set_option 函数与 ld 会话句柄配合使用，以设置确定搜索的执行方式的 LDAP_OPT_DEREF 选项。有关详细信息，请参阅会话选项。另外两个会话选项（LDAP_OPT_SIZELIMIT 和 LDAP_OPT_TIMELIMIT）将被忽略，以支持此函数中的 SizeLimit 和 TimeLimit 参数。

如果操作成功，ldap_search_ext 成功返回操作时将消息 ID 作为参数传递给调用方。使用消息 ID 调用 ldap_result 以获取操作的结果。

必须控制返回结果的速率的 LDAP 客户端应用程序可以指定搜索请求，以便提供一个分页结果控件，其大小设置为所需页面大小，Cookie 设置为零长度字符串。指定的页面大小可能大于零，并且小于搜索请求中指定的 SizeLimit 值。

如果页面大小大于或等于 SizeLimit会话选项中所述的值选项，则服务器应忽略该控件，因为请求可以在单个页面中得到满足。如果服务器不支持此控件，则如果客户端请求它为关键扩展，则服务器必须返回不受支持的严重扩展错误，否则服务器应忽略该控件。本部分的其余部分假定服务器不会忽略客户端的分页结果控件。

客户端使用简单的分页结果控件以及空的上一个枚举键（也称为“cookie”和初始页面大小）向服务器发送搜索请求。然后，服务器返回页面大小指定的条目数，并返回在下一个客户端请求上颁发的 Cookie 以获取下一页结果。然后，客户端会发出搜索，并包含 Cookie，可以选择重置页面大小。然后，服务器通过返回结果来响应，最多返回指定的条目数。若要指示函数直接返回结果，请使用同步例程 ldap_search_ext_s。

多线程处理：对 ldap_search_ext 的调用是线程安全的。

注意

winldap.h 标头将ldap_search_ext定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。有关详细信息，请参阅函数原型的约定。

要求

要求	价值
最低支持的客户端	Windows Vista
支持的最低服务器	Windows Server 2008
目标平台	窗户
标头	winldap.h
库	Wldap32.lib
DLL	Wldap32.dll