ldap_search_st 函数 (winldap.h)

项目
03/13/2024

ldap_search_st 函数同步搜索 LDAP 目录，并为匹配的每个条目返回一组请求的属性。附加参数指定搜索的本地超时。函数与 ldap_search_s 相同，但附加的本地超时参数除外。

语法

WINLDAPAPI ULONG LDAPAPI ldap_search_st(
  [in]  LDAP         *ld,
  [in]  PSTR         base,
  [in]  ULONG        scope,
  [in]  PSTR         filter,
  [in]  PZPSTR       attrs,
  [in]  ULONG        attrsonly,
  [in]  l_timeval    *timeout,
  [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] timeout

本地搜索超时值（以秒为单位）。

[out] res

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

返回值

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

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

注解

ldap_search_st 函数启动同步搜索操作。

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

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

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

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

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

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

    // Be aware that pMsg can contain valid data, even if the
    // call to ldap_search_st 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 complete.
    if (pMsg != NULL) ldap_msgfree(pMsg);
}

要求

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