ldap_search_ext_sW函式（winldap.h）

發行項
11/20/2024

ldap_search_ext_s 函式會同步搜尋 LDAP 目錄，並針對每個相符專案傳回一組要求的屬性。

語法

WINLDAPAPI ULONG LDAPAPI ldap_search_ext_sW(
  [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]  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，以擷取所有可用的屬性。

[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);

}

注意

winldap.h 標頭會將ldap_search_ext_s定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows Vista
支援的最低伺服器	Windows Server 2008
目標平臺	窗戶
標頭	winldap.h
連結庫	Wldap32.lib
DLL	Wldap32.dll