Структура LDAPVLVInfo (winldap.h)

Статья
08/27/2023

Структура LDAPVLVInfo используется для настройки параметров поиска для элемента управления запросами представления виртуального списка (VLV) (LDAP_CONTROL_VLVREQUEST).

Структура LDAPVLVInfo также может использоваться приложениями для управления данными о состоянии, связанными с рядом взаимодействий клиента и сервера VLV.

Синтаксис

typedef struct ldapvlvinfo {
  int     ldvlv_version;
  ULONG   ldvlv_before_count;
  ULONG   ldvlv_after_count;
  ULONG   ldvlv_offset;
  ULONG   ldvlv_count;
  PBERVAL ldvlv_attrvalue;
  PBERVAL ldvlv_context;
  VOID    *ldvlv_extradata;
} LDAPVLVInfo, *PLDAPVLVInfo;

Члены

ldvlv_version

Определяет версию структуры LDAPVLVInfo . Всегда должно быть задано значение LDAP_VLVINFO_VERSION (1).

ldvlv_before_count

Определяет количество записей перед целевой записью, которую клиент хочет, чтобы сервер отправил обратно в результатах списка. Это поле соответствует элементу beforeCount элемента управления LDAP_CONTROL_VLVREQUEST в кодировке BER.

ldvlv_after_count

Указывает количество записей после целевой записи, которую клиент указывает серверу отправить обратно в результатах списка. Это поле соответствует элементу afterCount элемента управления LDAP_CONTROL_VLVREQUEST в кодировке BER.

ldvlv_offset

Указывает соотношение между значением смещения и количеством содержимого. Например, подумайте, перетаскивает ли пользователь полосу прокрутки для просмотра записей в середине списка. Если клиент считает, что весь список содержит 100 записей, то для просмотра среднего списка он вычисляет смещение как 50, поэтому клиент отправляет это значение смещения со 100 в качестве количества содержимого, отправленного в элементе ldvlv_count , на сервер. Когда сервер получает эти данные, он может фактически вычислить количество содержимого в 500, поэтому он вычисляет смещение для поиска целевого объекта, запрошенного клиентом, по следующей формуле:

Si = Sc * (Ci /Cc)

where

Si — фактическое смещение списка, используемое сервером.

Sc — это оценка сервера для количества содержимого.

Ci — это смещение, отправленное клиентом.

Копия — это количество содержимого, отправленного клиентом.

Если клиент использует значение смещения 1, это означает, что целевой объект является первой записью в списке. Если клиент использует значение смещения, равное ldvlv_count, то элемент является последней записью в списке. Смещение будет равно нулю (0), если ldvlv_count равно нулю, что будет последней записью в списке.

Смещения используются только в том случае, если поиск не основан на значении атрибута, поэтому ldvlv_attrvalue должно иметь значение NULL. Это поле соответствует элементу offset в элементе управления LDAP_CONTROL_VLVREQUEST в кодировке BER.

ldvlv_count

Указывает количество содержимого списка. Оценка количества содержимого отправляется клиентом на сервер при отправке поискового запроса, чтобы сервер мог вычислить значение смещения. Сервер возвращает клиенту собственное вычисление количества содержимого в ответе. Если клиент не имеет оценки количества содержимого, он отправляет ноль (0), что означает, что сервер должен использовать собственную оценку для количества содержимого. Этот элемент используется с ldvlv_offset. Так как количество содержимого требуется только в том случае, если поиск не основан на значении атрибута, элемент ldvlv_attrvalue должен иметь значение NULL. Это поле соответствует элементу contentCount в элементе управления LDAP_CONTROL_VLVREQUEST в кодировке BER и элементу contentCount в элементе управления LDAP_CONTROL_VLVRESPONSE в кодировке BER.

ldvlv_attrvalue

Предоставляет значение атрибута в качестве целевой записи для поиска. Сервер сравнивает этот элемент со значениями, имеющими тот же тип атрибута, как указано в элементе sk_attrtype структуры LDAPSortKey . Если используется смещение, этот элемент должен иметь значение NULL. Этот элемент соответствует элементу assertionValue элемента управления LDAP_CONTROL_VLVREQUEST в кодировке BER.

ldvlv_context

Предоставляет идентификатор контекста, назначенный сервером для идентификации этой операции поиска. Это непрозрачный файл cookie, используемый сервером для внутреннего отслеживания текущей операции VLV. При первом вызове операции поиска с помощью элемента управления VLV этот параметр должен иметь значение NULL. Сервер может вернуть значение в LDAP_CONTROL_VLVRESPONSE сообщении. Это значение "cookie" должно быть возвращено серверу при следующем вызове функции поиска, выполняемой для определенного списка VLV.

ldvlv_extradata

Это поле зарезервировано для конкретного приложения и не используется функцией ldap_create_vlv_control ; он не влияет на создаваемый элемент управления.

Существует два метода вычисления целевого объекта поиска VLV: с помощью значения атрибута или с помощью смещения. Различные элементы этой структуры будут использоваться в зависимости от выбранного типа поиска. Оба метода требуют ввода значений для членов ldvlv_before_count и ldvlv_after_count . Укажите количество содержимого списка в ldvlv_count или, если вы не знаете это значение, используйте ноль (0), чтобы сервер вычислил его.

Поиск со значениями атрибутов
Чтобы выполнить поиск на основе значений, например, если вы хотите найти Джеффа Смита и знаете тип атрибута для этого значения, задайте тип атрибута в sk_attrtype член структуры LDAPSortKey и значение атрибута в ldvlv_attrvalue. Элемент ldvlv_offset игнорируется для этого типа поиска, поэтому задавать его необязательно.

Например, чтобы выполнить поиск с помощью буквы J. Чтобы получить 20 результатов, задайте для ldvlv_before_count значение 9, ldvlv_after_count — 10, а ldvlv_attrvalue — J. Сервер находит первую запись в списке, которая не меньше J, например Джеффа Смита, и возвращает девять предыдущих записей, целевую запись и 10 записей. Сервер вернет ldvlv_count 30 000 и ldvlv_offset 4053 в элементе управления LDAP_CONTROL_VLVRESPONSE ; это предполагает, что Джефф Смит является записью номер 4053 в списке. Сервер может вернуть несколько записей, чем запрошено до и (или) после целевой записи, если в списке недостаточно записей для удовлетворения запроса. Например, если до первой записи "J" было всего две записи, сервер не мог вернуть девять предыдущих записей.
Поиск со смещениями
Чтобы использовать смещения для поиска, задайте смещение в ldvlv_offset и задайте для ldvlv_attrvalueзначение NULL. Также задайте тип атрибута в элементе sk_attrtypeLDAPSortKey, но на этот раз целевой объект будет смещением в списке записей для этого типа атрибута, а не конкретным значением атрибута.

Например, для назначения поиска 68 процентов списка результатов поиска. Если ldvlv_count составляет 30 000, то 68 процентов 30000 — 20400. Чтобы получить 20 результатов, задайте для ldvlv_before_count значение 9, ldvlv_after_count — 10, ldvlv_count — 30000, ldvlv_offset — 20400 и отправьте запрос на сервер. Сервер возвращает предыдущие 20 записей в списке, а также ldvlv_count 30000 и ldvlv_offset 20400. Имейте в виду, что количество записей в списке может изменяться между оценкой количества записей клиентом и сервером, обрабатывающим поиск, что, в свою очередь, влияет на смещения. В этом случае возвращаемая целевая запись может быть не совсем целевой записью, ожидаемой клиентом. Приложения должны быть подготовлены для обработки этой неопределенности.

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

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista
Минимальная версия сервера	Windows Server 2008
Верхняя часть	winldap.h