Funzione DsGetDcOpenA (dsgetdc.h)

Articolo
11/20/2024

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 cui enumerare i controller di dominio. Questo parametro non può essere NULL.

[in] OptionFlags

Contiene un set di flag che modificano il comportamento della funzione. 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 ERROR_FILEMARK_DETECTED dopo il recupero di tutti i controller di dominio specifici del sito. 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 che contiene il nome del sito in cui si trova il client. Questo parametro è facoltativo e può essere NULL.

[in, optional] DomainGuid

Puntatore a un GUID valore che contiene 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 che contiene 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. Può essere zero o una combinazione di uno o più dei valori seguenti.

DS_FORCE_REDISCOVERY

Forza l'ignorare dei dati del controller di dominio memorizzati nella cache. Quando questo flag non viene 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 dispongono necessariamente di un contenitore di di configurazione scrivibile né di uno schema scrivibile contenitore. I server potrebbero 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 i 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 si specifica 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 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 DS_GC_SERVER_REQUIRED.

[out] RetGetDcContext

Puntatore a un HANDLE valore che riceve l'handle del contesto di 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 in caso di esito positivo o di errore Win32 o RPC in caso contrario. I possibili valori di errore includono quanto segue.

Osservazioni

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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista
server minimo supportato	Windows Server 2008
piattaforma di destinazione	Finestre
intestazione	dsgetdc.h
libreria	Netapi32.lib
dll	Netapi32.dll