如何使用 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結構中。 特別重要的是 dwContentCount 和 lpContextID 成員。 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 搜尋可讓您取得大約 4072 個專案的資訊，而不需要擷取有關專案之前的所有專案。

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

注意

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

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

  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結構的 dwBeforeCount 和 dwAfterCount 成員。 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結構的 dwBeforeCount 和 dwAfterCount 成員。