NetJoinDomain 函数 (lmjoin.h)

项目
08/24/2023

NetJoinDomain 函数将计算机加入工作组或域。

语法

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

parameters

[in] lpServer

指向常量字符串的指针，该字符串指定要在其中执行域加入操作的计算机的 DNS 或 NetBIOS 名称。如果此参数为 NULL，则使用本地计算机。

[in] lpDomain

指向常量以 null 结尾的字符串的指针，该字符串指定要加入的域或工作组的名称。

（可选）可以指定首选域控制器来执行联接操作。在此实例中，字符串必须采用 DomainName\MachineName 的形式，其中 DomainName 是要加入的域的名称， MachineName 是执行联接的域控制器的名称。

[in] lpMachineAccountOU

（可选）指定指向常量以 null 结尾的字符串的指针，该字符串包含计算机帐户的组织单位 (OU) 的 RFC 1779 格式名称。如果指定此参数，字符串必须包含完整路径，例如 OU=testOU，DC=domain，DC=Domain，DC=com。否则，此参数必须为 NULL。

[in] lpAccount

指向以 null 结尾的常量字符串的指针，该字符串指定连接到域控制器时要使用的帐户名称。字符串必须指定域 NetBIOS 名称和用户帐户 (例如 REDMOND\user) ，或者用户主体名称 (UPN) ，其格式为 Internet 样式登录名 (例如“”someone@example.com) 。如果此参数为 NULL，则使用调用方上下文。

[in] lpPassword

如果 lpAccount 参数指定帐户名称，则此参数必须指向连接到域控制器时要使用的密码。否则，此参数必须为 NULL。

可以为不安全的加入指定本地计算机帐户密码，而不是用户密码。有关详细信息，请参阅 fJoinOptions 参数中描述的NETSETUP_MACHINE_PWD_PASSED标志的说明。

[in] fJoinOptions

定义联接选项的一组位标志。此参数可以是 Lmjoin.h 头文件中定义的以下一个或多个值。

值	含义
NETSETUP_JOIN_DOMAIN 0x00000001	将计算机加入域。如果未指定此值，则将计算机加入工作组。
NETSETUP_ACCT_CREATE 0x00000002	在域上创建帐户。
NETSETUP_WIN9X_UPGRADE 0x00000010	联接操作是在升级过程中发生的。
NETSETUP_DOMAIN_JOIN_IF_JOINED 0x00000020	允许加入新域，即使计算机已加入域。
NETSETUP_JOIN_UNSECURE 0x00000040	执行不安全的加入操作。此选项请求域加入到预先创建的帐户，而无需使用域用户凭据进行身份验证。此选项可与 NETSETUP_MACHINE_PWD_PASSED 选项结合使用。在这种情况下， lpPassword 是预创建的计算机帐户的密码。在 Windows Vista SP1 和 Windows Server 2008 之前，不安全的加入未向域控制器进行身份验证。所有通信都是使用 null (未经身份验证) 会话执行的。从 SP1 和 Windows Server 2008 的 Windows Vista 开始，计算机帐户名称和密码用于向域控制器进行身份验证。
NETSETUP_MACHINE_PWD_PASSED 0x00000080	指示 lpPassword 参数指定本地计算机帐户密码，而不是用户密码。此标志仅对不安全的联接有效，必须同时设置NETSETUP_JOIN_UNSECURE标志来指示该联接。如果设置此标志，则在联接操作成功后，如果值是有效的计算机密码，则计算机密码将设置为 lpPassword 的值。
NETSETUP_DEFER_SPN_SET 0x00000100	指示当前不应更新计算机对象上的服务主体名称 (SPN) 和 DnsHostName 属性。通常，这些属性在联接操作期间更新。相反，应在后续调用 NetRenameMachineInDomain 函数期间更新这些属性。这些属性在重命名操作期间始终更新。有关更多信息，请参见下面的“备注”部分。
NETSETUP_JOIN_DC_ACCOUNT 0x00000200	如果现有帐户是域控制器，则允许域加入。注意 Windows Vista 及更高版本支持此标志。
NETSETUP_JOIN_WITH_NEW_NAME 0x00000400	将 lpServer 参数中指定的目标计算机与在 lpServer 参数中指定的计算机上从注册表查询的新名称联接。如果在重启计算机之前已调用 SetComputerNameEx ，则使用此选项。在重新启动之前，新计算机名称不会生效。使用此选项，调用方指示 NetJoinDomain 函数在域加入操作期间使用新名称。成功调用 NetJoinDomain 后，需要重新启动，此时计算机名称更改和域成员身份更改都将受到影响。注意 Windows Vista 及更高版本支持此标志。
NETSETUP_JOIN_READONLY 0x00000800	使用预先创建的帐户加入 lpServer 参数中指定的目标计算机，而无需可写域控制器。如果帐户已预配并复制到只读域控制器，则此选项提供将计算机加入域的功能。目标只读域控制器指定为 lpDomain 参数的一部分，在域名后面用“\”字符分隔。此预配必须包含计算机机密。必须通过组成员身份将计算机帐户添加到密码复制策略的允许列表中，并且必须在加入操作之前将帐户密码复制到只读域控制器。有关详细信息，请参阅有关密码复制策略管理的信息。从 Windows 7 开始，另一种机制是使用脱机域加入机制。有关详细信息，请参阅 NetProvisionComputerAccount 和 NetRequestOfflineDomainJoin 函数。注意 Windows Vista 及更高版本支持此标志。
NETSETUP_AMBIGUOUS_DC 0x00001000	加入域时，不要尝试在注册表中设置首选域控制器。注意 Windows 7、Windows Server 2008 R2 及更高版本支持此标志。
NETSETUP_NO_NETLOGON_CACHE 0x00002000	加入域时，不会创建 Netlogon 缓存。注意 Windows 7、Windows Server 2008 R2 及更高版本支持此标志。
NETSETUP_DONT_CONTROL_SERVICES 0x00004000	加入域时，不强制 Netlogon 服务启动。注意 Windows 7、Windows Server 2008 R2 及更高版本支持此标志。
NETSETUP_SET_MACHINE_NAME 0x00008000	仅当加入域以便进行脱机加入时，请设置目标计算机主机名和 NetBIOS 名称。注意 Windows 7、Windows Server 2008 R2 及更高版本支持此标志。
NETSETUP_FORCE_SPN_SET 0x00010000	加入域时，请在加入域期间替代其他设置， (SPN) 设置服务主体名称。注意 Windows 7、Windows Server 2008 R2 及更高版本支持此标志。
NETSETUP_NO_ACCT_REUSE 0x00020000	加入域时，请勿重复使用现有帐户。注意 Windows 7、Windows Server 2008 R2 及更高版本支持此标志。
NETSETUP_IGNORE_UNSUPPORTED_FLAGS 0x10000000	如果设置了此位， NetJoinDomain 函数将忽略无法识别的标志， NetJoinDomain 的行为就像未设置标志一样。

返回值

如果函数成功，则返回值NERR_Success。

如果函数失败，则返回值可以是以下错误代码之一或系统错误代码之一。

返回代码	说明
ERROR_ACCESS_DENIED	拒绝访问。如果调用方不是目标计算机上的管理员本地组的成员，则返回此错误。
ERROR_INVALID_PARAMETER	参数不正确。如果 lpDomain 参数为 NULL，则返回此错误。
ERROR_NO_SUCH_DOMAIN	指定的域不存在。
ERROR_NOT_SUPPORTED	不支持该请求。如果 lpServer 参数中指定的计算机不支持在 fJoinOptions 参数中传递的某些选项，则返回此错误。
NERR_InvalidWorkgroupName	指定的工作组名称无效。
NERR_SetupAlreadyJoined	计算机已加入域。
NERR_WkstaNotStarted	工作站服务尚未启动。
RPC_S_CALL_IN_PROGRESS	此线程的远程过程调用已在进行中。
RPC_S_PROTSEQ_NOT_SUPPORTED	不支持远程过程调用协议序列。

注解

将 (和取消加入) 计算机加入域或工作组只能由目标计算机上的管理员本地组的成员执行。请注意，域管理员可以设置使用委派和特权分配加入域的其他要求。

如果远程调用 NetJoinDomain 函数，则必须提供凭据，因为在这种情况下无法委派凭据。

不同进程或同一进程的不同线程不应同时调用 NetJoinDomain 函数。这种情况会使计算机处于不一致状态。

如果在联接操作过程中遇到问题，则不应删除计算机帐户，并立即执行删除操作并尝试另一次加入。这可能会导致与复制相关的问题难以调查。删除计算机帐户时，请等待更改已复制到所有域控制器，然后再尝试另一个加入操作。

调用 NetJoinDomain 函数后，需要重新启动系统才能完成操作。

Windows Server 2003 和 Windows XP： 当在调用 NetRenameMachineInDomain 函数之前调用 NetJoinDomain 函数时，应将计算机对象上的 SPN 和 DnsHostName 属性的更新推迟到重命名操作。这是因为联接操作在某些情况下可能会失败。这种情况的一个示例是，派生自当前计算机名称的 SPN 在计算机正在加入的新域中无效，但从重命名操作后计算机将具有的新名称派生的 SPN 在新域中有效。在这种情况下，除非在调用 NetJoinDomain 时通过在 fJoinOptions 参数中指定NETSETUP_DEFER_SPN_SET标志，将两个属性的更新推迟到重命名操作，否则对 NetJoinDomain 的调用将失败。

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	lmjoin.h (包括 Lm.h)
Library	Netapi32.lib
DLL	Netapi32.dll