Funzione NetJoinDomain (lmjoin.h)

Articolo
08/24/2023

La funzione NetJoinDomain aggiunge un computer a un gruppo di lavoro o a un dominio.

Sintassi

NET_API_STATUS NET_API_FUNCTION NetJoinDomain(
  [in] LPCWSTR lpServer,
  [in] LPCWSTR lpDomain,
  [in] LPCWSTR lpMachineAccountOU,
  [in] LPCWSTR lpAccount,
  [in] LPCWSTR lpPassword,
  [in] DWORD   fJoinOptions
);

Parametri

[in] lpServer

Puntatore a una stringa costante che specifica il nome DNS o NetBIOS del computer in cui eseguire l'operazione di aggiunta al dominio. Se questo parametro è NULL, viene utilizzato il computer locale.

[in] lpDomain

Puntatore a una stringa di caratteri con terminazione Null costante che specifica il nome del dominio o del gruppo di lavoro da aggiungere.

Facoltativamente, è possibile specificare il controller di dominio preferito per eseguire l'operazione di aggiunta. In questa istanza, la stringa deve essere nel formato NomeDominio\MachineName, dove DomainName è il nome del dominio da aggiungere e MachineName è il nome del controller di dominio per eseguire l'aggiunta.

[in] lpMachineAccountOU

Facoltativamente, specifica il puntatore a una stringa di caratteri con terminazione Null costante contenente il nome di formato RFC 1779 dell'unità organizzativa per l'account computer. Se si specifica questo parametro, la stringa deve contenere un percorso completo, ad esempio OU=testOU,DC=domain,DC=Domain,DC=com. In caso contrario, questo parametro deve essere NULL.

[in] lpAccount

Puntatore a una stringa di caratteri con terminazione Null costante che specifica il nome dell'account da utilizzare per la connessione al controller di dominio. La stringa deve specificare un nome NetBIOS di dominio e un account utente (ad esempio , REDMOND\user) o il nome dell'entità utente (UPN) dell'utente sotto forma di nome di accesso in stile Internet ,ad esempio "someone@example.com". Se questo parametro è NULL, viene usato il contesto del chiamante.

[in] lpPassword

Se il parametro lpAccount specifica un nome di account, questo parametro deve puntare alla password da usare per la connessione al controller di dominio. In caso contrario, questo parametro deve essere NULL.

È possibile specificare una password dell'account del computer locale anziché una password utente per i join non protetti. Per altre informazioni, vedere la descrizione del flag NETSETUP_MACHINE_PWD_PASSED descritto nel parametro fJoinOptions .

[in] fJoinOptions

Set di flag di bit che definiscono le opzioni di join. Questo parametro può essere uno o più dei valori seguenti definiti nel file di intestazione Lmjoin.h .

Valore	Significato
NETSETUP_JOIN_DOMAIN 0x00000001	Aggiunge il computer a un dominio. Se questo valore non viene specificato, aggiunge il computer a un gruppo di lavoro.
NETSETUP_ACCT_CREATE 0x00000002	Crea l'account nel dominio.
NETSETUP_WIN9X_UPGRADE 0x00000010	L'operazione di join viene eseguita come parte di un aggiornamento.
NETSETUP_DOMAIN_JOIN_IF_JOINED 0x00000020	Consente l'aggiunta a un nuovo dominio anche se il computer è già aggiunto a un dominio.
NETSETUP_JOIN_UNSECURE 0x00000040	esegue un join non sicuro. Questa opzione richiede l'aggiunta a un dominio a un account creato in modo preliminare senza eseguire l'autenticazione con le credenziali utente di dominio. Questa opzione può essere usata insieme all'opzione NETSETUP_MACHINE_PWD_PASSED . In questo caso , lpPassword è la password dell'account computer creato in modo preliminare. Prima di Windows Vista con SP1 e Windows Server 2008, un join non sicuro non è stato autenticato nel controller di dominio. Tutte le comunicazioni sono state eseguite usando una sessione null (non autenticata). A partire da Windows Vista con SP1 e Windows Server 2008, il nome e la password dell'account del computer vengono usati per eseguire l'autenticazione al controller di dominio.
NETSETUP_MACHINE_PWD_PASSED 0x00000080	Indica che il parametro lpPassword specifica una password dell'account del computer locale anziché una password utente. Questo flag è valido solo per i join non protetti, che è necessario indicare impostando anche il flag di NETSETUP_JOIN_UNSECURE. Se si imposta questo flag, al termine dell'operazione di join, la password del computer verrà impostata sul valore di lpPassword, se tale valore è una password del computer valida.
NETSETUP_DEFER_SPN_SET 0x00000100	Indica che il nome dell'entità servizio (SPN) e le proprietà DnsHostName nell'oggetto computer non devono essere aggiornate in questo momento. In genere, queste proprietà vengono aggiornate durante l'operazione di join. Queste proprietà devono invece essere aggiornate durante una chiamata successiva alla funzione NetRenameMachineInDomain . Queste proprietà vengono sempre aggiornate durante l'operazione di ridenominazione. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
NETSETUP_JOIN_DC_ACCOUNT 0x00000200	Consentire l'aggiunta al dominio se l'account esistente è un controller di dominio. Nota Questo flag è supportato in Windows Vista e versioni successive.
NETSETUP_JOIN_WITH_NEW_NAME 0x00000400	Aggiungere il computer di destinazione specificato nel parametro lpServer con un nuovo nome sottoposto a query dal Registro di sistema nel computer specificato nel parametro lpServer . Questa opzione viene utilizzata se SetComputerNameEx è stato chiamato prima del riavvio del computer. Il nuovo nome computer non avrà effetto fino a quando non verrà riavviato. Con questa opzione, il chiamante indica alla funzione NetJoinDomain di usare il nuovo nome durante l'operazione di aggiunta al dominio. Un riavvio è necessario dopo aver chiamato NetJoinDomain correttamente al momento in cui la modifica del nome del computer e la modifica dell'appartenenza al dominio avranno effetto. Nota Questo flag è supportato in Windows Vista e versioni successive.
NETSETUP_JOIN_READONLY 0x00000800	Aggiungere il computer di destinazione specificato nel parametro lpServer usando un account creato in precedenza senza richiedere un controller di dominio scrivibile. Questa opzione consente di aggiungere un computer al dominio se è già stato effettuato il provisioning e la replica di un account in un controller di dominio di sola lettura. Il controller di dominio di sola lettura di destinazione viene specificato come parte del parametro lpDomain , dopo il nome di dominio delimitato da un carattere '\'. Questo provisioning deve includere il segreto del computer. L'account del computer deve essere aggiunto tramite l'appartenenza al gruppo nell'elenco consentito per i criteri di replica delle password e la password dell'account deve essere replicata nel controller di dominio di sola lettura prima dell'operazione di aggiunta. Per altre informazioni, vedere le informazioni sull'amministrazione dei criteri di replica delle password. A partire da Windows 7, un meccanismo alternativo consiste nell'usare il meccanismo di aggiunta a un dominio offline. Per altre informazioni, vedere le funzioni NetProvisionComputerAccount e NetRequestOfflineDomainJoin . Nota Questo flag è supportato in Windows Vista e versioni successive.
NETSETUP_AMBIGUOUS_DC 0x00001000	Quando si aggiunge al dominio non si tenta di impostare il controller di dominio preferito nel Registro di sistema. Nota Questo flag è supportato in Windows 7, Windows Server 2008 R2 e versioni successive.
NETSETUP_NO_NETLOGON_CACHE 0x00002000	Quando si aggiunge al dominio non viene creata la cache Netlogon. Nota Questo flag è supportato in Windows 7, Windows Server 2008 R2 e versioni successive.
NETSETUP_DONT_CONTROL_SERVICES 0x00004000	Quando si aggiunge al dominio non viene forzato l'avvio del servizio Netlogon. Nota Questo flag è supportato in Windows 7, Windows Server 2008 R2 e versioni successive.
NETSETUP_SET_MACHINE_NAME 0x00008000	Quando si aggiunge il dominio solo per l'aggiunta offline, impostare il nome host del computer di destinazione e il nome NetBIOS. Nota Questo flag è supportato in Windows 7, Windows Server 2008 R2 e versioni successive.
NETSETUP_FORCE_SPN_SET 0x00010000	Quando si aggiunge il dominio, eseguire l'override di altre impostazioni durante l'aggiunta al dominio e impostare il nome dell'entità servizio (SPN). Nota Questo flag è supportato in Windows 7, Windows Server 2008 R2 e versioni successive.
NETSETUP_NO_ACCT_REUSE 0x00020000	Quando si aggiunge il dominio, non riutilizzare un account esistente. Nota Questo flag è supportato in Windows 7, Windows Server 2008 R2 e versioni successive.
NETSETUP_IGNORE_UNSUPPORTED_FLAGS 0x10000000	Se questo bit è impostato, i flag non riconosciuti verranno ignorati dalla funzione NetJoinDomain e NetJoinDomain si comportano come se i flag non siano stati impostati.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è NERR_Success.

Se la funzione ha esito negativo, il valore restituito può essere uno dei codici di errore seguenti o uno dei codici di errore di sistema.

Codice restituito	Descrizione
ERROR_ACCESS_DENIED	Accesso negato. Questo errore viene restituito se il chiamante non è stato membro del gruppo locale Administrators nel computer di destinazione.
ERROR_INVALID_PARAMETER	Un parametro non è corretto. Questo errore viene restituito se il parametro lpDomain è NULL.
ERROR_NO_SUCH_DOMAIN	Il dominio specificato non esiste.
ERROR_NOT_SUPPORTED	La richiesta non è supportata. Questo errore viene restituito se il computer specificato nel parametro lpServer non supporta alcune delle opzioni passate nel parametro fJoinOptions .
NERR_InvalidWorkgroupName	Il nome del gruppo di lavoro specificato non è valido.
NERR_SetupAlreadyJoined	Il computer è già aggiunto a un dominio.
NERR_WkstaNotStarted	Il servizio Workstation non è stato avviato.
RPC_S_CALL_IN_PROGRESS	Una chiamata di procedura remota è già in corso per questo thread.
RPC_S_PROTSEQ_NOT_SUPPORTED	La sequenza di protocollo di chiamata alla routine remota non è supportata.

Commenti

L'aggiunta (e l'annullamento della partecipazione) di un computer a un dominio o a un gruppo di lavoro può essere eseguita solo da un membro del gruppo locale Administrators nel computer di destinazione. Si noti che l'amministratore del dominio può impostare requisiti aggiuntivi per l'aggiunta al dominio usando la delega e l'assegnazione dei privilegi.

Se si chiama la funzione NetJoinDomain in remoto, è necessario specificare le credenziali perché non è possibile delegare le credenziali in queste circostanze.

Processi diversi o thread diversi dello stesso processo, non devono chiamare la funzione NetJoinDomain contemporaneamente. Questa situazione può lasciare il computer in uno stato incoerente.

Se si verifica un problema durante un'operazione di join, non è consigliabile eliminare un account computer e seguire immediatamente l'eliminazione con un altro tentativo di join. Ciò può causare problemi correlati alla replica che sono difficili da analizzare. Quando si elimina un account computer, attendere fino a quando la modifica non è stata replicata in tutti i controller di dominio prima di tentare un'altra operazione di join.

È necessario un riavvio del sistema dopo aver chiamato la funzione NetJoinDomain per il completamento dell'operazione.

Windows Server 2003 e Windows XP: Quando una chiamata alla funzione NetJoinDomain precede una chiamata alla funzione NetRenameMachineInDomain , è necessario rinviare l'aggiornamento delle proprietà SPN e DnsHostName nell'oggetto computer fino all'operazione di ridenominazione. Questo perché l'operazione di join può non riuscire in determinate situazioni. Un esempio di tale situazione è quando il nome SPN derivato dal nome del computer corrente non è valido nel nuovo dominio a cui si aggiunge il computer, ma il nome SPN derivato dal nuovo nome che il computer avrà dopo che l'operazione di ridenominazione è valida nel nuovo dominio. In questa situazione, la chiamata a NetJoinDomain non riesce a meno che non si rinvii l'aggiornamento delle due proprietà fino a quando l'operazione di ridenominazione specificando il flag di NETSETUP_DEFER_SPN_SET nel parametro fJoinOptions quando si chiama NetJoinDomain.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	lmjoin.h (include Lm.h)
Libreria	Netapi32.lib
DLL	Netapi32.dll