Función DsGetDcNameA (dsgetdc.h)
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 DsGetDcNameA(
[in] LPCSTR ComputerName,
[in] LPCSTR DomainName,
[in] GUID *DomainGuid,
[in] LPCSTR SiteName,
[in] ULONG Flags,
[out] PDOMAIN_CONTROLLER_INFOA *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.
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
y
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).
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
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 |
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de