Función DsGetDcNameW (dsgetdc.h)
La función
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
Si el parámetro Flags
Si
[in] DomainGuid
Puntero a una estructura GUID de
[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 siguientes valores.
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, se omite esta marca. 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 los datos del controlador de dominio almacenados en caché. 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 encontrar 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 el intento de encontrar un controlador de dominio de servicio de directorio agote el tiempo de espera.
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 la omisión de los datos del controlador de dominio almacenados en caché. Cuando no se especifica la marca de 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á una detección de controlador de dominio nueva.
Esta marca no debe usarse 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 de forma coherente el mismo controlador de dominio. 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 el DsGetDcName llamada 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 encontrar un controlador de dominio que sea un servidor de hora confiable. El servicio de hora de Windows se puede configurar para declarar uno o varios controladores de dominio como un servidor horario confiable. Para obtener más información, consulte la documentación de 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 domainControllerAddress miembro de DomainControllerInfo.
DS_IS_DNS_NAME
Especifica que el parámetro domainName de
Especifique DS_IS_DNS_NAME o DS_IS_FLAT_NAME. Si no se especifica ninguna marca, DsGetDcName puede tardar más tiempo en encontrar un controlador de dominio porque puede tener que buscar tanto el estilo DNS como el nombre plano.
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 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 es un servidor LDAP. El servidor devuelto no es necesariamente un controlador de dominio. Ningún otro servicio está implícito en estar presente en el servidor. El servidor devuelto no tiene necesariamente una configuración escritura contenedor ni un contenedor de esquemas 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. Ningún otro servicio está implícito en estar presente 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_REQUIREDy 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 el domainControllerName de
DS_RETURN_FLAT_NAME
Especifica que los nombres devueltos en el DomainControllerName de
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 encontrar 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 puede 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, almacenar en caché el nombre del sitio encontrado. Si no se encuentra ningún controlador de dominio en ese sitio, DsGetDcName recurre 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. Esta estructura se asigna mediante DsGetDcName. El autor de la llamada debe liberar la estructura mediante la función de 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.
Observaciones
La función
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 de
Al usar DsGetDcName tenga en cuenta los siguientes detalles de tiempo:- DsGetDcName realiza llamadas de red y puede tardar unos segundos hasta 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 antes 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 de en la permanencia del controlador de dominio
En Active Directory Domain Services, 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 deseada de este comportamiento es que si un controlador de dominio determinado deja de funcionar por mantenimiento, todos los clientes conectados a él cambian 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 provocar 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 a la que se llamaba periódicamente DsGetDcName con la marca DS_FORCE_REDISCOVERY. 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.
Siempre 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 volver a detectar un nombre de controlador de dominio. El intervalo de vida de una entrada almacenada en caché se controla mediante el valor de las siguientes claves del Registro.
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Netlogon\Parameters\ForceRediscoveryInterval
y
Directivas de
Los valores de estas claves del Registro son de tipo REG_DWORD. Especifican la longitud en segundos antes de DsGetDcName deben intentar volver a detectar el nombre del controlador de dominio. El valor predeterminado es 43200 segundos (12 horas). Si el valor del ForceRediscoveryInterval entrada del Registro 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 usándose. Se recomienda no establecer el ForceRediscoveryInterval entrada del Registro en un valor inferior a 3600 segundos (60 minutos).
seguimiento etw de en DsGetDcName
Para activar de seguimiento ETW para DsGetDcName, cree la siguiente clave del Registro:HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\DCLocator\Tracing
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 se requiere 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 procesos (o más) 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 realizaría un seguimiento de 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 <nombre de sesión> -guid #cfaa5446-c6c4-4f5c-866f-31c9b55b962d -f <nombre de archivo> -flag <traceFlags>
nombre de sesión es el nombre especificado para la sesión de seguimiento. El guid de
| Bandera | 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 detallado de nombres |
| 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
nombre de sesión 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows Vista |
| servidor mínimo admitido | Windows Server 2008 |
| de la plataforma de destino de |
Windows |
| encabezado de |
dsgetdc.h |
| biblioteca de |
NetApi32.lib |
| DLL de |
NetApi32.dll |
Consulte también
funciones del servicio de directorio de
GUID de