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

Статья
03/04/2024

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

Синтаксис

WINLDAPAPI ULONG LDAPAPI ldap_search_s(
  [in]  LDAP         *ld,
  [in]  PSTR         base,
  [in]  ULONG        scope,
  [in]  PSTR         filter,
  [in]  PZPSTR       attrs,
  [in]  ULONG        attrsonly,
  [out] PLDAPMessage *res
);

Параметры

[in] ld

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

[in] base

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

[in] scope

Указывает одно из следующих значений для указания область поиска.

LDAP_SCOPE_BASE

Выполните поиск только по базовой записи.

LDAP_SCOPE_ONELEVEL

Выполните поиск всех записей на первом уровне под базовой записью, за исключением базовой записи.

LDAP_SCOPE_SUBTREE

Выполните поиск базовой записи и всех записей в дереве под основанием.

[in] filter

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

[in] attrs

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

[in] attrsonly

Логическое значение, которое должно быть равно нулю, если возвращаются как типы атрибутов, так и значения, не равное нулю, если требуются только типы.

[out] res

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

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

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

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

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

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

Многопоточность. Вызовы к ldap_search_s являются потокобезопасны.

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

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

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

    // Be aware that pMsg can contain valid data, even if the
    // call to ldap_search_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 just frees pMsg on any 
    // error code.

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

else
{
    // Process the search results.
    ...
    // Free the results when no longer required.
    if (pMsg != NULL) ldap_msgfree(pMsg);
}

Требования

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