функция ldap_search_ext (winldap.h)

Статья
08/27/2023

Функция 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

Указатель на строку, завершающуюся нулевым значением, которая содержит различающееся имя записи, с которой начинается поиск.

[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 value , описанному в разделе Параметры сеанса, сервер должен игнорировать элемент управления , так как запрос может быть удовлетворен на одной странице. Если сервер не поддерживает этот элемент управления, сервер должен вернуть ошибку неподдерживаемого критического расширения, если клиент запросил его как критическое, в противном случае сервер должен игнорировать элемент управления. В оставшейся части этого раздела предполагается, что сервер не игнорирует выгружаемую клиентом элемент управления результатами.

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

Многопоточность. Вызовы ldap_search_ext потокобезопасны.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista
Минимальная версия сервера	Windows Server 2008
Целевая платформа	Windows
Header	winldap.h
Библиотека	Wldap32.lib
DLL	Wldap32.dll