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

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

Синтаксис

DSGETDCAPI DWORD DsGetDcNameW(
  [in]  LPCWSTR                  ComputerName,
  [in]  LPCWSTR                  DomainName,
  [in]  GUID                     *DomainGuid,
  [in]  LPCWSTR                  SiteName,
  [in]  ULONG                    Flags,
  [out] PDOMAIN_CONTROLLER_INFOW *DomainControllerInfo
);

Параметры

[in] ComputerName

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

[in] DomainName

Указатель на строку, завершающуюся нулевым значением, которая указывает имя домена или секции приложения для запроса. Это может быть имя в стиле DNS, например fabrikam.com, или имя в плоском стиле, например Fabrikam. Если указано имя стиля DNS, оно может быть указано с конечным периодом или без нее.

Если параметр Flags содержит флаг DS_GC_SERVER_REQUIRED , domainName должно быть именем леса. В этом случае dsGetDcName завершается сбоем, если DomainName указывает имя, которое не является корнем леса.

Если параметр Flags содержит флаг DS_GC_SERVER_REQUIRED , а domainName имеет значение NULL, DsGetDcName пытается найти глобальный каталог в лесу компьютера, определяемого именем компьютера, который является локальным компьютером, если ComputerName имеет значение NULL.

Если параметр DomainName имеет значение NULL , а параметр Flags не содержит флаг DS_GC_SERVER_REQUIRED , то для параметра ComputerName устанавливается доменное имя по умолчанию основного домена компьютера, определяемого параметром ComputerName.

[in] DomainGuid

Указатель на структуру GUID , указывающую GUID запрашиваемого домена. Если значение DomainGuid не равно NULL и не удается найти домен, указанный в параметре DomainName или ComputerName , DsGetDcName пытается найти контроллер домена в домене с идентификатором GUID, указанным в DomainGuid.

[in] SiteName

Указатель на строку, завершающуюся нулевым значением, которая указывает имя сайта, на котором должен физически существовать возвращенный контроллер домена. Если этот параметр имеет значение NULL, DsGetDcName пытается вернуть контроллер домена на сайте, ближайшем к сайту компьютера, указанному параметром ComputerName. По умолчанию этот параметр должен иметь значение NULL.

[in] Flags

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

DS_AVOID_SELF

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

DS_BACKGROUND_ONLY

Если флаг DS_FORCE_REDISCOVERY не указан, эта функция использует кэшированные данные контроллера домена. Если кэшированные данные устарели более 15 минут, кэш обновляется путем проверки связи с контроллером домена. Если этот флаг указан, обновление не выполняется, даже если срок действия кэшированных данных истек. Этот флаг следует использовать, если функция DsGetDcName вызывается периодически.

DS_DIRECTORY_SERVICE_PREFERRED

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

DS_DIRECTORY_SERVICE_REQUIRED

Требует, чтобы возвращенный контроллер домена поддерживал службы каталогов.

DS_DIRECTORY_SERVICE_6_REQUIRED

Требуется, чтобы возвращенный контроллер домена работал под управлением Windows Server 2008 или более поздней версии.

DS_DIRECTORY_SERVICE_8_REQUIRED

Требует, чтобы возвращенный контроллер домена работал Windows Server 2012 или более поздней версии.

DS_FORCE_REDISCOVERY

Принудительно игнорирует кэшированные данные контроллера домена. Если флаг DS_FORCE_REDISCOVERY не указан, DsGetDcName может возвращать кэшированные данные контроллера домена. Если этот флаг указан, DsGetDcName не будет использовать кэшированные сведения (если таковые существуют), а выполняет обнаружение нового контроллера домена.

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

DS_GC_SERVER_REQUIRED

Требует, чтобы возвращенный контроллер домена был сервером глобального каталога для леса доменов, в котором данный домен является корневым. Если этот флаг установлен и параметр DomainName не равен NULL, domainName должен указать имя леса. Этот флаг нельзя сочетать с флагами DS_PDC_REQUIRED или DS_KDC_REQUIRED .

DS_GOOD_TIMESERV_PREFERRED

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

DS_IP_REQUIRED

Этот параметр указывает, что контроллер домена должен иметь IP-адрес. В этом случае DsGetDcName поместит ip-адрес протокола контроллера домена в элемент DomainControllerAddressобъекта DomainControllerInfo.

DS_IS_DNS_NAME

Указывает, что параметр DomainName является DNS-именем. Этот флаг нельзя объединить с флагом DS_IS_FLAT_NAME .

Укажите DS_IS_DNS_NAME или DS_IS_FLAT_NAME. Если не указан ни флаг, dsGetDcName может занять больше времени для поиска контроллера домена, так как ему может потребоваться поиск как в стиле DNS, так и по неструктурированному имени.

DS_IS_FLAT_NAME

Указывает, что параметр DomainName является неструктурированным именем. Этот флаг нельзя сочетать с флагом DS_IS_DNS_NAME .

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_KDC_REQUIRED или DS_GC_SERVER_REQUIRED .

DS_RETURN_DNS_NAME

Указывает, что имена, возвращаемые в элементах DomainControllerName и DomainNameобъекта DomainControllerInfo , должны быть DNS-именами. Если DNS-имя недоступно, возвращается ошибка. Этот флаг нельзя указать с помощью флага DS_RETURN_FLAT_NAME . Этот флаг подразумевает флаг DS_IP_REQUIRED .

DS_RETURN_FLAT_NAME

Указывает, что имена, возвращаемые в элементах DomainControllerName и DomainNameобъекта DomainControllerInfo , должны быть неструктурированными именами. Если неструктурированное имя недоступно, возвращается ошибка. Этот флаг нельзя указать с помощью флага DS_RETURN_DNS_NAME .

DS_TIMESERV_REQUIRED

Требует, чтобы на возвращенном контроллере домена в данный момент была запущена служба времени Windows.

DS_TRY_NEXTCLOSEST_SITE

Если этот флаг указан, DsGetDcName пытается найти контроллер домена на том же сайте, что и вызывающий объект. Если такой контроллер домена не найден, он найдет контроллер домена, который может предоставить сведения о топологии, и вызовет DsBindToISTG для получения дескриптора привязки, а затем вызовет DsQuerySitesByCost через UDP, чтобы определить "следующий ближайший сайт", и, наконец, кэширует имя найденного сайта. Если контроллер домена не найден на этом сайте, dsGetDcName возвращается к методу по умолчанию для поиска контроллера домена.

Если этот флаг используется в сочетании со значением, отличным от NULL, во входном параметре SiteName, возникает ERROR_INVALID_FLAGS .

Кроме того, тип поиска, используемый с DS_TRY_NEXT_CLOSEST_SITE , зависит от сайта, поэтому этот флаг игнорируется, если он используется в сочетании с DS_PDC_REQUIRED. Наконец, DS_TRY_NEXTCLOSEST_SITE игнорируется при использовании в сочетании с DS_RETURN_FLAT_NAME так как для разрешения имени используется NetBIOS, но домен найденного контроллера домена не обязательно соответствует домену, к которому присоединен клиент.

DS_WRITABLE_REQUIRED

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

DS_WEB_SERVICE_REQUIRED

Требует, чтобы возвращенный контроллер домена в настоящее время работал под управлением веб-службы Active Directory.

[out] DomainControllerInfo

Указатель на значение PDOMAIN_CONTROLLER_INFO , которое получает указатель на структуру DOMAIN_CONTROLLER_INFO , содержащую данные о выбранном контроллере домена. Эта структура выделяется с помощью DsGetDcName. Вызывающий объект должен освободить структуру с помощью функции NetApiBufferFree , если она больше не требуется.

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

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

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

Комментарии

Функция DsGetDcName отправляется в службу Netlogon на удаленном компьютере, указанном в параметре ComputerName. Если аргумент ComputerName имеет значение NULL, функция обрабатывается на локальном компьютере.

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

DsGetDcName не требует определенного доступа к указанному домену. По умолчанию эта функция не гарантирует доступность возвращенного контроллера домена. Вместо этого вызывающий объект должен попытаться использовать возвращенный контроллер домена. Если контроллер домена недоступен, вызывающий объект должен снова вызвать функцию DsGetDcName , указав флаг DS_FORCE_REDISCOVERY .

Время отклика

При использовании DsGetDcName следует учитывать следующие сведения о времени:

• DsGetDcName выполняет сетевые вызовы и может занять от нескольких секунд до одной минуты в зависимости от сетевого трафика, топологии, нагрузки на контроллер домена и т. д.
• Не рекомендуется вызывать DsGetDcName из пользовательского интерфейса или другого критического потока времени.
• Указатель контроллера домена использует оптимизированную логику для предоставления сведений о контроллере домена как можно быстрее. Он также использует кэшированные сведения на сайте для связи с ближайшим контроллером домена.

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

В доменные службы Active Directory функция указателя контроллера домена разработана таким образом, чтобы после того, как клиент нашел предпочтительный контроллер домена, клиент не будет искать другой контроллер домена, если этот контроллер домена не перестанет отвечать или клиент не перезапустится. Это называется "Залипание контроллера домена". Так как рабочие станции обычно работают в течение нескольких месяцев без проблем или перезапуска, одним из непредвиденных последствий этого поведения является то, что если определенный контроллер домена выходит из строя для обслуживания, все клиенты, подключенные к нему, переносят свои подключения на другой контроллер домена. Но при резервном копировании контроллера домена клиенты никогда не подключались к нему повторно, так как клиенты не перезапускаются очень часто. Это может привести к проблемам с балансировкой нагрузки.

Ранее наиболее распространенным решением этой проблемы было развертывание скрипта на каждом клиентском компьютере, который периодически вызывал DsGetDcName с помощью флага DS_FORCE_REDISCOVERY . Это было несколько громоздким решением, поэтому в Windows Server 2008 и Windows Vista появился новый механизм, который вызвал проблемы с залипанием контроллера домена.

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

HKEY_LOCAL_MACHINE\СИСТЕМЫ\CurrentControlSet\Услуги\Netlogon\Параметры\ForceRediscoveryInterval

и

HKEY_LOCAL_MACHINE\Программного обеспечения\Политики\Microsoft\Netlogon\Параметры\ForceRediscoveryInterval

Значения в этих разделах реестра относятся к типу REG_DWORD. Они указывают продолжительность в секундах, прежде чем DsGetDcName попытается повторно обнаружить имя контроллера домена. Значение по умолчанию — 43200 секунд (12 часов). Если значение записи реестра ForceRediscoveryInterval равно 0, клиент всегда выполняет повторное обнаружение. Если задано значение 4294967295, срок действия кэша никогда не истекает, и кэшированный контроллер домена продолжает использоваться. Не рекомендуется задавать для записи реестра ForceRediscoveryInterval значение меньше 3600 секунд (60 минут).

Обратите внимание, что если указан флаг DS_BACKGROUND_ONLY , DsGetDcName никогда не будет пытаться повторно обнаружить имя контроллера домена, так как этот флаг заключается в том, чтобы заставить DsGetDcName использовать кэшированное имя контроллера домена, даже если срок его действия истек.

Трассировка трассировки событий Windows в DsGetDcName

Чтобы включить трассировку трассировки событий Windows для DsGetDcName, создайте следующий раздел реестра:

HKEY_LOCAL_MACHINE\Системы\CurrentControlSet\Услуги\DCLocator\Трассировки

Ключ будет иметь следующую структуру:

String ProcessName
  DWORD  PID <optional>

ProcessName должно быть полным именем, включая расширение процесса, для которого требуется получить сведения трассировки. PID требуется только в том случае, если существует несколько процессов с одинаковым именем. Если он определен, для трассировки будет включен только процесс с этим PID. Невозможно отследить только 2 из 3 (или более) процессов с одинаковым именем. Вы можете включить один или все экземпляры (если существует несколько экземпляров с одним именем процесса и piD не указан, все экземпляры будут включены для трассировки).

Например, будет выполняться трассировка всех экземпляров App1.exe и App2.exe, но только экземпляра App3.exe с ИДЕНТИФИКАТОРом 999:

App1.exe 
App2.exe
App3.exe
     PID 999

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

tracelog.exe -start <sessionname> -guid #cfaa5446-c6c4-4f5c-866f-31c9b55b962d -f <имя> файла -flag <traceFlags>

sessionname — это имя, заданное для сеанса трассировки. Guid поставщика трассировки DCLocator — cfaa5446-c6c4-4f5c-866f-31c9b55b962d. filename — это имя файла журнала, в который записываются события. traceFlags — это один или несколько из следующих флагов, которые означают, какие области необходимо отследить:

Flag	Шестнадцатеричное значение	Описание
DCLOCATOR_MISC	0x00000002	Прочие отладки
DCLOCATOR_MAILSLOT	0x00000010	Сообщения почтового слоя
DCLOCATOR_SITE	0x00000020	Сайты
DCLOCATOR_CRITICAL	0x00000100	Важные ошибки
DCLOCATOR_SESSION_SETUP	0x00000200	Обслуживание доверенного домена
DCLOCATOR_DNS	0x00004000	Регистрация имени
DCLOCATOR_DNS_MORE	0x00020000	Регистрация подробного имени
DCLOCATOR_MAILBOX_TEXT	0x02000000	Подробные сообщения почтового ящика
DCLOCATOR_SITE_MORE	0x08000000	Подробные сайты

 

Выполните следующую команду, чтобы остановить сеанс трассировки:

tracelog.exe -stop <sessionname>

имя_сеанса совпадает с именем, которое использовалось при запуске сеанса.

Требования

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

См. также раздел

DOMAIN_CONTROLLER_INFO

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

DsGetSiteName

DsValidateSubnetName

GUID

NetApiBufferFree

Служба времени Windows