Функция DsGetDcOpenA (dsgetdc.h)

Статья
11/20/2024

Функция DsGetDcOpen открывает новую операцию перечисления контроллера домена.

Синтаксис

DSGETDCAPI DWORD DsGetDcOpenA(
  [in]           LPCSTR  DnsName,
  [in]           ULONG   OptionFlags,
  [in, optional] LPCSTR  SiteName,
  [in, optional] GUID    *DomainGuid,
  [in, optional] LPCSTR  DnsForestName,
  [in]           ULONG   DcFlags,
  [out]          PHANDLE RetGetDcContext
);

Параметры

[in] DnsName

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

[in] OptionFlags

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

DS_ONLY_DO_SITE_NAME

Перечисляются только контроллеры домена, относящиеся к сайту.

DS_NOTIFY_AFTER_SITE_RECORDS

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

[in, optional] SiteName

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

[in, optional] DomainGuid

Указатель на значение GUID , содержащее идентификатор домена, указанного DnsName. Этот идентификатор используется для обработки дела переименованного домена. Если это значение указано и домен, указанный в DnsName переименован, эта функция пытается перечислить контроллеры домена в домене, который содержит указанный идентификатор. Этот параметр является необязательным и может быть NULL.

[in, optional] DnsForestName

Указатель на строку, завершающую значение NULL, содержащую имя леса, содержащего домен DnsName. Это значение используется в сочетании с DomainGuid для перечисления контроллеров домена, если домен был переименован. Этот параметр является необязательным и может быть NULL.

[in] DcFlags

Содержит набор флагов, определяющих тип контроллеров домена для перечисления. Это может быть ноль или сочетание одного или нескольких следующих значений.

DS_FORCE_REDISCOVERY

Принудительно игнорирует кэшированные данные контроллера домена. Если этот флаг не указан, dsGetDcOpen получает перечисление контроллера домена из кэшированных данных контроллера домена.

DS_GC_SERVER_REQUIRED

Требует, чтобы перечисленные контроллеры домена были глобальными серверами каталога для леса доменов с этим доменом в качестве корневого элемента. Этот флаг нельзя объединить с флагом DS_PDC_REQUIRED.

DS_KDC_REQUIRED

Требует, чтобы перечисленные контроллеры домена в настоящее время запускали службу Центра распространения ключей Kerberos. Этот флаг нельзя объединить с флагами DS_PDC_REQUIRED или DS_GC_SERVER_REQUIRED.

DS_ONLY_LDAP_NEEDED

Указывает, что перечисленные серверы являются серверами LDAP. Серверы не обязательно являются контроллерами домена. Другие службы не подразумеваются, что они присутствуют на каждом перечислении сервера. Серверы не обязательно имеют записываемый контейнер конфигурации, а также контейнер схемы записи. Серверы могут не обязательно использоваться для создания или изменения принципов безопасности. Этот флаг можно использовать с флагом DS_GC_SERVER_REQUIRED для перечисления серверов LDAP, на которых также размещен глобальный сервер каталога. В этом случае перечисленные серверы глобального каталога не обязательно являются контроллерами домена и другими службами, которые должны присутствовать на каждом сервере. Если этот флаг указан, DS_PDC_REQUIRED, DS_TIMESERV_REQUIRED, DS_GOOD_TIMESERV_PREFERRED, DS_DIRECTORY_SERVICES_PREFERED, DS_DIRECTORY_SERVICES_REQUIREDи флаги DS_KDC_REQUIRED игнорируются.

DS_PDC_REQUIRED

Требует, чтобы перечисленные контроллеры домена были основными контроллерами домена для домена. Этот флаг нельзя объединить с флагом DS_GC_SERVER_REQUIRED.

[out] RetGetDcContext

Указатель на значение HANDLE, которое получает дескриптор контекста перечисления контроллера домена. Этот дескриптор используется с функцией DsGetDcNext для идентификации операции перечисления контроллера домена. Этот дескриптор передается в dsGetDcClose, чтобы закрыть операцию перечисления контроллера домена.

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

Возвращает ERROR_SUCCESS, если ошибка Win32 или RPC успешно выполнена в противном случае. Возможные значения ошибок включают следующие значения.

Замечания

Заметка

Заголовок dsgetdc.h определяет DsGetDcOpen как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista
минимальный поддерживаемый сервер	Windows Server 2008
целевая платформа	Виндоус
заголовка	dsgetdc.h
библиотеки	Netapi32.lib
DLL	Netapi32.dll

См. также

функций службы каталогов

DsGetDcClose

DsGetDcNext

перечисление контроллеров домена

Поделиться через