Funzione DsGetDcNameA (dsgetdc.h)
La funzione DsGetDcName restituisce il nome di un controller di dominio in un dominio specificato. Questa funzione accetta criteri di selezione aggiuntivi del controller di dominio per indicare la preferenza per un controller di dominio con caratteristiche specifiche.
Sintassi
DSGETDCAPI DWORD DsGetDcNameA(
[in] LPCSTR ComputerName,
[in] LPCSTR DomainName,
[in] GUID *DomainGuid,
[in] LPCSTR SiteName,
[in] ULONG Flags,
[out] PDOMAIN_CONTROLLER_INFOA *DomainControllerInfo
);
Parametri
[in] ComputerName
Puntatore a una stringa con terminazione null che specifica il nome del server per elaborare questa funzione. In genere, questo parametro è NULL, che indica che viene usato il computer locale.
[in] DomainName
Puntatore a una stringa con terminazione null che specifica il nome del dominio o della partizione dell'applicazione da eseguire in query. Questo nome può essere un nome di stile DNS, ad esempio fabrikam.com o un nome in stile flat, ad esempio Fabrikam. Se viene specificato un nome di stile DNS, il nome può essere specificato con o senza un periodo finale.
Se il parametro Flags contiene il flag DS_GC_SERVER_REQUIRED , DomainName deve essere il nome della foresta. In questo caso , DsGetDcName ha esito negativo se DomainName specifica un nome che non è la radice della foresta.
Se il parametro Flags contiene il flag DS_GC_SERVER_REQUIRED e DomainName è NULL, DsGetDcName tenta di trovare un catalogo globale nella foresta del computer identificato da ComputerName, ovvero il computer locale se ComputerName è NULL.
Se DomainName è NULL e il parametro Flags non contiene il flag DS_GC_SERVER_REQUIRED , ComputerName è impostato sul nome di dominio predefinito del dominio primario del computer identificato da ComputerName.
[in] DomainGuid
Puntatore a una struttura GUID che specifica il GUID del dominio sottoposto a query. Se DomainGuid non è NULL e il dominio specificato da DomainName o ComputerName non è disponibile, DsGetDcName tenta di individuare un controller di dominio nel dominio con il GUID specificato da DomainGuid.
[in] SiteName
Puntatore a una stringa con terminazione null che specifica il nome del sito in cui deve esistere fisicamente il controller di dominio restituito. Se questo parametro è NULL, DsGetDcName tenta di restituire un controller di dominio nel sito più vicino al sito del computer specificato da ComputerName. Questo parametro deve essere NULL, per impostazione predefinita.
[in] Flags
Contiene un set di flag che forniscono dati aggiuntivi usati per elaborare la richiesta. Questo parametro può essere una combinazione dei valori seguenti.
DS_AVOID_SELF
Quando viene chiamato da un controller di dominio, specifica che il nome del controller di dominio restituito non deve essere il computer corrente. Se il computer corrente non è un controller di dominio, questo flag viene ignorato. Questo flag può essere usato per ottenere il nome di un altro controller di dominio nel dominio.
DS_BACKGROUND_ONLY
Se il flag DS_FORCE_REDISCOVERY non è specificato, questa funzione usa i dati del controller di dominio memorizzati nella cache. Se i dati memorizzati nella cache sono più di 15 minuti precedenti, la cache viene aggiornata eseguendo il ping del controller di dominio. Se questo flag viene specificato, questo aggiornamento viene evitato anche se i dati memorizzati nella cache sono scaduti. Questo flag deve essere usato se la funzione DsGetDcName viene chiamata periodicamente.
DS_DIRECTORY_SERVICE_PREFERRED
DsGetDcName tenta di trovare un controller di dominio che supporta le funzioni del servizio directory. Se un controller di dominio che supporta i servizi directory non è disponibile, DsGetDcName restituisce il nome di un controller di dominio non del servizio directory. Tuttavia, DsGetDcName restituisce solo un controller di dominio del servizio non directory dopo il tentativo di trovare un controller di dominio del servizio directory timeout.
DS_DIRECTORY_SERVICE_REQUIRED
Richiede che il controller di dominio restituito supporti i servizi directory.
DS_DIRECTORY_SERVICE_6_REQUIRED
Richiede che il controller di dominio restituito sia in esecuzione Windows Server 2008 o versione successiva.
DS_DIRECTORY_SERVICE_8_REQUIRED
Richiede che il controller di dominio restituito sia in esecuzione Windows Server 2012 o versione successiva.
DS_FORCE_REDISCOVERY
Impone l'ignorare i dati del controller di dominio memorizzati nella cache. Quando il flag di DS_FORCE_REDISCOVERY non è specificato, DsGetDcName può restituire i dati del controller di dominio memorizzati nella cache. Se questo flag è specificato, DsGetDcName non userà le informazioni memorizzate nella cache (se presente) ma eseguirà invece un'individuazione del controller di dominio aggiornata.
Questo flag non deve essere usato in condizioni normali, come l'uso delle informazioni sul controller di dominio memorizzato nella cache presenta caratteristiche di prestazioni migliori e consente di garantire che lo stesso controller di dominio venga usato in modo coerente da tutte le applicazioni. Questo flag deve essere usato solo dopo che l'applicazione determina che il controller di dominio restituito da DsGetDcName (quando chiamato senza questo flag) non è accessibile. In tal caso, l'applicazione deve ripetere la chiamata DsGetDcName con questo flag per assicurarsi che le informazioni memorizzate nella cache non utili (se presenti) vengano ignorate e venga individuato un controller di dominio raggiungibile.
DS_GC_SERVER_REQUIRED
Richiede che il controller di dominio restituito sia un server di catalogo globale per l'insieme di domini con il dominio impostato come radice. Se questo flag è impostato e il parametro DomainName non è NULL, DomainName deve specificare un nome di foresta. Questo flag non può essere combinato con i flag DS_PDC_REQUIRED o DS_KDC_REQUIRED .
DS_GOOD_TIMESERV_PREFERRED
DsGetDcName tenta di trovare un controller di dominio che è un server di tempo affidabile. Il servizio ora di Windows può essere configurato per dichiarare uno o più controller di dominio come server di tempo affidabile. Per altre informazioni, vedere la documentazione del servizio ora di Windows . Questo flag deve essere usato solo dal servizio ora di Windows.
DS_IP_REQUIRED
Questo parametro indica che il controller di dominio deve avere un indirizzo IP. In tal caso , DsGetDcName inserisce l'indirizzo del protocollo Internet del controller di dominio nel membro DomainControllerAddress di DomainControllerInfo.
DS_IS_DNS_NAME
Specifica che il parametro DomainName è un nome DNS. Questo flag non può essere combinato con il flag DS_IS_FLAT_NAME .
Specificare DS_IS_DNS_NAME o DS_IS_FLAT_NAME. Se non viene specificato alcun flag, DsGetDcName potrebbe richiedere più tempo per trovare un controller di dominio perché potrebbe dover cercare sia il nome DNS che il nome flat.
DS_IS_FLAT_NAME
Specifica che il parametro DomainName è un nome flat. Questo flag non può essere combinato con il flag DS_IS_DNS_NAME .
DS_KDC_REQUIRED
Richiede che nel controller di dominio restituito sia in esecuzione il servizio Kerberos KDC (Key Distribution Center). Questo flag non può essere combinato con i flag DS_PDC_REQUIRED o DS_GC_SERVER_REQUIRED .
DS_ONLY_LDAP_NEEDED
Specifica che il server restituito è un server LDAP. Il server restituito non è necessariamente un controller di dominio. Nessun altro servizio è implicito essere presente nel server. Il server restituito non ha necessariamente un contenitore di configurazione scrivibile né un contenitore dello schema scrivibile. Il server restituito potrebbe non essere necessariamente usato per creare o modificare i principi di sicurezza. Questo flag può essere usato con il flag DS_GC_SERVER_REQUIRED per restituire un server LDAP che ospita anche un server di catalogo globale. Il server di catalogo globale restituito non è necessariamente un controller di dominio. Nessun altro servizio è implicito essere presente nel 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 il controller di dominio restituito sia quello primario per il dominio. Questo flag non può essere combinato con i flag DS_KDC_REQUIRED o DS_GC_SERVER_REQUIRED .
DS_RETURN_DNS_NAME
Specifica che i nomi restituiti nei membri DomainControllerName e DomainName di DomainControllerInfo devono essere nomi DNS. Se non è disponibile un nome DNS, viene restituito un errore. Questo flag non può essere specificato con il flag di DS_RETURN_FLAT_NAME . Questo flag implica il flag di DS_IP_REQUIRED .
DS_RETURN_FLAT_NAME
Specifica che i nomi restituiti nei membri DomainControllerName e DomainName di DomainControllerInfo devono essere nomi flat. Se un nome flat non è disponibile, viene restituito un errore. Impossibile specificare questo flag con il flag DS_RETURN_DNS_NAME .
DS_TIMESERV_REQUIRED
Richiede che nel controller di dominio restituito sia in esecuzione il servizio Ora di Windows.
DS_TRY_NEXTCLOSEST_SITE
Quando viene specificato questo flag, DsGetDcName tenta di trovare un controller di dominio nello stesso sito del chiamante. Se non viene trovato alcun controller di dominio di questo tipo, troverà un controller di dominio in grado di fornire informazioni sulla topologia e chiamare DsBindToISTG per ottenere un handle di associazione, quindi chiamare DsQuerySitesByCost su UDP per determinare il "sito più vicino successivo" e infine memorizzare nella cache il nome del sito trovato. Se non viene trovato alcun controller di dominio nel sito, DsGetDcName esegue il fallback sul metodo predefinito di individuazione di un controller di dominio.
Se questo flag viene usato insieme a un valore non NULL nel parametro di input SiteName, viene generata ERROR_INVALID_FLAGS .
Inoltre, il tipo di ricerca usato con DS_TRY_NEXT_CLOSEST_SITE è specifico del sito, quindi questo flag viene ignorato se viene usato in combinazione con DS_PDC_REQUIRED. Infine, DS_TRY_NEXTCLOSEST_SITE viene ignorato quando viene usato in combinazione con DS_RETURN_FLAT_NAME perché usa NetBIOS per risolvere il nome, ma il dominio del controller di dominio trovato non corrisponde necessariamente al dominio a cui viene aggiunto il client.
DS_WRITABLE_REQUIRED
Richiede che il controller di dominio restituito sia scrivibile; ovvero ospitare una copia scrivibile del servizio directory.
DS_WEB_SERVICE_REQUIRED
Richiede che il controller di dominio restituito esegua attualmente il servizio Web Active Directory.
[out] DomainControllerInfo
Puntatore a un valore PDOMAIN_CONTROLLER_INFO che riceve un puntatore a una struttura DOMAIN_CONTROLLER_INFO che contiene dati sul controller di dominio selezionato. Questa struttura viene allocata da DsGetDcName. Il chiamante deve liberare la struttura usando la funzione NetApiBufferFree quando non è più necessaria.
Valore restituito
Se la funzione restituisce dati del controller di dominio, il valore restituito è ERROR_SUCCESS.
Se la funzione ha esito negativo, il valore restituito può essere uno dei codici di errore seguenti.
Commenti
La funzione DsGetDcName viene inviata al servizio Netlogon nel computer remoto specificato da ComputerName. Se ComputerName è NULL, la funzione viene elaborata nel computer locale.
DsGetDcName non verifica che il nome del controller di dominio restituito sia il nome di un controller di dominio effettivo o di un catalogo globale. Se è necessaria l'autenticazione reciproca, il chiamante deve eseguire l'autenticazione.
DsGetDcName non richiede alcun accesso specifico al dominio specificato. Per impostazione predefinita, questa funzione non garantisce che il controller di dominio restituito sia attualmente disponibile. Al contrario, il chiamante deve tentare di usare il controller di dominio restituito. Se il controller di dominio non è disponibile, il chiamante deve chiamare di nuovo la funzione DsGetDcName , specificando il flag DS_FORCE_REDISCOVERY .
Tempo di risposta
Quando si usa DsGetDcName , tenere presente i dettagli di intervallo seguenti:- DsGetDcName effettua chiamate di rete e può richiedere da alcuni secondi fino a un minuto, a seconda del traffico di rete, della topologia, del carico del controller di dominio e così via.
- Non è consigliabile chiamare DsGetDcName da un'interfaccia utente o da un altro thread critico di intervallo.
- Il localizzatore di controller di dominio usa la logica ottimizzata per fornire le informazioni sul controller di dominio il più rapidamente possibile. Usa anche le informazioni memorizzate nella cache nel sito per contattare il controller di dominio più vicino.
Note sulla persistenza del controller di dominio
In Active Directory Domain Services, la funzione del localizzatore di controller di dominio è progettata in modo che dopo che un client trovi un controller di dominio preferito, il client non cercherà un altro a meno che il controller di dominio non risponda o il client venga riavviato. Questa operazione viene definita "Stickiness del controller di dominio". Poiché le workstation funzionano in genere per mesi senza problemi o riavvii, una conseguenza imprevista di questo comportamento è che se un determinato controller di dominio si arresta per la manutenzione, tutti i client connessi a esso spostano le connessioni a un altro controller di dominio. Tuttavia, quando viene eseguito il backup del controller di dominio, nessun client si riconnette a esso perché i client non vengono riavviati molto spesso. Ciò può causare problemi di bilanciamento del carico.In precedenza, la soluzione più comune a questo problema era distribuire uno script in ogni computer client che periodicamente ha chiamato DsGetDcName usando il DS_FORCE_REDISCOVERY flag . Si tratta di una soluzione piuttosto complessa, quindi Windows Server 2008 e Windows Vista ha introdotto un nuovo meccanismo che ha causato problemi di persistenza del controller di dominio.
Ogni volta che DsGetDcName recupera un nome di controller di dominio dalla cache, verifica se questa voce memorizzata nella cache è scaduta e, in tal caso, rimuove il nome del controller di dominio e tenta di individuare un nome di controller di dominio. L'intervallo di vita di una voce memorizzata nella cache è controllato dal valore nelle chiavi del Registro di sistema seguenti
HKEY_LOCAL_MACHINE\SISTEMA\Currentcontrolset\Servizi\Netlogon\Parametri\ForceRediscoveryInterval
e
HKEY_LOCAL_MACHINE\Software\Politiche\Microsoft\Netlogon\Parametri\ForceRediscoveryInterval
I valori in queste chiavi del Registro di sistema sono di tipo REG_DWORD. Specificano la lunghezza in secondi prima che DsGetDcName tenti di ritrovare il nome del controller di dominio. Il valore predefinito è 43200 secondi (12 ore). Se il valore della voce del Registro di sistema ForceRediscoveryInterval è impostato su 0, il client esegue sempre l'individuazione. Se il valore è impostato su 4294967295, la cache non scade mai e il controller di dominio memorizzato nella cache continua a essere usato. È consigliabile non impostare la voce del Registro di sistema ForceRediscoveryInterval su un valore inferiore a 3600 secondi (60 minuti).
Traccia ETW in DsGetDcName
Per attivare la traccia ETW per DsGetDcName, creare la chiave del Registro di sistema seguente:HKEY_LOCAL_MACHINE\Sistema\Currentcontrolset\Servizi\DCLocator\Traccia
La chiave avrà una struttura come segue:
String ProcessName
DWORD PID <optional>
ProcessName deve essere il nome completo, inclusa l'estensione del processo per cui si desidera ottenere informazioni di traccia. Il PID è obbligatorio solo quando esistono più processi con lo stesso nome. Se è definito, solo il processo con tale PID verrà abilitato per la traccia. Non è possibile tracciare solo 2 processi su 3 (o più) con lo stesso nome. È possibile abilitare un'istanza o tutte le istanze (quando esistono più istanze con lo stesso nome di processo e PID non è specificato, tutte le istanze verranno abilitate per la traccia).
Ad esempio, tracciare tutte le istanze di App1.exe e App2.exe, ma solo l'istanza di App3.exe con pid 999:
App1.exe
App2.exe
App3.exe
PID 999
Eseguire il comando seguente per avviare la sessione di traccia:
tracelog.exe -start <sessionname> -guid #cfaa5446-c6c4-4f5c-866f-31c9b55b962d -f <filename> -flag <traceFlags>
sessionname è il nome specificato per la sessione di traccia. Il GUID per il provider di traccia DCLocator è "cfaa5446-c6c4-4f5c-866f-31c9b55b962d". filename è il nome del file di log in cui vengono scritti gli eventi. traceFlags è uno o più dei flag seguenti che indicano quali aree tracciare:
| Contrassegno | Valore esadecimale | Descrizione |
|---|---|---|
| DCLOCATOR_MISC | 0x00000002 | Debug esterno |
| DCLOCATOR_MAILSLOT | 0x00000010 | Messaggi mailslot |
| DCLOCATOR_SITE | 0x00000020 | Siti |
| DCLOCATOR_CRITICAL | 0x00000100 | Errori importanti |
| DCLOCATOR_SESSION_SETUP | 0x00000200 | Manutenzione dominio attendibile |
| DCLOCATOR_DNS | 0x00004000 | Registrazione del nome |
| DCLOCATOR_DNS_MORE | 0x00020000 | Registrazione dei nomi dettagliata |
| DCLOCATOR_MAILBOX_TEXT | 0x02000000 | Messaggi dettagliati delle cassette postali |
| DCLOCATOR_SITE_MORE | 0x08000000 | Siti dettagliato |
Eseguire il comando seguente per arrestare la sessione di traccia:
tracelog.exe -stop <sessionname>
sessionname corrisponde al nome usato all'avvio della sessione.
Nota
L'intestazione dsgetdc.h definisce DsGetDcName 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows Vista |
| Server minimo supportato | Windows Server 2008 |
| Piattaforma di destinazione | Windows |
| Intestazione | dsgetdc.h |
| Libreria | NetApi32.lib |
| DLL | NetApi32.dll |