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

Статья
08/27/2023

Функция ldap_init инициализирует сеанс с сервером LDAP.

Синтаксис

WINLDAPAPI LDAP *LDAPAPI ldap_init(
  [in] PSTR  HostName,
  [in] ULONG PortNumber
);

Параметры

[in] HostName

Указатель на строку, завершающуюся значением NULL, которая содержит доменное имя, или разделенный пробелами список имен узлов или пунктирные строки, представляющие IP-адрес узлов, на которых выполняется подключение к серверу LDAP. Каждое имя узла в списке может содержать необязательный номер порта, который отделен от самого узла двоеточием (:). Дополнительные сведения об использовании параметра LDAP_OPT_AREC_EXCLUSIVE при подключении к серверам Active Directory см. в разделе Примечания.

[in] PortNumber

Содержит номер TCP-порта, к которому нужно подключиться. Задайте значение LDAP_PORT , чтобы получить порт по умолчанию 389. Этот параметр игнорируется, если имя узла содержит номер порта.

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

Если функция выполняется успешно, она возвращает дескриптор сеанса в виде указателя на структуру данных LDAP . Дескриптор сеанса должен быть освобожден с помощью вызова ldap_unbind , когда он больше не требуется.

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

Вызовите ldap_init , чтобы создать блок подключения к серверу LDAP. В отличие от ldap_open, вызов ldap_init не открывает подключение. Вы можете вызвать ldap_connect явным образом, чтобы библиотека связалась с сервером. Это полезно, если требуется указать локальное время ожидания, и в этом случае необходимо вызвать ldap_set_option с блоком подключения из ldap_init, прежде чем вызывать ldap_connect. Однако обычно этот вызов не требуется, так как первая функция операции, требующая открытого подключения, ldap_connect внутренне, если она не была вызвана.

Функция выделяет структуру данных LDAP для хранения данных о состоянии для сеанса и возвращает дескриптор этой структуре. Передайте этот дескриптор в вызовы функций LDAP во время сеанса.

Параметр HostName может иметь значение NULL. В этом случае во время выполнения выполняется попытка найти сервер LDAP по умолчанию. При вызове ldap_connect узлы пытаются выполнить в указанном порядке, останавливаясь при первом успешном подключении. Для серверов Active Directory можно использовать функцию DsGetDcName , чтобы получить имя сервера, которое затем можно передать в качестве параметра HostName вместо null.

Даже если функция ldap_set_option используется для задания параметра LDAP_OPT_GETDSNAME_FLAGS , который, в свою очередь, задает флаги, которые будут переданы в DsGetDCName для определения контроллера домена для подключения. Клиент LDAP также передает флаг DS_ONLY_LDAP_NEEDEDв DsGetDCName в дополнение к флагам, которые LDAP_OPT_GETDSNAME_FLAGS указывает.

Если параметру HostName передается значение NULL, а вызывающий компьютер является членом домена Active Directory, среда выполнения будет искать контроллер домена в домене, членом которого является текущий компьютер, при попытке подключения.

Если для параметра HostNameпередано значение NULL, а вызывающий компьютер является контроллером домена Active Directory, среда выполнения переключит значение NULL с 127.0.0.1 и подключится к локальному компьютеру с помощью замыкания на себя при попытке подключения.

Если для параметра HostName передается доменное имя Active Directory, то ldap_init найдет в этом домене сервер LDAP по умолчанию.

Если для параметра HostName задано значение NULL или доменное имя, применяется автоматическое повторное подключение. Если подключенный контроллер домена по какой-либо причине перестает работать в течение времени существования подключения, LDAP автоматически повторно подключится к другому контроллеру домена в указанном домене. Это поведение можно отключить или включить с помощью параметра сеанса LDAP_OPT_AUTO_RECONNECT , который включен по умолчанию.

Если для параметра HostName передается имя DNS-сервера Active Directory, необходимо вызвать ldap_set_option , чтобы установить флаг LDAP_OPT_AREC_EXCLUSIVE перед вызовом любой функции LDAP, создающей фактическое подключение. Это приводит к принудительному поиску записи A и обхода любого поиска записи SRV при разрешении имени узла. В случае филиала с коммутируемым подключением использование поиска A-Record может избежать принудительного запроса удаленного DNS-сервера для записи SRV при разрешении имен.

Если номер порта глобального каталога передается ldap_init в качестве одного из аргументов, то имя узла , переданное для этого номера порта, должно быть именем леса для базового вызова DsGetDcName(), чтобы правильно найти сборку мусора в предприятии.

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

Обратите вниманиеldap_init является предпочтительным методом инициализации сеанса LDAP. Использование ldap_open является в значительной степени нерекомендуемым в текущем RFC LDAP, так как это исключает использование настройки параметров сеанса.

Требования

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