Função NetJoinDomain (lmjoin.h)

Artigo
08/24/2023

A função NetJoinDomain une um computador a um grupo de trabalho ou domínio.

Sintaxe

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

Parâmetros

[in] lpServer

Um ponteiro para uma cadeia de caracteres constante que especifica o nome DNS ou NetBIOS do computador no qual executar a operação de junção de domínio. Se esse parâmetro for NULL, o computador local será usado.

[in] lpDomain

Um ponteiro para uma cadeia de caracteres terminada em nulo constante que especifica o nome do domínio ou grupo de trabalho a ser unido.

Opcionalmente, você pode especificar o controlador de domínio preferencial para executar a operação de junção. Nessa instância, a cadeia de caracteres deve ser do formulário DomainName\MachineName, em que DomainName é o nome do domínio a ingressar e MachineName é o nome do controlador de domínio para executar a junção.

[in] lpMachineAccountOU

Opcionalmente, especifica o ponteiro para uma cadeia de caracteres terminada em nulo constante que contém o nome do formato RFC 1779 da UO (unidade organizacional) da conta de computador. Se você especificar esse parâmetro, a cadeia de caracteres deverá conter um caminho completo, por exemplo, OU=testOU,DC=domain,DC=Domain,DC=com. Caso contrário, esse parâmetro deve ser NULL.

[in] lpAccount

Um ponteiro para uma cadeia de caracteres terminada em nulo constante que especifica o nome da conta a ser usado ao se conectar ao controlador de domínio. A cadeia de caracteres deve especificar um nome netBIOS de domínio e uma conta de usuário (por exemplo, REDMOND\user) ou o nome upn do usuário na forma de um nome de logon no estilo da Internet (por exemplo, "someone@example.com"). Se esse parâmetro for NULL, o contexto do chamador será usado.

[in] lpPassword

Se o parâmetro lpAccount especificar um nome de conta, esse parâmetro deverá apontar para a senha a ser usada ao se conectar ao controlador de domínio. Caso contrário, esse parâmetro deve ser NULL.

Você pode especificar uma senha de conta de computador local em vez de uma senha de usuário para junções não seguras. Para obter mais informações, consulte a descrição do sinalizador NETSETUP_MACHINE_PWD_PASSED descrito no parâmetro fJoinOptions .

[in] fJoinOptions

Um conjunto de sinalizadores de bits definindo as opções de junção. Esse parâmetro pode ser um ou mais dos seguintes valores definidos no arquivo de cabeçalho Lmjoin.h .

Valor	Significado
NETSETUP_JOIN_DOMAIN 0x00000001	Une o computador a um domínio. Se esse valor não for especificado, unirá o computador a um grupo de trabalho.
NETSETUP_ACCT_CREATE 0x00000002	Cria a conta no domínio.
NETSETUP_WIN9X_UPGRADE 0x00000010	A operação de junção está ocorrendo como parte de uma atualização.
NETSETUP_DOMAIN_JOIN_IF_JOINED 0x00000020	Permite uma junção a um novo domínio mesmo que o computador já esteja ingressado em um domínio.
NETSETUP_JOIN_UNSECURE 0x00000040	Executa uma junção não segura. Essa opção solicita uma junção de domínio a uma conta pré-criada sem autenticar com credenciais de usuário de domínio. Essa opção pode ser usada em conjunto com NETSETUP_MACHINE_PWD_PASSED opção. Nesse caso, lpPassword é a senha da conta de computador pré-criada. Antes do Windows Vista com o SP1 e o Windows Server 2008, uma junção não se autenticava no controlador de domínio. Toda a comunicação foi executada usando uma sessão nula (não autenticada). A partir do Windows Vista com o SP1 e o Windows Server 2008, o nome da conta de computador e a senha são usados para autenticar no controlador de domínio.
NETSETUP_MACHINE_PWD_PASSED 0x00000080	Indica que o parâmetro lpPassword especifica uma senha de conta de computador local em vez de uma senha de usuário. Esse sinalizador é válido apenas para junções não asseguradas, que você deve indicar definindo também o sinalizador NETSETUP_JOIN_UNSECURE. Se você definir esse sinalizador, depois que a operação de junção for bem-sucedida, a senha do computador será definida como o valor de lpPassword, se esse valor for uma senha de computador válida.
NETSETUP_DEFER_SPN_SET 0x00000100	Indica que o SPN (nome da entidade de serviço) e as propriedades DnsHostName no objeto do computador não devem ser atualizados no momento. Normalmente, essas propriedades são atualizadas durante a operação de junção. Em vez disso, essas propriedades devem ser atualizadas durante uma chamada subsequente para a função NetRenameMachineInDomain . Essas propriedades são sempre atualizadas durante a operação de renomeação. Para obter mais informações, consulte a seção Comentários a seguir.
NETSETUP_JOIN_DC_ACCOUNT 0x00000200	Permita a junção de domínio se a conta existente for um controlador de domínio. Nota Esse sinalizador tem suporte no Windows Vista e posterior.
NETSETUP_JOIN_WITH_NEW_NAME 0x00000400	Junte o computador de destino especificado no parâmetro lpServer com um novo nome consultado do registro no computador especificado no parâmetro lpServer . Essa opção será usada se SetComputerNameEx tiver sido chamado antes de reiniciar o computador. O novo nome do computador não entrará em vigor até uma reinicialização. Com essa opção, o chamador instrui a função NetJoinDomain a usar o novo nome durante a operação de junção de domínio. Uma reinicialização é necessária depois de chamar NetJoinDomain com êxito, momento em que a alteração do nome do computador e a alteração da associação de domínio terão sido afetadas. Nota Esse sinalizador tem suporte no Windows Vista e posterior.
NETSETUP_JOIN_READONLY 0x00000800	Ingresse no computador de destino especificado no parâmetro lpServer usando uma conta pré-criada sem exigir um controlador de domínio gravável. Essa opção fornece a capacidade de ingressar um computador no domínio se uma conta já tiver sido provisionada e replicada para um controlador de domínio somente leitura. O controlador de domínio somente leitura de destino é especificado como parte do parâmetro lpDomain , após o nome de domínio delimitado por um caractere '\'. Esse provisionamento deve incluir o segredo do computador. A conta do computador deve ser adicionada por meio da associação de grupo à lista permitida para a política de replicação de senha e a senha da conta deve ser replicada para o controlador de domínio somente leitura antes da operação de junção. Para obter mais informações, consulte as informações sobre Administração de Política de Replicação de Senha. A partir do Windows 7, um mecanismo alternativo é usar o mecanismo de junção de domínio offline. Para obter mais informações, consulte as funções NetProvisionComputerAccount e NetRequestOfflineDomainJoin . Nota Esse sinalizador tem suporte no Windows Vista e posterior.
NETSETUP_AMBIGUOUS_DC 0x00001000	Ao ingressar no domínio, não tente definir o controlador de domínio preferencial no registro. Nota Esse sinalizador tem suporte no Windows 7, no Windows Server 2008 R2 e posterior.
NETSETUP_NO_NETLOGON_CACHE 0x00002000	Ao ingressar no domínio, não crie o cache do Netlogon. Nota Esse sinalizador tem suporte no Windows 7, no Windows Server 2008 R2 e posterior.
NETSETUP_DONT_CONTROL_SERVICES 0x00004000	Ao ingressar no domínio, não force o início do serviço Netlogon. Nota Esse sinalizador tem suporte no Windows 7, no Windows Server 2008 R2 e posterior.
NETSETUP_SET_MACHINE_NAME 0x00008000	Ao ingressar no domínio somente para junção offline, defina o nome do host do computador de destino e o nome do NetBIOS. Nota Esse sinalizador tem suporte no Windows 7, no Windows Server 2008 R2 e posterior.
NETSETUP_FORCE_SPN_SET 0x00010000	Ao ingressar no domínio, substitua outras configurações durante a junção de domínio e defina o SPN (nome da entidade de serviço). Nota Esse sinalizador tem suporte no Windows 7, no Windows Server 2008 R2 e posterior.
NETSETUP_NO_ACCT_REUSE 0x00020000	Ao ingressar no domínio, não reutilize uma conta existente. Nota Esse sinalizador tem suporte no Windows 7, no Windows Server 2008 R2 e posterior.
NETSETUP_IGNORE_UNSUPPORTED_FLAGS 0x10000000	Se esse bit for definido, os sinalizadores não reconhecidos serão ignorados pela função NetJoinDomain e NetJoinDomain se comportará como se os sinalizadores não estivessem definidos.

Valor retornado

Se a função for bem-sucedida, o valor retornado será NERR_Success.

Se a função falhar, o valor retornado poderá ser um dos seguintes códigos de erro ou um dos códigos de erro do sistema.

Código de retorno	Descrição
ERROR_ACCESS_DENIED	O acesso foi negado. Esse erro será retornado se o chamador não for membro do grupo local Administradores no computador de destino.
ERROR_INVALID_PARAMETER	Um parâmetro está incorreto. Esse erro será retornado se o parâmetro lpDomain for NULL.
ERROR_NO_SUCH_DOMAIN	O domínio especificado não existia.
ERROR_NOT_SUPPORTED	A solicitação não terá suporte. Esse erro será retornado se o computador especificado no parâmetro lpServer não oferecer suporte a algumas das opções passadas no parâmetro fJoinOptions .
NERR_InvalidWorkgroupName	O nome do grupo de trabalho especificado não é válido.
NERR_SetupAlreadyJoined	O computador já está ingressado em um domínio.
NERR_WkstaNotStarted	O serviço estação de trabalho não foi iniciado.
RPC_S_CALL_IN_PROGRESS	Uma chamada de procedimento remoto já está em andamento para esse thread.
RPC_S_PROTSEQ_NOT_SUPPORTED	Não há suporte para a sequência de protocolo de chamada de procedimento remoto.

Comentários

A junção (e descompossão) de um computador a um domínio ou grupo de trabalho só pode ser executada por um membro do grupo local Administradores no computador de destino. Observe que o administrador de domínio pode definir requisitos adicionais para ingressar no domínio usando delegação e atribuição de privilégios.

Se você chamar a função NetJoinDomain remotamente, deverá fornecer credenciais porque não é possível delegar credenciais nessas circunstâncias.

Processos diferentes ou threads diferentes do mesmo processo não devem chamar a função NetJoinDomain ao mesmo tempo. Essa situação pode deixar o computador em um estado inconsistente.

Se você encontrar um problema durante uma operação de junção, não deverá excluir uma conta de computador e seguir imediatamente a exclusão com outra tentativa de junção. Isso pode levar a problemas relacionados à replicação que são difíceis de investigar. Quando você excluir uma conta de computador, aguarde até que a alteração seja replicada para todos os controladores de domínio antes de tentar outra operação de junção.

Uma reinicialização do sistema é necessária depois de chamar a função NetJoinDomain para que a operação seja concluída.

Windows Server 2003 e Windows XP: Quando uma chamada para a função NetJoinDomain precede uma chamada para a função NetRenameMachineInDomain , você deve adiar a atualização das propriedades SPN e DnsHostName no objeto do computador até a operação de renomeação. Isso ocorre porque a operação de junção pode falhar em determinadas situações. Um exemplo dessa situação é quando o SPN derivado do nome do computador atual não é válido no novo domínio que o computador está ingressando, mas o SPN derivado do novo nome que o computador terá depois que a operação de renomeação for válida no novo domínio. Nessa situação, a chamada para NetJoinDomain falhará, a menos que você adie a atualização das duas propriedades até a operação de renomeação especificando o sinalizador NETSETUP_DEFER_SPN_SET no parâmetro fJoinOptions ao chamar NetJoinDomain.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	lmjoin.h (inclua Lm.h)
Biblioteca	Netapi32.lib
DLL	Netapi32.dll