Funzione DsGetDcOpenA (dsgetdc.h)

Articolo
08/23/2023

La funzione DsGetDcOpen apre una nuova operazione di enumerazione del controller di dominio.

Sintassi

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

Parametri

[in] DnsName

Puntatore a una stringa con terminazione null contenente il nome DNS (Domain Naming System) del dominio per enumerare i controller di dominio per. Questo parametro non può essere NULL.

[in] OptionFlags

Contiene un set di flag che modificano il comportamento della funzione. Questo può essere zero o una combinazione di uno o più dei valori seguenti.

DS_ONLY_DO_SITE_NAME

Vengono enumerati solo controller di dominio specifici del sito.

DS_NOTIFY_AFTER_SITE_RECORDS

La funzione DsGetDcNext restituirà il valore di ERROR_FILEMARK_DETECTED dopo che tutti i controller di dominio specifici del sito vengono recuperati. DsGetDcNext enumererà quindi il secondo gruppo, che contiene tutti i controller di dominio nel dominio, inclusi i controller di dominio specifici del sito contenuti nel primo gruppo.

[in, optional] SiteName

Puntatore a una stringa con terminazione null contenente il nome del sito in cui si trova il client. Questo parametro è facoltativo e può essere NULL.

[in, optional] DomainGuid

Puntatore a un valore GUID contenente l'identificatore del dominio specificato da DnsName. Questo identificatore viene usato per gestire il caso di un dominio rinominato. Se questo valore viene specificato e il dominio specificato in DnsName viene rinominato, questa funzione tenta di enumerare i controller di dominio nel dominio contenente l'identificatore specificato. Questo parametro è facoltativo e può essere NULL.

[in, optional] DnsForestName

Puntatore a una stringa con terminazione null contenente il nome della foresta contenente il dominio DnsName . Questo valore viene usato insieme a DomainGuid per enumerare i controller di dominio se il dominio è stato rinominato. Questo parametro è facoltativo e può essere NULL.

[in] DcFlags

Contiene un set di flag che identificano il tipo di controller di dominio da enumerare. Questo può essere zero o una combinazione di uno o più dei valori seguenti.

DS_FORCE_REDISCOVERY

Impone l'ignorare i dati del controller di dominio memorizzati nella cache. Quando questo flag non è specificato, DsGetDcOpen ottiene l'enumerazione del controller di dominio dai dati del controller di dominio memorizzati nella cache.

DS_GC_SERVER_REQUIRED

Richiede che i controller di dominio enumerati siano server di catalogo globali per la foresta di domini con questo dominio come radice. Questo flag non può essere combinato con il flag DS_PDC_REQUIRED .

DS_KDC_REQUIRED

Richiede che i controller di dominio enumerati eseguano attualmente il servizio Centro distribuzione chiavi Kerberos. Questo flag non può essere combinato con i flag DS_PDC_REQUIRED o DS_GC_SERVER_REQUIRED .

DS_ONLY_LDAP_NEEDED

Specifica che i server enumerati sono server LDAP. I server non sono necessariamente controller di dominio. Nessun altro servizio è implicito essere presente in ogni server enumerato. I server non hanno necessariamente un contenitore di configurazione scrivibile né un contenitore di schemi scrivibile. I server possono non essere necessariamente usati per creare o modificare i principi di sicurezza. Questo flag può essere usato con il flag DS_GC_SERVER_REQUIRED per enumerare server LDAP che ospitano anche un server di catalogo globale. In tal caso, i server di catalogo globale enumerati non sono necessariamente controller di dominio e altri servizi sono impliciti per essere presenti in ogni server. Se viene specificato questo flag, i flag DS_PDC_REQUIRED, DS_TIMESERV_REQUIRED, DS_GOOD_TIMESERV_PREFERRED, DS_DIRECTORY_SERVICES_PREFERED, DS_DIRECTORY_SERVICES_REQUIREDe DS_KDC_REQUIRED flag vengono ignorati.

DS_PDC_REQUIRED

Richiede che i controller di dominio enumerati siano i controller di dominio primari per il dominio. Questo flag non può essere combinato con il flag di DS_GC_SERVER_REQUIRED .

[out] RetGetDcContext

Puntatore a un valore HANDLE che riceve l'handle di contesto dell'enumerazione del controller di dominio. Questo handle viene usato con la funzione DsGetDcNext per identificare l'operazione di enumerazione del controller di dominio. Questo handle viene passato a DsGetDcClose per chiudere l'operazione di enumerazione del controller di dominio.

Valore restituito

Restituisce ERROR_SUCCESS se ha esito positivo o un errore WIN32 o RPC in caso contrario. I valori di errore possibili includono quanto segue.

Commenti

Nota

L'intestazione dsgetdc.h definisce DsGetDcOpen come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti


Client minimo supportato	Windows Vista
Server minimo supportato	Windows Server 2008
Piattaforma di destinazione	Windows
Intestazione	dsgetdc.h
Libreria	Netapi32.lib
DLL	Netapi32.dll