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

Статья
08/27/2023

Функция ldap_search_ext_s синхронно выполняет поиск в каталоге LDAP и возвращает запрошенный набор атрибутов для каждой совпадаемой записи.

Синтаксис

WINLDAPAPI ULONG LDAPAPI ldap_search_ext_s(
  [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]  l_timeval     *timeout,
  [in]  ULONG         SizeLimit,
  [out] PLDAPMessage  *res
);

Параметры

[in] ld

Дескриптор сеанса.

[in] base

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

[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] timeout

Задает значение времени ожидания локального поиска (в секундах) и ограничение времени операции, отправляемое на сервер в поисковом запросе.

[in] SizeLimit

Ограничение на количество записей, возвращаемых из поиска. Нулевое значение указывает, что ограничений нет.

[out] res

Содержит результаты поиска после завершения вызова . Может также содержать частичные результаты или расширенные данные при сбое вызова функции с кодом ошибки. Бесплатные возвращаемые результаты с вызовом ldap_msgfree , когда приложение больше не требуется.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение будет LDAP_SUCCESS.

Если функция завершается сбоем, она возвращает код ошибки, однако ldap_search_ext_s может завершиться ошибкой и по-прежнему может выделить pMsg. Например, LDAP_PARTIAL_RESULTS и LDAP_REFERRAL код ошибки выделяет pMsg. Дополнительные сведения см. в следующем примере кода. Дополнительные сведения см. в разделе Возвращаемые значения.

Функция ldap_search_ext_s инициирует синхронную операцию поиска. Параметры и эффекты ldap_search_ext_s включают параметры ldap_search_s. Расширенная подпрограмма включает дополнительные параметры для поддержки клиентских и серверных элементов управления, а также для указания размера и ограничений времени для каждой операции поиска.

Используйте функцию ldap_set_option с дескриптором сеанса ld , чтобы задать параметр LDAP_OPT_DEREF , определяющий способ выполнения поиска. Дополнительные сведения см. в разделе Параметры сеанса. Два других параметра поиска, LDAP_OPT_SIZELIMIT и LDAP_OPT_TIMELIMIT, игнорируются в пользу параметров SizeLimit и TimeLimit в этой функции.

После завершения операции поиска ldap_search_ext_s возвращается вызывающей объекту. Используйте ldap_search_ext , чтобы выполнить операцию асинхронно.

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

В следующем примере кода показано, как освободить pMsg в случае сбоя ldap_search_ext_s .

// Initialize return value to NULL.
LDAPMessage *pMsg = NULL;

// Perform the search request.
dwErr = ldap_search_ext_s (i_pldap,
        i_lpszBase,
        i_ulScope,
        i_lpszSearchFilter,
        lpszAttributes,
        0,
        pServerControls,
        pClientControls,
        lpsTimeout,
        0,
        &pMsg
        );

// Cleanup calling parameters.
if (lpszAttributes != NULL)
    delete [] lpszAttributes;

// Convert error code and cleanup pMsg if necessary.
if (dwErr != LDAP_SUCCESS)
{
    DebugOutLDAPError(i_pldap, dwErr, _T("ldap_search_ext_s"));
    hr = HRESULT_FROM_WIN32(dwErr);

    // Be aware that pMsg can contain valid data, even if
    // the call to ldap_search_ext_s returned an error code.
    // This can be caused by the server returning codes
    // such as LDAP_RESULTS_TOO_LARGE or other codes
    // that indicate that the search returned partial
    // results. The user code can handle these cases
    // if required, this example frees pMsg on any 
    // error code.

    if (pMsg != NULL) ldap_msgfree(pMsg);
}

else
{
    // Process the search results.
    ...
    // Free the results when complete.
    if (pMsg != NULL) ldap_msgfree(pMsg);

}

Требования

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