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

Статья
03/16/2023

Функция ldap_search_st синхронно выполняет поиск в каталоге LDAP и возвращает запрошенный набор атрибутов для каждой совпадаемой записи. Дополнительный параметр задает локальное время ожидания для поиска. Функция идентична ldap_search_s, за исключением дополнительного параметра локального времени ожидания.

Синтаксис

WINLDAPAPI ULONG LDAPAPI ldap_search_st(
  [in]  LDAP         *ld,
  [in]  PSTR         base,
  [in]  ULONG        scope,
  [in]  PSTR         filter,
  [in]  PZPSTR       attrs,
  [in]  ULONG        attrsonly,
  [in]  l_timeval    *timeout,
  [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] timeout

Значение времени ожидания локального поиска в секундах.

[out] res

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

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

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

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

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

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

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

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

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

// Perform the search request.
dwErr = ldap_search_st (i_pldap,
        i_lpszBase,
        i_ulScope,
        i_lpszSearchFilter,
        lpszAttributes,
        0,
        lpsTimeout,
        &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_st"));
    hr = HRESULT_FROM_WIN32(dwErr);

    // Be aware that pMsg can contain valid data, even if the
    // call to ldap_search_st 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 just 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