Función NetJoinDomain (lmjoin.h)

Artículo
08/24/2023

La función NetJoinDomain une un equipo a un grupo de trabajo o dominio.

Sintaxis

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

Puntero a una cadena constante que especifica el nombre DNS o NetBIOS del equipo en el que se va a ejecutar la operación de unión a un dominio. Si este parámetro es NULL, se usa el equipo local.

[in] lpDomain

Puntero a una cadena de caracteres terminada en NULL constante que especifica el nombre del dominio o grupo de trabajo que se va a unir.

Opcionalmente, puede especificar el controlador de dominio preferido para realizar la operación de combinación. En este caso, la cadena debe tener el formato DomainName\MachineName, donde DomainName es el nombre del dominio que se va a unir y MachineName es el nombre del controlador de dominio para realizar la combinación.

[in] lpMachineAccountOU

Opcionalmente, especifica el puntero a una cadena de caracteres terminada en NULL constante que contiene el nombre de formato RFC 1779 de la unidad organizativa (OU) para la cuenta de equipo. Si especifica este parámetro, la cadena debe contener una ruta de acceso completa, por ejemplo, OU=testOU,DC=domain,DC=Domain,DC=com. De lo contrario, este parámetro debe ser NULL.

[in] lpAccount

Puntero a una cadena de caracteres terminada en null constante que especifica el nombre de cuenta que se va a usar al conectarse al controlador de dominio. La cadena debe especificar un nombre netBIOS de dominio y una cuenta de usuario (por ejemplo, REDMOND\user) o el nombre principal de usuario (UPN) del usuario en forma de nombre de inicio de sesión de estilo Internet (por ejemplo, "someone@example.com"). Si este parámetro es NULL, se usa el contexto del autor de la llamada.

[in] lpPassword

Si el parámetro lpAccount especifica un nombre de cuenta, este parámetro debe apuntar a la contraseña que se usará al conectarse al controlador de dominio. De lo contrario, este parámetro debe ser NULL.

Puede especificar una contraseña de cuenta de equipo local en lugar de una contraseña de usuario para combinaciones no seguras. Para obtener más información, vea la descripción de la marca NETSETUP_MACHINE_PWD_PASSED descrita en el parámetro fJoinOptions .

[in] fJoinOptions

Conjunto de marcas de bits que definen las opciones de combinación. Este parámetro puede ser uno o varios de los siguientes valores definidos en el archivo de encabezado Lmjoin.h .

Valor	Significado
NETSETUP_JOIN_DOMAIN 0x00000001	Une el equipo a un dominio. Si no se especifica este valor, une el equipo a un grupo de trabajo.
NETSETUP_ACCT_CREATE 0x00000002	Crea la cuenta en el dominio.
NETSETUP_WIN9X_UPGRADE 0x00000010	La operación de combinación se está produciendo como parte de una actualización.
NETSETUP_DOMAIN_JOIN_IF_JOINED 0x00000020	Permite una unión a un nuevo dominio incluso si el equipo ya está unido a un dominio.
NETSETUP_JOIN_UNSECURE 0x00000040	realiza una unión no segura. Esta opción solicita una unión de dominio a una cuenta creada previamente sin autenticarse con credenciales de usuario de dominio. Esta opción se puede usar junto con NETSETUP_MACHINE_PWD_PASSED opción. En este caso, lpPassword es la contraseña de la cuenta de máquina creada previamente. Antes de Windows Vista con SP1 y Windows Server 2008, una combinación no segura no se autenticaba en el controlador de dominio. Toda la comunicación se realizó mediante una sesión nula (sin autenticar). A partir de Windows Vista con SP1 y Windows Server 2008, el nombre de la cuenta de equipo y la contraseña se usan para autenticarse en el controlador de dominio.
NETSETUP_MACHINE_PWD_PASSED 0x00000080	Indica que el parámetro lpPassword especifica una contraseña de cuenta de equipo local en lugar de una contraseña de usuario. Esta marca solo es válida para combinaciones no seguros, que debe indicar estableciendo también la marca de NETSETUP_JOIN_UNSECURE. Si establece esta marca, después de que la operación de combinación se realice correctamente, la contraseña del equipo se establecerá en el valor de lpPassword, si ese valor es una contraseña de máquina válida.
NETSETUP_DEFER_SPN_SET 0x00000100	Indica que el nombre de la entidad de seguridad de servicio (SPN) y las propiedades DnsHostName del objeto de equipo no deben actualizarse en este momento. Normalmente, estas propiedades se actualizan durante la operación de combinación. En su lugar, estas propiedades deben actualizarse durante una llamada posterior a la función NetRenameMachineInDomain . Estas propiedades siempre se actualizan durante la operación de cambio de nombre. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
NETSETUP_JOIN_DC_ACCOUNT 0x00000200	Permita la unión a un dominio si la cuenta existente es un controlador de dominio. Nota Esta marca se admite en Windows Vista y versiones posteriores.
NETSETUP_JOIN_WITH_NEW_NAME 0x00000400	Una la máquina de destino especificada en el parámetro lpServer con un nuevo nombre consultado desde el registro en el equipo especificado en el parámetro lpServer . Esta opción se usa si se ha llamado a SetComputerNameEx antes de reiniciar la máquina. El nuevo nombre de equipo no surtirá efecto hasta que se reinicie. Con esta opción, el autor de la llamada indica a la función NetJoinDomain que use el nuevo nombre durante la operación de unión a un dominio. Se requiere un reinicio después de llamar a NetJoinDomain correctamente en el momento en que el cambio de nombre del equipo y el cambio de pertenencia al dominio tendrán efecto. Nota Esta marca se admite en Windows Vista y versiones posteriores.
NETSETUP_JOIN_READONLY 0x00000800	Una la máquina de destino especificada en el parámetro lpServer mediante una cuenta creada previamente sin necesidad de un controlador de dominio grabable. Esta opción proporciona la capacidad de unir una máquina a un dominio si ya se ha aprovisionado y replicado una cuenta en un controlador de dominio de solo lectura. El controlador de dominio de solo lectura de destino se especifica como parte del parámetro lpDomain , después del nombre de dominio delimitado por un carácter "\". Este aprovisionamiento debe incluir el secreto de la máquina. La cuenta de máquina debe agregarse a través de la pertenencia a grupos en la lista de permitidos para la directiva de replicación de contraseñas y la contraseña de la cuenta debe replicarse en el controlador de dominio de solo lectura antes de la operación de unión. Para obtener más información, consulte la información sobre la administración de directivas de replicación de contraseñas. A partir de Windows 7, un mecanismo alternativo consiste en usar el mecanismo de unión a un dominio sin conexión. Para obtener más información, consulte las funciones NetProvisionComputerAccount y NetRequestOfflineDomainJoin . Nota Esta marca se admite en Windows Vista y versiones posteriores.
NETSETUP_AMBIGUOUS_DC 0x00001000	Al unir el dominio, no intente establecer el controlador de dominio preferido en el Registro. Nota Esta marca se admite en Windows 7, Windows Server 2008 R2 y versiones posteriores.
NETSETUP_NO_NETLOGON_CACHE 0x00002000	Al unir el dominio, no cree la memoria caché de Netlogon. Nota Esta marca se admite en Windows 7, Windows Server 2008 R2 y versiones posteriores.
NETSETUP_DONT_CONTROL_SERVICES 0x00004000	Cuando se une al dominio, no se fuerza el inicio del servicio Netlogon. Nota Esta marca se admite en Windows 7, Windows Server 2008 R2 y versiones posteriores.
NETSETUP_SET_MACHINE_NAME 0x00008000	Al unir el dominio solo para la unión sin conexión, establezca el nombre de host de la máquina de destino y el nombre netBIOS. Nota Esta marca se admite en Windows 7, Windows Server 2008 R2 y versiones posteriores.
NETSETUP_FORCE_SPN_SET 0x00010000	Al unir el dominio, invalide otras opciones de configuración durante la unión al dominio y establezca el nombre de entidad de seguridad de servicio (SPN). Nota Esta marca se admite en Windows 7, Windows Server 2008 R2 y versiones posteriores.
NETSETUP_NO_ACCT_REUSE 0x00020000	Al unir el dominio, no vuelva a usar una cuenta existente. Nota Esta marca se admite en Windows 7, Windows Server 2008 R2 y versiones posteriores.
NETSETUP_IGNORE_UNSUPPORTED_FLAGS 0x10000000	Si se establece este bit, la función NetJoinDomain omitirá las marcas no reconocidas y NetJoinDomain se comportará como si no se hubieran establecido las marcas.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto se NERR_Success.

Si se produce un error en la función, el valor devuelto puede ser uno de los siguientes códigos de error o uno de los códigos de error del sistema.

Código devuelto	Descripción
ERROR_ACCESS_DENIED	Se denegó el acceso. Este error se devuelve si el autor de la llamada no era miembro del grupo local Administradores en el equipo de destino.
ERROR_INVALID_PARAMETER	Un parámetro es incorrecto. Este error se devuelve si el parámetro lpDomain es NULL.
ERROR_NO_SUCH_DOMAIN	El dominio especificado no existía.
ERROR_NOT_SUPPORTED	No se admite la solicitud. Este error se devuelve si el equipo especificado en el parámetro lpServer no admite algunas de las opciones pasadas en el parámetro fJoinOptions .
NERR_InvalidWorkgroupName	El nombre del grupo de trabajo especificado no es válido.
NERR_SetupAlreadyJoined	El equipo ya está unido a un dominio.
NERR_WkstaNotStarted	No se ha iniciado el servicio Workstation.
RPC_S_CALL_IN_PROGRESS	Ya hay una llamada a procedimiento remoto en curso para este subproceso.
RPC_S_PROTSEQ_NOT_SUPPORTED	No se admite la secuencia de protocolo de llamada a procedimiento remoto.

Comentarios

La unión (y desenlazamiento) de un equipo a un dominio o grupo de trabajo solo la puede realizar un miembro del grupo local Administradores en el equipo de destino. Tenga en cuenta que el administrador de dominio puede establecer requisitos adicionales para unir el dominio mediante la delegación y la asignación de privilegios.

Si llama a la función NetJoinDomain de forma remota, debe proporcionar credenciales porque no puede delegar las credenciales en estas circunstancias.

Los distintos procesos, o subprocesos diferentes del mismo proceso, no deben llamar a la función NetJoinDomain al mismo tiempo. Esta situación puede dejar el equipo en un estado incoherente.

Si se produce un problema durante una operación de unión, no debe eliminar una cuenta de equipo y seguir inmediatamente la eliminación con otro intento de combinación. Esto puede provocar problemas relacionados con la replicación que son difíciles de investigar. Al eliminar una cuenta de equipo, espere hasta que el cambio se haya replicado en todos los controladores de dominio antes de intentar otra operación de unión.

Se requiere un reinicio del sistema después de llamar a la función NetJoinDomain para que se complete la operación.

Windows Server 2003 y Windows XP: Cuando una llamada a la función NetJoinDomain precede a una llamada a la función NetRenameMachineInDomain , debe aplazar la actualización de las propiedades SPN y DnsHostName en el objeto de equipo hasta la operación de cambio de nombre. Esto se debe a que la operación de combinación puede producir un error en determinadas situaciones. Un ejemplo de esta situación es cuando el SPN que se deriva del nombre de equipo actual no es válido en el nuevo dominio al que se une el equipo, pero el SPN derivado del nuevo nombre que tendrá el equipo después de que la operación de cambio de nombre sea válida en el nuevo dominio. En esta situación, se produce un error en la llamada a NetJoinDomain a menos que aplaza la actualización de las dos propiedades hasta que se especifique la marca de NETSETUP_DEFER_SPN_SET en el parámetro fJoinOptions al llamar a NetJoinDomain.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	lmjoin.h (include Lm.h)
Library	Netapi32.lib
Archivo DLL	Netapi32.dll