ldap_search_s 函数 (winldap.h)

项目
03/04/2024

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

语法

WINLDAPAPI ULONG LDAPAPI ldap_search_s(
  [in]  LDAP         *ld,
  [in]  PSTR         base,
  [in]  ULONG        scope,
  [in]  PSTR         filter,
  [in]  PZPSTR       attrs,
  [in]  ULONG        attrsonly,
  [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 以检索所有可用属性。

[in] attrsonly

如果同时返回属性类型和值，则应为零的布尔值;如果只需要类型，则为非零值。

[out] res

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

返回值

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

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

注解

ldap_search_s 函数启动同步搜索。

将 ldap_set_option 函数与 ld 会话句柄结合使用，设置确定搜索执行方式 的LDAP_OPT_SIZELIMIT、 LDAP_OPT_TIMELIMIT和 LDAP_OPT_DEREF 选项。有关详细信息，请参阅会话选项。

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

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

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

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

// Perform the search request.
dwErr = ldap_search_s (i_pldap,
        i_lpszBase,
        i_ulScope,
        i_lpszSearchFilter,
        lpszAttributes,
        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_s"));
    hr = HRESULT_FROM_WIN32(dwErr);

    // Be aware that pMsg can contain valid data, even if the
    // call to ldap_search_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 just frees pMsg on any 
    // error code.

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

else
{
    // Process the search results.
    ...
    // Free the results when no longer required.
    if (pMsg != NULL) ldap_msgfree(pMsg);
}

要求

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