Función DsGetDcNameW (dsgetdc.h)

Artículo
08/23/2023

La función DsGetDcName devuelve el nombre de un controlador de dominio en un dominio especificado. Esta función acepta criterios de selección de controladores de dominio adicionales para indicar la preferencia de un controlador de dominio con características concretas.

Sintaxis

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

Parámetros

[in] ComputerName

Puntero a una cadena terminada en null que especifica el nombre del servidor para procesar esta función. Normalmente, este parámetro es NULL, que indica que se usa el equipo local.

[in] DomainName

Puntero a una cadena terminada en null que especifica el nombre del dominio o la partición de aplicación que se va a consultar. Este nombre puede ser un nombre de estilo DNS, por ejemplo, fabrikam.com o un nombre de estilo plano, por ejemplo, Fabrikam. Si se especifica un nombre de estilo DNS, el nombre se puede especificar con o sin un punto final.

Si el parámetro Flags contiene la marca DS_GC_SERVER_REQUIRED , DomainName debe ser el nombre del bosque. En este caso, DsGetDcName produce un error si DomainName especifica un nombre que no es la raíz del bosque.

Si el parámetro Flags contiene la marca DS_GC_SERVER_REQUIRED y DomainName es NULL, DsGetDcName intenta buscar un catálogo global en el bosque del equipo identificado por ComputerName, que es el equipo local si ComputerName es NULL.

Si DomainName es NULL y el parámetro Flags no contiene la marca DS_GC_SERVER_REQUIRED , ComputerName se establece en el nombre de dominio predeterminado del dominio principal del equipo identificado por ComputerName.

[in] DomainGuid

Puntero a una estructura GUID que especifica el GUID del dominio consultado. Si DomainGuid no es NULL y no se encuentra el dominio especificado por DomainName o ComputerName , DsGetDcName intenta buscar un controlador de dominio en el dominio que tenga el GUID especificado por DomainGuid.

[in] SiteName

Puntero a una cadena terminada en null que especifica el nombre del sitio donde debe existir físicamente el controlador de dominio devuelto. Si este parámetro es NULL, DsGetDcName intenta devolver un controlador de dominio en el sitio más cercano al sitio del equipo especificado por ComputerName. Este parámetro debe ser NULL, de forma predeterminada.

[in] Flags

Contiene un conjunto de marcas que proporcionan datos adicionales usados para procesar la solicitud. Este parámetro puede ser una combinación de los valores siguientes.

DS_AVOID_SELF

Cuando se llama desde un controlador de dominio, especifica que el nombre del controlador de dominio devuelto no debe ser el equipo actual. Si el equipo actual no es un controlador de dominio, este marcador se pasa por alto. Esta marca se puede usar para obtener el nombre de otro controlador de dominio en el dominio.

DS_BACKGROUND_ONLY

Si no se especifica la marca DS_FORCE_REDISCOVERY , esta función usa datos almacenados en caché del controlador de dominio. Si los datos almacenados en caché tiene más de 15 minutos de antigüedad, la memoria caché se actualiza haciendo ping al controlador de dominio. Si se especifica esta marca, esta actualización se evita incluso si los datos almacenados en caché han expirado. Esta marca se debe usar si se llama periódicamente a la función DsGetDcName .

DS_DIRECTORY_SERVICE_PREFERRED

DsGetDcName intenta buscar un controlador de dominio que admita funciones de servicio de directorio. Si un controlador de dominio que admite servicios de directorio no está disponible, DsGetDcName devuelve el nombre de un controlador de dominio de servicio que no es de directorio. Sin embargo, DsGetDcName solo devuelve un controlador de dominio de servicio que no es de directorio después de que se agote el tiempo de espera del intento de encontrar un controlador de dominio de servicio de directorio.

DS_DIRECTORY_SERVICE_REQUIRED

Requiere que el controlador de dominio devuelto admita servicios de directorio.

DS_DIRECTORY_SERVICE_6_REQUIRED

Requiere que el controlador de dominio devuelto ejecute Windows Server 2008 o posterior.

DS_DIRECTORY_SERVICE_8_REQUIRED

Requiere que el controlador de dominio devuelto ejecute Windows Server 2012 o posterior.

DS_FORCE_REDISCOVERY

Fuerza a que se omitan los datos del controlador de dominio almacenados en caché. Cuando no se especifica la marca DS_FORCE_REDISCOVERY , DsGetDcName puede devolver datos del controlador de dominio almacenados en caché. Si se especifica esta marca, DsGetDcName no usará información almacenada en caché (si existe alguna), sino que realizará en su lugar una detección de controlador de dominio nueva.

Esta marca no se debe usar en condiciones normales, ya que el uso de la información del controlador de dominio almacenado en caché tiene mejores características de rendimiento y ayuda a garantizar que todas las aplicaciones usen el mismo controlador de dominio de forma coherente. Esta marca solo se debe usar después de que la aplicación determine que el controlador de dominio devuelto por DsGetDcName (cuando se llama sin esta marca) no es accesible. En ese caso, la aplicación debe repetir la llamada DsGetDcName con esta marca para asegurarse de que se omite la información almacenada en caché sin usar (si existe) y se detecta un controlador de dominio accesible.

DS_GC_SERVER_REQUIRED

Requiere que el controlador de dominio devuelto sea un servidor de catálogo global para el bosque de dominios con este dominio como raíz. Si se establece esta marca y el parámetro DomainName no es NULL, DomainName debe especificar un nombre de bosque. Esta marca no se puede combinar con las marcas DS_PDC_REQUIRED o DS_KDC_REQUIRED .

DS_GOOD_TIMESERV_PREFERRED

DsGetDcName intenta buscar un controlador de dominio que sea un servidor horario confiable. El servicio de hora de Windows se puede configurar para declarar uno o varios controladores de dominio como servidor horario confiable. Para obtener más información, consulte la documentación del servicio de hora de Windows . Esta marca está pensada para que solo la use el servicio de hora de Windows.

DS_IP_REQUIRED

Este parámetro indica que el controlador de dominio debe tener una dirección IP. En ese caso, DsGetDcName colocará la dirección del protocolo de Internet del controlador de dominio en el miembro DomainControllerAddress de DomainControllerInfo.

DS_IS_DNS_NAME

Especifica que el parámetro DomainName es un nombre DNS. Esta marca no se puede combinar con la marca DS_IS_FLAT_NAME .

Especifique DS_IS_DNS_NAME o DS_IS_FLAT_NAME. Si no se especifica ninguna marca, DsGetDcName puede tardar más tiempo en buscar un controlador de dominio, ya que puede que tenga que buscar el nombre plano y el estilo DNS.

DS_IS_FLAT_NAME

Especifica que el parámetro DomainName es un nombre plano. Esta marca no se puede combinar con la marca DS_IS_DNS_NAME .

DS_KDC_REQUIRED

Requiere que el controlador de dominio devuelto esté ejecutando actualmente el servicio del Centro de distribución de claves Kerberos. Esta marca no se puede combinar con las marcas DS_PDC_REQUIRED o DS_GC_SERVER_REQUIRED .

DS_ONLY_LDAP_NEEDED

Especifica que el servidor devuelto sea un servidor LDAP. El servidor devuelto no es necesariamente un controlador de dominio. No se supone que otros servicios estén presentes en el servidor. El servidor devuelto no tiene necesariamente un contenedor de configuración grabable ni un contenedor de esquema grabable. Es posible que el servidor devuelto no se use necesariamente para crear o modificar principios de seguridad. Esta marca se puede usar con la marca DS_GC_SERVER_REQUIRED para devolver un servidor LDAP que también hospeda un servidor de catálogo global. El servidor de catálogo global devuelto no es necesariamente un controlador de dominio. No se supone que otros servicios estén presentes en el servidor. Si se especifica esta marca, se omiten las marcas DS_PDC_REQUIRED, DS_TIMESERV_REQUIRED, DS_GOOD_TIMESERV_PREFERRED, DS_DIRECTORY_SERVICES_PREFERED, DS_DIRECTORY_SERVICES_REQUIRED y DS_KDC_REQUIRED .

DS_PDC_REQUIRED

Requiere que el controlador de dominio devuelto sea el controlador de dominio principal para el dominio. Esta marca no se puede combinar con las marcas DS_KDC_REQUIRED o DS_GC_SERVER_REQUIRED .

DS_RETURN_DNS_NAME

Especifica que los nombres devueltos en los miembros DomainControllerName y DomainName de DomainControllerInfo deben ser nombres DNS. Si un nombre DNS no está disponible, se devuelve un error. Esta marca no se puede especificar con la marca DS_RETURN_FLAT_NAME . Esta marca implica la marca DS_IP_REQUIRED .

DS_RETURN_FLAT_NAME

Especifica que los nombres devueltos en los miembros DomainControllerName y DomainName de DomainControllerInfo deben ser nombres planos. Si un nombre plano no está disponible, se devuelve un error. Esta marca no se puede especificar con la marca DS_RETURN_DNS_NAME .

DS_TIMESERV_REQUIRED

Requiere que el controlador de dominio devuelto esté ejecutando actualmente el Servicio de hora de Windows.

DS_TRY_NEXTCLOSEST_SITE

Cuando se especifica esta marca, DsGetDcName intenta buscar un controlador de dominio en el mismo sitio que el autor de la llamada. Si no se encuentra ningún controlador de dominio, encontrará un controlador de dominio que pueda proporcionar información de topología y llamar a DsBindToISTG para obtener un identificador de enlace, llame a DsQuerySitesByCost a través de UDP para determinar el "siguiente sitio más cercano" y, por último, almacene en caché el nombre del sitio encontrado. Si no se encuentra ningún controlador de dominio en ese sitio, DsGetDcName vuelve al método predeterminado de buscar un controlador de dominio.

Si esta marca se usa junto con un valor distinto de NULL en el parámetro de entrada SiteName, se inicia ERROR_INVALID_FLAGS .

Además, el tipo de búsqueda empleado con DS_TRY_NEXT_CLOSEST_SITE es específico del sitio, por lo que esta marca se omite si se usa junto con DS_PDC_REQUIRED. Por último, DS_TRY_NEXTCLOSEST_SITE se omite cuando se usa junto con DS_RETURN_FLAT_NAME porque usa NetBIOS para resolver el nombre, pero el dominio del controlador de dominio encontrado no coincidirá necesariamente con el dominio al que está unido el cliente.

Nota Esta marca está habilitada directiva de grupo. Si habilita la configuración de directiva "Siguiente sitio más cercano", la siguiente ubicación del controlador de dominio del sitio más cercano se activará para la máquina en todos los adaptadores de red disponibles pero no configurados. Si deshabilita la configuración de directiva, la siguiente ubicación de DC de sitio más cercana no se usará de forma predeterminada para la máquina en todos los adaptadores de red disponibles, pero no configurados. Sin embargo, si se realiza una llamada de localizador de controlador de dominio mediante la marca DS_TRY_NEXTCLOSEST_SITE explícitamente, DsGetDcName respeta el comportamiento siguiente del sitio más cercano. Si no establece esta configuración de directiva, la siguiente ubicación de DC del sitio más cercana no se usará de forma predeterminada para la máquina en todos los adaptadores de red disponibles, pero no configurados. Si la marca de DS_TRY_NEXTCLOSEST_SITE se usa explícitamente, se usará el comportamiento siguiente del sitio más cercano.

DS_WRITABLE_REQUIRED

Requiere que se pueda escribir el controlador de dominio devuelto; es decir, hospede una copia grabable del servicio de directorio.

DS_WEB_SERVICE_REQUIRED

Requiere que el controlador de dominio devuelto esté ejecutando actualmente el servicio web de Active Directory.

[out] DomainControllerInfo

Puntero a un valor de PDOMAIN_CONTROLLER_INFO que recibe un puntero a una estructura de DOMAIN_CONTROLLER_INFO que contiene datos sobre el controlador de dominio seleccionado. DsGetDcName asigna esta estructura. El autor de la llamada debe liberar la estructura mediante la función NetApiBufferFree cuando ya no sea necesario.

Valor devuelto

Si la función devuelve datos del controlador de dominio, el valor devuelto es ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto puede ser uno de los siguientes códigos de error.

Comentarios

La función DsGetDcName se envía al servicio Netlogon en el equipo remoto especificado por ComputerName. Si ComputerName es NULL, la función se procesa en el equipo local.

DsGetDcName no comprueba que el nombre del controlador de dominio devuelto sea el nombre de un controlador de dominio real o un catálogo global. Si se requiere autenticación mutua, el autor de la llamada debe realizar la autenticación.

DsGetDcName no requiere ningún acceso determinado al dominio especificado. De forma predeterminada, esta función no garantiza que el controlador de dominio devuelto esté disponible actualmente. En su lugar, el autor de la llamada debe intentar usar el controlador de dominio devuelto. Si el controlador de dominio no está disponible, el autor de la llamada debe llamar a la función DsGetDcName de nuevo, especificando la marca DS_FORCE_REDISCOVERY .

Tiempo de respuesta

Al usar DsGetDcName , tenga en cuenta los siguientes detalles de tiempo:

DsGetDcName realiza llamadas de red y puede tardar entre unos segundos y un minuto, en función del tráfico de red, la topología, la carga del controlador de dominio, etc.
No se recomienda llamar a DsGetDcName desde una interfaz de usuario u otro subproceso crítico de tiempo.
El localizador de controladores de dominio usa lógica optimizada para proporcionar la información del controlador de dominio lo más rápido posible. También usa información almacenada en caché en el sitio para ponerse en contacto con el controlador de dominio más cercano.

Notas sobre la permanencia del controlador de dominio

En Servicios de dominio de Active Directory, la función de localizador de controladores de dominio está diseñada para que una vez que un cliente encuentre un controlador de dominio preferido, el cliente no buscará otro a menos que ese controlador de dominio deje de responder o se reinicie el cliente. Esto se conoce como "Permanencia del controlador de dominio". Dado que las estaciones de trabajo normalmente funcionan durante meses sin un problema o reinicio, una consecuencia no intencionada de este comportamiento es que si un controlador de dominio determinado deja de funcionar por mantenimiento, todos los clientes que estaban conectados a él trasladan sus conexiones a otro controlador de dominio. Pero cuando el controlador de dominio vuelve a funcionar, ningún cliente se vuelve a conectar a él porque los clientes no se reinician con mucha frecuencia. Esto puede causar problemas de equilibrio de carga.

Anteriormente, la solución más común a este problema era implementar un script en cada máquina cliente que se llamaba periódicamente DsGetDcName con la DS_FORCE_REDISCOVERY marca . Se trata de una solución algo complicada, por lo que Windows Server 2008 y Windows Vista introdujeron un nuevo mecanismo que provocó problemas con la permanencia del controlador de dominio.

Cada vez que DsGetDcName recupera un nombre de controlador de dominio de su memoria caché, comprueba si esta entrada almacenada en caché ha expirado y, si es así, descarta ese nombre de controlador de dominio e intenta redescubrir un nombre de controlador de dominio. El valor de las siguientes claves del Registro controla el intervalo de vida de una entrada almacenada en caché.

HKEY_LOCAL_MACHINE\SISTEMA\Currentcontrolset\Servicios\Netlogon\Parámetros\ForceRediscoveryInterval

HKEY_LOCAL_MACHINE\Software\Políticas\Microsoft\Netlogon\Parámetros\ForceRediscoveryInterval

Los valores de estas claves del Registro son de tipo REG_DWORD. Especifican la longitud en segundos antes de que DsGetDcName intente redescubrir el nombre del controlador de dominio. El valor predeterminado es 43200 segundos (12 horas). Si el valor de la entrada del Registro ForceRediscoveryInterval se establece en 0, el cliente siempre realiza el redescubrimiento. Si el valor se establece en 4294967295, la memoria caché nunca expira y el controlador de dominio almacenado en caché continúa utilizándose. Se recomienda no establecer la entrada del Registro ForceRediscoveryInterval en un valor inferior a 3600 segundos (60 minutos).

Nota La configuración del Registro de ForceRediscoveryInterval está habilitada para la directiva de grupo. Si deshabilita la configuración de directiva, Forzar redescubrimiento usará de forma predeterminada para la máquina en cada intervalo de 12 horas. Si no establece esta configuración de directiva, Forzar redescubrimiento se usará de forma predeterminada para la máquina en cada intervalo de 12 horas, a menos que la configuración de la máquina local en el Registro sea un valor diferente.

Tenga en cuenta que si se especifica la marca DS_BACKGROUND_ONLY , DsGetDcName nunca intentará redescubrir el nombre del controlador de dominio, ya que el punto de esa marca es forzar a DsGetDcName a usar el nombre del controlador de dominio almacenado en caché incluso si ha expirado.

Seguimiento de ETW en DsGetDcName

Para activar el seguimiento de ETW para DsGetDcName, cree la siguiente clave del Registro:

HKEY_LOCAL_MACHINE\Sistema\Currentcontrolset\Servicios\DCLocator\Rastreo

La clave tendrá una estructura como se indica a continuación:

String ProcessName
  DWORD  PID <optional>

ProcessName debe ser el nombre completo, incluida la extensión del proceso para el que desea obtener información de seguimiento. PID solo es necesario cuando existen varios procesos con el mismo nombre. Si se define, solo se habilitará el proceso con ese PID para el seguimiento. No es posible realizar un seguimiento de solo 2 de 3 (o más) procesos con el mismo nombre. Puede habilitar una instancia o todas las instancias (cuando existen varias instancias con el mismo nombre de proceso y no se especifica PID, todas las instancias se habilitarán para el seguimiento).

Por ejemplo, esto rastrearía todas las instancias de App1.exe y App2.exe, pero solo la instancia de App3.exe que tiene un PID de 999:

App1.exe 
App2.exe
App3.exe
     PID 999

Ejecute el siguiente comando para iniciar la sesión de seguimiento:

tracelog.exe -start <sessionname> -guid #cfaa5446-c6c4-4f5c-866f-31c9b55b962d -f <filename> -flag <traceFlags>

sessionname es el nombre especificado para la sesión de seguimiento. El guid del proveedor de seguimiento DCLocator es "cfaa5446-c6c4-4f5c-866f-31c9b55b962d". filename es el nombre del archivo de registro en el que se escriben los eventos. traceFlags es una o varias de las marcas siguientes que indican qué áreas se van a rastrear:

Marca	Valor hexadecimal	Descripción
DCLOCATOR_MISC	0x00000002	Depuración varias
DCLOCATOR_MAILSLOT	0x00000010	Mensajes de mailslot
DCLOCATOR_SITE	0x00000020	Sitios
DCLOCATOR_CRITICAL	0x00000100	Errores importantes
DCLOCATOR_SESSION_SETUP	0x00000200	Mantenimiento de dominio de confianza
DCLOCATOR_DNS	0x00004000	Registro de nombres
DCLOCATOR_DNS_MORE	0x00020000	Registro de nombres detallados
DCLOCATOR_MAILBOX_TEXT	0x02000000	Mensajes detallados del buzón
DCLOCATOR_SITE_MORE	0x08000000	Sitios detallados

Ejecute el siguiente comando para detener la sesión de seguimiento:

tracelog.exe -stop <sessionname>

sessionname es el mismo nombre que el nombre que usó al iniciar la sesión.

Nota La clave del Registro para el proceso que se realiza el seguimiento debe estar presente en el Registro en el momento en que se inicia la sesión de seguimiento. Cuando se inicia la sesión, el proceso comprobará si debe generar o no mensajes de seguimiento (en función de la presencia o ausencia de una clave del Registro para ese nombre de proceso y PID opcional). El proceso comprueba el registro solo al principio de la sesión. Cualquier cambio en el registro que se produzca después de eso no tendrá ningún efecto en el seguimiento.

Nota

El encabezado dsgetdc.h define DsGetDcName como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista
Servidor mínimo compatible	Windows Server 2008
Plataforma de destino	Windows
Encabezado	dsgetdc.h
Library	NetApi32.lib
Archivo DLL	NetApi32.dll