Поиск с помощью VLV

Active Directory поддерживает поиски по представлению виртуальных списков (VLV). Этот стиль поиска специально предназначен для больших результирующих наборов и позволяет приложению отображать подмножество тысяч записей без фактического получения каждой записи.

Существует два разных способа использования поиска VLV. Первое — получить атрибуты для определенных записей на основе числового смещения. Этот метод полезен при получении результатов поиска в ответ на операцию прокрутки.

Вторым способом использования поиска VLV является поиск части или всего текстового атрибута и отображение результатов поиска. Примером использования этого является адресная книга. Если пользователь вводит "s", приложение может использовать поиск VLV для поиска записей с общим именем, начинающимся с "s". Если пользователь добавляет "m" в "s", приложение может использовать другой поиск VLV для поиска записей с общим именем, начинающимся с "sm".

Чтобы выполнить поиск VLV, указать ADSI использовать элемент управления VLV. Для этого вызовите метод IDirectorySearch::SetSearchPreference с параметром поиска ADS_SEARCHPREF_VLV со значением ADSTYPE_PROV_SPECIFIC. Значение ADSTYPE_PROV_SPECIFIC — это указатель на структуру ADS_VLV, содержащую данные о поиске. Пример функции GetVLVItemCount показывает, как задать оба этих параметра поиска.

Все поиски VLV должны использовать сортировку результатов на стороне сервера, которая выполняется путем задания предпочтения ADS_SEARCHPREF_SORT_ON поиска. Дополнительные сведения о предпочтениях поиска ADS_SEARCHPREF_SORT_ON см. в разделе Сортировка результатов поиска с помощью IDirectorySearch.

При выполнении поиска VLV определенный объем метаданных о поиске возвращается в столбце, который извлекается путем вызова IDirectorySearch::GetColumn с идентификатором ADS_VLV_RESPONSE. Эти данные содержатся в ADS_VLV структуре. Особое значение имеют члены dwContentCount и lpContextID . Член dwContentCount будет содержать количество результатов, соответствующих критериям поиска VLV. Это значение можно использовать в качестве оценки общего количества элементов, возвращаемых для поиска этого типа. Элемент lpContextID содержит определяемое сервером значение, которое можно передать в следующий поиск, чтобы определить поиск. Использование lpContextID может повысить производительность поиска. Помните, что lpContextID — это определяемое сервером значение, а его длина содержится в элементе dwContextIDLength. Этот буфер освобождается при вызове метода IDirectorySearch::FreeColumn , поэтому вызывающий объект должен выделить буфер соответствующего размера и скопировать и сохранить содержимое буфера между поиском.

Дополнительные сведения об элементе управления LDAP VLV см. в статье "Поиск с помощью элемента управления LDAP VLV".

Дополнительные сведения см. в разделе:

• Получение количества элементов
• Поиск по смещениям
• Поиск по строке
• Пример кода для использования поиска VLV

Получение количества элементов

Чтобы получить оценку количества элементов, возвращаемых для определенного поиска, выполните следующие действия.

1. Заполните структуру ADS_VLV всеми нулевыми или NULL-значениями .

2. Заполните ADS_SEARCHPREF_INFO следующими значениями.

   • Задайте для элемента dwSearchPref значение ADS_SEARCHPREF_VLV.
   • Задайте для элемента vValue.dwType значение ADSTYPE_PROV_SPECIFIC.
   • Задайте для элемента vValue.ProviderSpecific.dwLength размер структуры ADS_VLV.
   • Задайте для члена vValue.ProviderSpecific.lpValue адрес структуры ADS_VLV из шага 1.

3. Заполните структуру ADS_SORTKEY , как показано в сортировке результатов поиска с помощью IDirectorySearch , чтобы сортировать нужный атрибут.

4. Заполните еще один ADS_SEARCHPREF_INFO, чтобы добавить структуру ADS_SORTKEY в параметры поиска, как показано в разделе "Сортировка результатов поиска с помощью IDirectorySearch".

5. Добавьте любые другие нужные параметры поиска и вызовите IDirectorySearch::SetSearchPreference , чтобы задать параметры поиска.

6. Выполните поиск с помощью IDirectorySearch::ExecuteSearch.

7. Получите первую строку результатов, вызвав IDirectorySearch::GetFirstRow.

8. Вызовите IDirectorySearch::GetColumn с ADS_VLV_RESPONSE , чтобы получить метаданные поиска VLV.

9. Приведение pADsValues-ProviderSpecific.lpValue> структуры ADS_SEARCH_COLUMN к указателю ADS_VLV структуры. Элемент dwContentCount этой структуры ADS_VLV содержит приблизительное количество элементов, возвращаемых поиском этого типа.

10. Если другие поисковые запросы VLV того же типа будут выполнены, создайте копию данных lpContextID и сохраните ее для следующего поиска VLV.

В примере функции GetVLVItemCount показано, как это сделать.

Поиск по смещениям

Одним из способов быстрого поиска VLV является то, что можно искать определенный результат по числовой смещения. Например, если поиск приведет к возврату 10 000 элементов, поиск VLV позволяет получить сведения примерно для 4072-го элемента без необходимости извлекать все элементы перед вопросом.

Смещения указываются в качестве соотношения между смещением и числом содержимого. Коэффициенты полезны, так как сервер может не иметь точной оценки количества записей, существующих в списке, или размер списка может меняться в течение времени, когда пользователь просматривает его. Так как необходимо указать начало и конец списка, можно использовать предполагаемое значение для количества содержимого в первом запросе поиска, а также значение смещения. Сервер использует эти данные для вычисления соответствующих смещения в списке на основе его идеи количества контента, который отправляется в ответ на клиент через член dwContentCount структуры ADS_VLV. Например, если вы оцениваете размер списка равным 3000, а смещение должно быть записью 1500, то присвойте dwContentCount значение 3000 и dwOffset значение 1500. Если сервер оценивает фактический размер списка 4500, он перерасчитывает смещение до 2250 и возвращает новые оценки в dwContentCount и dwOffset.

Примечание.

Все числовые значения в поиске VLV являются приблизителями и не должны использоваться для абсолютных значений. Например, если вы выдаете VLV-запрос на 50-й элемент в норме 100, вы не гарантируете получение точного промежуточного элемента.

Чтобы выполнить поиск определенного элемента по смещениям, выполните следующие действия.

1. Заполните структуру ADS_VLV следующими значениями. Дополнительные члены структуры должны иметь значение null или NULL.

   • Задайте для элемента dwContentCount максимальное значение соотношения элементов для получения.
   • Задайте для элемента dwOffset отношение, относительно dwContentCount, элемента или элементов для извлечения.
   • Присвойте элементу lpContextID адрес копии буфера идентификатора контекста и dwContextIDLength длину в байтах буфера идентификатора контекста. Если идентификатор контекста не сохранен, оба этих элемента должны быть равны нулю или NULL.

2. Задайте параметры поиска, как показано на шагах 2–5 процедуры получения количества элементов.

3. Выполните поиск с помощью IDirectorySearch::ExecuteSearch.

4. Получите первую строку результатов, вызвав IDirectorySearch::GetFirstRow.

5. Вызовите IDirectorySearch::GetColumn с именем атрибута, чтобы получить фактические данные для запрошенного элемента.

6. Вызовите IDirectorySearch::GetColumn с ADS_VLV_RESPONSE , чтобы получить метаданные поиска VLV.

7. Приведение pADsValues-ProviderSpecific.lpValue> структуры ADS_SEARCH_COLUMN к указателю ADS_VLV структуры.

8. Создайте копию данных lpContextID и сохраните ее для следующего поиска VLV.

 

В примере функции GetVLVItemText показано, как это сделать.

Кроме того, можно получить несколько строк данных с одним вызовом поиска. Это делается на шаге 1 путем задания элементов dwBeforeCount и dwAfterCount структуры ADS_VLV соответствующим образом. Элемент dwBeforeCount содержит количество элементов, которые отображаются в списке до указанного элемента, а элемент dwAfterCount содержит количество элементов, которые отображаются в списке после того, как элемент в вопросе. Оба этих счетчика исключают сам элемент, поэтому при задании dwBeforeCount значение 10 и dwAfterCount до 10 возвращается в общей сложности 21 элементов. Этот параметр позволяет кэширование результатов поиска на стороне клиента.

Поиск по строке

Также можно использовать поиск VLV для поиска элементов, имеющих строковый атрибут, значение которого соответствует всем или части строки без необходимости извлекать все элементы. Сопоставление строк выполняется с атрибутом, указанным в структуре ADS_SORTKEY предпочтения поиска ADS_SEARCHPREF_SORT_ON.

Чтобы найти конкретный элемент по строке, выполните следующие действия.

1. Заполните структуру ADS_VLV следующими значениями. Дополнительные члены структуры должны иметь значение null или NULL.

   • Присвойте элементу pszTarget указатель на строку, завершающую значение NULL, содержащую строку для поиска.
   • Присвойте элементу lpContextID адрес копии буфера идентификатора контекста и dwContextIDLength длину в байтах буфера идентификатора контекста. Если идентификатор контекста не сохранен, оба этих элемента должны быть равны нулю или NULL.

2. Задайте параметры поиска, как показано на шагах 2–5 процедуры получения количества элементов.

3. Выполните поиск с помощью IDirectorySearch::ExecuteSearch.

4. Получите первую строку результатов, вызвав IDirectorySearch::GetFirstRow.

5. Вызовите IDirectorySearch::GetColumn с именем атрибута, чтобы получить фактические данные для запрошенного элемента.

6. Вызовите IDirectorySearch::GetColumn с ADS_VLV_RESPONSE , чтобы получить метаданные поиска VLV.

7. Приведение pADsValues-ProviderSpecific.lpValue> структуры ADS_SEARCH_COLUMN к указателю ADS_VLV структуры.

8. Создайте копию данных lpContextID и сохраните ее для следующего поиска VLV. При необходимости элемент dwOffset содержит одноуровневый индекс первого элемента, строковый атрибут которого начинается со значения, указанного в pszTarget.

В примере функции GetVLVItemsByString показано, как это сделать.

Аналогично поиску по индексу, также можно получить несколько строк данных с одним вызовом поиска. Это достигается таким же образом, задав члены dwBeforeCount и dwAfterCount структуры ADS_VLV соответствующим образом.