ldap_search_ext函式 (winldap.h)

發行項
03/04/2024

ldap_search_ext函式會搜尋 LDAP 目錄，並針對每個相符項目傳回一組所要求的屬性。

語法

WINLDAPAPI ULONG LDAPAPI ldap_search_ext(
  [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]  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。

[in] attrsonly

布爾值，如果傳回屬性類型和值，則為零;如果只傳回型別，則為非零值。

[in] ServerControls

LDAP 伺服器控制件的清單。

[in] ClientControls

用戶端控制件的清單。

[in] TimeLimit

指定本機搜尋逾時值，以秒為單位，以及傳送至搜尋要求內伺服器的作業時間限制。

[in] SizeLimit

要從搜尋傳回的項目數限制。值為零表示無限制。

[out] MessageNumber

要求訊息標識碼。

傳回值

如果函式成功，傳回值會 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 當作業傳回成功時，將訊息標識碼傳遞至呼叫端做為參數。使用訊息標識符呼叫ldap_result ，以取得作業的結果。

必須控制傳回結果速率的LDAP用戶端應用程式可以指定搜尋要求，以提供頁面結果控件的大小設定為所需的頁面大小，並將Cookie設定為零長度字元串。指定的頁面大小可能大於零，且小於搜尋要求中指定的 SizeLimit 值。

如果頁面大小大於或等於會話選項中所述的 SizeLimit 值選項，伺服器應該忽略控件，因為可以在單一頁面中滿足要求。如果伺服器不支援此控件，則如果用戶端要求它為重要，則伺服器必須傳回不支援的重要延伸模塊錯誤，否則伺服器應該忽略控件。本節的其餘部分假設伺服器不會忽略客戶端的分頁結果控件。

用戶端會傳送具有簡單分頁結果控件的搜尋要求伺服器，以及空的先前列舉索引鍵，也稱為“cookie”，以及初始頁面大小。接著，伺服器會傳回頁面大小所指定的項目數目，並傳回在下一個用戶端要求上發出的 Cookie，以取得下一頁的結果。用戶端接著會發出搜尋，其中包含 Cookie，並選擇性地重設頁面大小。接著，伺服器會傳回結果，最多傳回指定的項目數。若要指示函式直接傳回結果，請使用同步例程 ldap_search_ext_s。

多線程： 對ldap_search_ext 的呼叫是安全線程。

規格需求

需求	值
最低支援的用戶端	Windows Vista
最低支援的伺服器	Windows Server 2008
目標平台	Windows
標頭	winldap.h
程式庫	Wldap32.lib
Dll	Wldap32.dll