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 su cui eseguire la 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 punto finale.
Se il parametro flag
Se il parametro Flags
Se
[in] DomainGuid
Puntatore a una struttura GUID
[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 NomeComputer. 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 hanno più di 15 minuti, 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
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 del servizio non 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.
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 esegua Windows Server 2008 o versione successiva.
DS_DIRECTORY_SERVICE_8_REQUIRED
Richiede che il controller di dominio restituito esegua Windows Server 2012 o versione successiva.
DS_FORCE_REDISCOVERY
Forza l'ignorare dei 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 si specifica questo flag, DsGetDcName non userà le informazioni memorizzate nella cache (se presenti) ma eseguirà invece un'individuazione aggiornata del controller di dominio.
Questo flag non deve essere usato in condizioni normali, perché l'uso delle informazioni del 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 viene chiamato senza questo flag) non è accessibile. In tal caso, l'applicazione deve ripetere la DsGetDcName chiamata con questo flag per assicurarsi che le informazioni non necessarie memorizzate nella cache (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 la foresta di domini con questo dominio come radice. Se questo flag è impostato e il parametro DomainName
DS_GOOD_TIMESERV_PREFERRED
DsGetDcName tenta di trovare un controller di dominio affidabile. Il servizio ora di Windows può essere configurato per dichiarare uno o più controller di dominio come server ora affidabile. Per altre informazioni, vedere la documentazione
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 DomainControllerAddress membro di DomainControllerInfo.
DS_IS_DNS_NAME
Specifica che il parametro domainName
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 il controller di dominio restituito esegua 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 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 contenitore né uno schema scrivibile contenitore. Il server restituito potrebbe non essere necessariamente utilizzato 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 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 il controller di dominio restituito sia il controller di dominio 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 nel DomainControllerName e DomainName membri 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 DS_RETURN_FLAT_NAME. Questo flag implica il flag DS_IP_REQUIRED.
DS_RETURN_FLAT_NAME
Specifica che i nomi restituiti nel DomainControllerName
DS_TIMESERV_REQUIRED
Richiede che il controller di dominio restituito esegua attualmente il servizio Ora di Windows.
DS_TRY_NEXTCLOSEST_SITE
Quando si specifica 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 successivo più vicino" e infine memorizzare nella cache il nome del sito trovato. Se non viene trovato alcun controller di dominio in tale 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 insieme a DS_PDC_REQUIRED. Infine, DS_TRY_NEXTCLOSEST_SITE viene ignorato quando viene usato insieme a 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
Valore restituito
Se la funzione restituisce i 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.
Osservazioni
La funzione DsGetDcName
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 nuovamente la funzione DsGetDcName
tempo di risposta
Quando si usa DsGetDcName tenere presenti 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 permanentità del controller di dominio
In Servizi di dominio Active Directory 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 che il client venga riavviato. Questa operazione viene definita "Stickiness controller di dominio". Poiché le workstation funzionano in genere per mesi senza problemi o riavvii, una conseguenza imprevista di questo comportamento è che se un particolare controller di dominio è inattivo per la manutenzione, tutti i client connessi spostano le connessioni a un altro controller di dominio. Tuttavia, quando viene eseguito il backup del controller di dominio, nessun client si riconnette mai 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 consiste nel distribuire uno script in ogni computer client chiamato periodicamente DsGetDcName usando il flag DS_FORCE_REDISCOVERY. Questa è stata una soluzione piuttosto complessa, quindi Windows Server 2008 e Windows Vista ha introdotto un nuovo meccanismo che ha causato problemi con la persistenza del controller di dominio.
Ogni volta che DsGetDcName recupera un nome di controller di dominio dalla cache, verifica se la 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\SYSTEM\CurrentControlSet\Services\\Parameters\ForceRediscoveryInterval
e
Criteri di
I valori in queste chiavi del Registro di sistema sono di tipo REG_DWORD. Specificano la lunghezza in secondi prima di
traccia ETW in DsGetDcName
Per attivare traccia ETW per DsGetDcName, creare la chiave del Registro di sistema seguente:HKEY_LOCAL_MACHINE\\CurrentControlSet\Services\DCLocator\Tracing
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. PID è necessario solo quando esistono più processi con lo stesso nome. Se è definito, per la traccia verrà abilitato solo il processo con tale PID. 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, in questo modo vengono tracciate 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 <nome sessione> -guid #cfaa5446-c6c4-4f5c-866f-31c9b55b962d -f <filename> -flag <traceFlags>
nome sessione è il nome specificato per la sessione di traccia. Il guid per il provider di traccia DCLocator è "cfaa5446-c6c4-4f5c-866f-31c9b55b962d". nome file è il nome del file di log in cui vengono scritti gli eventi. traceFlags è uno o più dei flag seguenti che indicano quali aree tracciare:
| Bandiera | Valore esadecimale | Descrizione |
|---|---|---|
| DCLOCATOR_MISC | 0x00000002 | Debug vari |
| 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 delle cassette postali dettagliati |
| DCLOCATOR_SITE_MORE | 0x08000000 | Siti verbose |
Eseguire il comando seguente per arrestare la sessione di traccia:
tracelog.exe -stop <nome sessione>
nome sessione corrisponde al nome usato durante l'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 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 |