Función DsGetDcOpenA (dsgetdc.h)

Artículo
08/23/2023

La función DsGetDcOpen abre una nueva operación de enumeración del controlador de dominio.

Sintaxis

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
);

Parámetros

[in] DnsName

Puntero a una cadena terminada en null que contiene el nombre del sistema de nomenclatura de dominio (DNS) del dominio para el que se van a enumerar los controladores de dominio. Este parámetro no puede ser NULL.

[in] OptionFlags

Contiene un conjunto de marcas que modifican el comportamiento de la función. Puede ser cero o una combinación de uno o varios de los valores siguientes.

DS_ONLY_DO_SITE_NAME

Solo se enumeran los controladores de dominio específicos del sitio.

DS_NOTIFY_AFTER_SITE_RECORDS

La función DsGetDcNext devolverá el valor de ERROR_FILEMARK_DETECTED después de recuperar todos los controladores de dominio específicos del sitio. A continuación, DsGetDcNext enumerará el segundo grupo, que contiene todos los controladores de dominio del dominio, incluidos los controladores de dominio específicos del sitio contenidos en el primer grupo.

[in, optional] SiteName

Puntero a una cadena terminada en null que contiene el nombre del sitio en el que se encuentra el cliente. Este parámetro es opcional y puede ser NULL.

[in, optional] DomainGuid

Puntero a un valor GUID que contiene el identificador del dominio especificado por DnsName. Este identificador se usa para controlar el caso de un dominio cuyo nombre ha cambiado. Si se especifica este valor y se cambia el nombre del dominio especificado en DnsName , esta función intenta enumerar controladores de dominio en el dominio que contiene el identificador especificado. Este parámetro es opcional y puede ser NULL.

[in, optional] DnsForestName

Puntero a una cadena terminada en null que contiene el nombre del bosque que contiene el dominio DnsName . Este valor se usa junto con DomainGuid para enumerar los controladores de dominio si se ha cambiado el nombre del dominio. Este parámetro es opcional y puede ser NULL.

[in] DcFlags

Contiene un conjunto de marcas que identifican el tipo de controladores de dominio que se van a enumerar. Puede ser cero o una combinación de uno o varios de los valores siguientes.

DS_FORCE_REDISCOVERY

Fuerza a que se omitan los datos del controlador de dominio almacenados en caché. Cuando no se especifica esta marca, DsGetDcOpen obtiene la enumeración del controlador de dominio de los datos del controlador de dominio almacenados en caché.

DS_GC_SERVER_REQUIRED

Requiere que los controladores de dominio enumerados sean servidores de catálogo global para el bosque de dominios con este dominio como raíz. Esta marca no se puede combinar con la marca DS_PDC_REQUIRED .

DS_KDC_REQUIRED

Requiere que los controladores de dominio enumerados ejecuten 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 los servidores enumerados son servidores LDAP. Los servidores no son necesariamente controladores de dominio. No se supone que otros servicios estén presentes en cada servidor enumerado. Los servidores no tienen necesariamente un contenedor de configuración grabable ni un contenedor de esquema grabable. Es posible que los servidores no se usen necesariamente para crear o modificar principios de seguridad. Esta marca se puede usar con la marca DS_GC_SERVER_REQUIRED para enumerar los servidores LDAP que también hospedan un servidor de catálogo global. En ese caso, los servidores de catálogo global enumerados no son necesariamente controladores de dominio y otros servicios están implícitos en estar presentes en cada 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 los controladores de dominio enumerados sean los controladores de dominio principales del dominio. Esta marca no se puede combinar con la marca DS_GC_SERVER_REQUIRED .

[out] RetGetDcContext

Puntero a un valor HANDLE que recibe el identificador de contexto de enumeración del controlador de dominio. Este identificador se usa con la función DsGetDcNext para identificar la operación de enumeración del controlador de dominio. Este identificador se pasa a DsGetDcClose para cerrar la operación de enumeración del controlador de dominio.

Valor devuelto

Devuelve ERROR_SUCCESS si se ejecuta correctamente o un error de Win32 o RPC en caso contrario. Entre los posibles valores de error se incluyen los siguientes.

Comentarios

Nota:

El encabezado dsgetdc.h define DsGetDcOpen 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 Convenciones para prototipos de función.

Requisitos


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