Função NetJoinDomain (lmjoin.h)
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 |
|---|---|
|
Une o computador a um domínio. Se esse valor não for especificado, unirá o computador a um grupo de trabalho. |
|
Cria a conta no domínio. |
|
A operação de junção está ocorrendo como parte de uma atualização. |
|
Permite uma junção a um novo domínio mesmo que o computador já esteja ingressado em um domínio. |
|
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. |
|
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. |
|
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. |
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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 |
|---|---|
|
O acesso foi negado. Esse erro será retornado se o chamador não for membro do grupo local Administradores no computador de destino. |
|
Um parâmetro está incorreto. Esse erro será retornado se o parâmetro lpDomain for NULL. |
|
O domínio especificado não existia. |
|
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 . |
|
O nome do grupo de trabalho especificado não é válido. |
|
O computador já está ingressado em um domínio. |
|
O serviço estação de trabalho não foi iniciado. |
|
Uma chamada de procedimento remoto já está em andamento para esse thread. |
|
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 |
Confira também
NetRemoveAlternateComputerName
NetRequestProvisioningPackageInstall
Funções de gerenciamento de rede
Visão geral do gerenciamento de rede