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

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

ldap_open

ldap_set_option

ldap_unbind