ldap_search_ext_s 函数 (winldap.h)

2024-03-13

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

语法

WINLDAPAPI ULONG LDAPAPI ldap_search_ext_s(
  [in]  LDAP          *ld,
  [in]  PSTR          base,
  [in]  ULONG         scope,
  [in]  PSTR          filter,
  [in]  PZPSTR        attrs,
  [in]  ULONG         attrsonly,
  [in]  PLDAPControlA *ServerControls,
  [in]  PLDAPControlA *ClientControls,
  [in]  l_timeval     *timeout,
  [in]  ULONG         SizeLimit,
  [out] PLDAPMessage  *res
);

参数

[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] timeout

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

[in] SizeLimit

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

[out] res

包含调用完成后的搜索结果。当函数调用失败并出现错误代码时，还可以包含部分结果或扩展数据。当应用程序不再需要时，通过调用 ldap_msgfree 免费返回结果。

返回值

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

如果函数失败，它将返回错误代码，但 ldap_search_ext_s 可能会失败，并且仍然可以分配 pMsg。例如， LDAP_PARTIAL_RESULTS 和 LDAP_REFERRAL 错误代码都将分配 pMsg。有关详细信息，请参阅以下代码示例。有关详细信息，请参阅返回值。

注解

ldap_search_ext_s 函数启动同步搜索操作。 ldap_search_ext_s的参数和效果包括ldap_search_s的参数和效果。扩展例程包括其他参数，以支持客户端和服务器控件，并指定每个搜索操作的大小和时间限制。

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

完成搜索操作后， ldap_search_ext_s 返回给调用方。使用 ldap_search_ext 异步执行操作。

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

下面的代码示例演示如何在ldap_search_ext_s失败时释放 pMsg。

// Initialize return value to NULL.
LDAPMessage *pMsg = NULL;

// Perform the search request.
dwErr = ldap_search_ext_s (i_pldap,
        i_lpszBase,
        i_ulScope,
        i_lpszSearchFilter,
        lpszAttributes,
        0,
        pServerControls,
        pClientControls,
        lpsTimeout,
        0,
        &pMsg
        );

// Cleanup calling parameters.
if (lpszAttributes != NULL)
    delete [] lpszAttributes;

// Convert error code and cleanup pMsg if necessary.
if (dwErr != LDAP_SUCCESS)
{
    DebugOutLDAPError(i_pldap, dwErr, _T("ldap_search_ext_s"));
    hr = HRESULT_FROM_WIN32(dwErr);

    // Be aware that pMsg can contain valid data, even if
    // the call to ldap_search_ext_s returned an error code.
    // This can be caused by the server returning codes
    // such as LDAP_RESULTS_TOO_LARGE or other codes
    // that indicate that the search returned partial
    // results. The user code can handle these cases
    // if required, this example frees pMsg on any 
    // error code.

    if (pMsg != NULL) ldap_msgfree(pMsg);
}

else
{
    // Process the search results.
    ...
    // Free the results when complete.
    if (pMsg != NULL) ldap_msgfree(pMsg);

}

要求

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