如何使用 VLV 搜尋

Active Directory 支援 VLV) 搜尋 (虛擬清單檢視。 此搜尋樣式特別針對大型結果集而設計,可讓應用程式顯示數千個專案的子集,而不需要實際擷取每個專案。

有兩種不同的方式可以使用 VLV 搜尋。 第一個是根據數值位移擷取特定專案的屬性。 當擷取搜尋結果以回應捲動作業時,這個方法很有用。

使用 VLV 搜尋的第二種方式是搜尋部分或所有文字屬性,並只顯示搜尋的結果。 這是通訊錄的範例用法。 如果使用者輸入 「s」,則應用程式可以使用 VLV 搜尋來搜尋具有開頭為 「s」 之通用名稱的專案。 如果使用者接著將 「m」 新增至 「s」,應用程式可以使用另一個 VLV 搜尋來搜尋具有開頭為 「sm」 之通用名稱的專案。

若要執行 VLV 搜尋,請指示 ADSI 使用 VLV 控制項。 若要這樣做,請使用具有ADSTYPE_PROV_SPECIFIC值的ADS_SEARCHPREF_VLV搜尋選項,呼叫IDirectorySearch::SetSearchPreference方法。 ADSTYPE_PROV_SPECIFIC值是包含搜尋相關資料的ADS_VLV結構的指標。 GetVLVItemCount範例函式示範如何設定這兩個搜尋喜好設定。

所有 VLV 搜尋都必須使用伺服器端結果排序,方法是設定 ADS_SEARCHPREF_SORT_ON 搜尋喜好設定來執行。 如需 ADS_SEARCHPREF_SORT_ON 搜尋喜好設定的詳細資訊,請參閱 使用 IDirectorySearch 排序搜尋結果

執行 VLV 搜尋時,會以ADS_VLV_RESPONSE識別碼呼叫IDirectorySearch::GetColumn,在擷取的資料行中傳回有關搜尋的特定中繼資料量。 此資料包含在 ADS_VLV 結構中。 特別重要的是 dwContentCountlpCoNtextID 成員。 dwContentCount成員將包含符合 VLV 搜尋準則的結果數目。 此值可用來做為針對該類型搜尋所傳回之專案總數的估計值。 lpCoNtextID成員包含伺服器定義的值,可傳遞至下一個搜尋以識別搜尋。 使用 lpCoNtextID 可以增強搜尋效能。 請注意 ,lpCoNtextID 是伺服器定義的值,而且其長度包含在 dwCoNtextIDLength 成員中。 呼叫 IDirectorySearch::FreeColumn 方法時,會釋放此緩衝區,因此呼叫端必須配置適當大小的緩衝區,並在搜尋之間複製並儲存緩衝區的內容。

如需 LDAP VLV 控制項的詳細資訊,請參閱 使用 LDAP VLV 控制項進行搜尋

如需詳細資訊,請參閱

取得專案數

若要取得針對特定搜尋傳回的專案數估計值,請執行下列步驟。

  1. 使用所有零或Null值填入ADS_VLV結構。

  2. 使用下列值填入 ADS_SEARCHPREF_INFO

    • dwSearchPref 成員設定為 ADS_SEARCHPREF_VLV
    • vValue.dwType 成員設定為 ADSTYPE_PROV_SPECIFIC
    • vValue.ProviderSpecific.dwLength 成員設定為 ADS_VLV 結構的大小。
    • vValue.ProviderSpecific.lpValue 成員設定為步驟 1 中 ADS_VLV 結構的位址。
  3. 填入 ADS_SORTKEY 結構,如 使用 IDirectorySearch 排序搜尋結果 中所示,以在所需的屬性上排序。

  4. 填入另一個 ADS_SEARCHPREF_INFO ,將 ADS_SORTKEY 結構新增至搜尋喜好設定,如 使用 IDirectorySearch 排序搜尋結果中所示。

  5. 新增任何其他所需的搜尋喜好設定,並呼叫 IDirectorySearch::SetSearchPreference 來設定搜尋喜好設定。

  6. 使用 IDirectorySearch::ExecuteSearch執行搜尋。

  7. 呼叫 IDirectorySearch::GetFirstRow以取得結果的第一個資料列。

  8. 使用ADS_VLV_RESPONSE呼叫IDirectorySearch::GetColumn以取得 VLV 搜尋中繼資料。

  9. ADS_SEARCH_COLUMN結構的pADsValues-ProviderSpecific.lpValue >轉換成ADS_VLV結構指標。 這個ADS_VLV結構的dwContentCount成員包含搜尋該類型所傳回的大約專案數。

  10. 如果執行相同類型的其他 VLV 搜尋,請建立 lpCoNtextID 資料的複本,並保留該資料以供下一個 VLV 搜尋使用。

GetVLVItemCount範例函式示範如何執行這項操作。

依位移搜尋

讓 VLV 搜尋變得非常快速的其中一件事,就是可以藉由數值位移搜尋特定結果。 例如,如果搜尋會導致傳回 10,000 個專案,則 VLV 搜尋可讓您取得大約 4072nd 專案的資訊,而不需要在有問題的專案之前擷取所有專案。

位移會指定為位移與內容計數之間的比率。 比率很有用,因為伺服器可能沒有正確估計清單中存在的專案數,或清單大小可能會在使用者流覽時變更。 由於您必須指出清單的開頭和結尾,因此您可以使用第一個搜尋要求中內容計數的估計值,以及位移值。 伺服器會根據內容計數的概念,使用此資料來計算清單中的對應位移,這會透過ADS_VLV結構的dwContentCount成員傳送給用戶端 例如,如果您估計清單大小為 3000,而您想要位移為清單專案 1500,您可以將 dwContentCount 設定為 3000, 並將 dwOffset 設定為 1500。 如果伺服器估計實際清單大小為 4500,則會將位移重新計算為 2250,並在 dwContentCountdwOffset中傳回新的估計值。

注意

VLV 搜尋中的所有數值都是近似值,不應用於絕對值。 例如,如果您在 100 的比率中發出第 50 個專案的 VLV 搜尋,則不保證會取得確切的中間專案。

若要依位移搜尋特定專案,請執行下列步驟。

  1. 使用下列值填入 ADS_VLV 結構。 結構的其他成員應該設定為零或 Null

    • dwContentCount 成員設定為要擷取之專案比例的最大值。
    • dwOffset 成員設定為相對於要擷取之專案或專案的 dwContentCount的比例。
    • lpCoNtextID 成員設定為內容識別碼緩衝區複本的位址,並將 dwCoNtextIDLength 設定為內容識別碼緩衝區的長度,以位元組為單位。 如果未儲存任何內容識別碼,則這兩個成員都應該為零或 Null
  2. 設定搜尋喜好設定,如取得專案數程式的步驟 2 到 5 所示。

  3. 使用 IDirectorySearch::ExecuteSearch執行搜尋。

  4. 呼叫 IDirectorySearch::GetFirstRow以取得結果的第一個資料列。

  5. 使用屬性名稱呼叫 IDirectorySearch::GetColumn 以擷取以取得所要求專案的實際資料。

  6. 使用ADS_VLV_RESPONSE呼叫IDirectorySearch::GetColumn以取得 VLV 搜尋中繼資料。

  7. ADS_SEARCH_COLUMN結構的pADsValues-ProviderSpecific.lpValue >轉換成ADS_VLV結構指標。

  8. 製作 lpCoNtextID 資料的複本,並保留以供下一個 VLV 搜尋使用。

 

GetVLVItemText範例函式示範如何執行這項操作。

您也可以使用單一搜尋呼叫來擷取一個以上的資料列。 這是在步驟 1 中完成的,方法是適當地設定ADS_VLV結構的dwBeforeCountdwAfterCount成員。 dwBeforeCount成員包含專案在有問題專案之前出現在清單中的專案數,而 dwAfterCount成員則包含清單中出現在有問題專案之後的專案數。 這兩個計數都會排除專案本身,因此將 dwBeforeCount 設定為 10 且 dwAfterCount 設為 10 將會導致傳回總共 21 個專案。 此選項可讓您在用戶端快取搜尋結果。

依字串搜尋

您也可以使用 VLV 搜尋來尋找具有字串屬性的專案,其值符合字串的所有或部分,而不需要擷取所有專案。 字串比對會針對ADS_SEARCHPREF_SORT_ON搜尋喜好設定ADS_SORTKEY結構中指定的屬性執行。

若要依字串搜尋特定專案,請執行下列步驟。

  1. 使用下列值填入 ADS_VLV 結構。 結構的其他成員應該設定為零或 Null

    • pszTarget 成員設定為指標,指向包含要搜尋之字串的 Null 終止字串。
    • lpCoNtextID 成員設定為內容識別碼緩衝區複本的位址,並將 dwCoNtextIDLength 設定為內容識別碼緩衝區的長度,以位元組為單位。 如果未儲存任何內容識別碼,則這兩個成員都應該為零或 Null
  2. 設定搜尋喜好設定,如取得專案數程式的步驟 2 到 5 所示。

  3. 使用 IDirectorySearch::ExecuteSearch執行搜尋。

  4. 呼叫 IDirectorySearch::GetFirstRow以取得結果的第一個資料列。

  5. 使用屬性名稱呼叫 IDirectorySearch::GetColumn 以擷取以取得所要求專案的實際資料。

  6. 使用ADS_VLV_RESPONSE呼叫IDirectorySearch::GetColumn以取得 VLV 搜尋中繼資料。

  7. ADS_SEARCH_COLUMN結構的pADsValues-ProviderSpecific.lpValue >轉換成ADS_VLV結構指標。

  8. 製作 lpCoNtextID 資料的複本,並保留以供下一個 VLV 搜尋使用。 如有需要, dwOffset 成員會包含字串屬性開頭為 pszTarget中所指定值之第一個專案的單一型索引。

GetVLVItemsByString範例函式會示範如何執行這項操作。

類似于依索引搜尋,您也可以使用單一搜尋呼叫來擷取多個資料列。 這可以透過適當地設定ADS_VLV結構的dwBeforeCountdwAfterCount成員,以相同方式完成。