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

參數

[in] lpServer

常數位符串的指標，指定要在其中執行網域加入作業之電腦的 DNS 或 NetBIOS 名稱。如果此參數為 Null，則會使用本機電腦。

[in] lpDomain

常數 Null 終止字元字串的指標，指定要加入之網域或工作組的名稱。

您可以選擇性地指定要執行聯結作業的慣用網域控制站。在此實例中，字串的格式必須是 DomainName\MachineName，其中 DomainName 是要加入的網功能變數名稱稱，而 MachineName 是執行聯結的網域控制站名稱。

[in] lpMachineAccountOU

選擇性地指定包含電腦帳戶之組織單位之 RFC 1779 格式名稱的常數 Null 終止字元字串指標， (OU) 。如果您指定此參數，字串必須包含完整路徑，例如 OU=testOU，DC=domain，DC=Domain，DC=com。否則，此參數必須是 Null。

[in] lpAccount

常數 Null 終止字元字串的指標，指定連接到網域控制站時要使用的帳戶名稱。字串必須指定網域 NetBIOS 名稱和使用者帳戶 (，例如 REDMOND\user) ，或是使用者主體名稱 (UPN) 的使用者主體名稱， (例如「 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 (未經驗證) 會話來執行。從 WINDOWS Vista SP1 和 Windows Server 2008 開始，電腦帳戶名稱和密碼會用來向網域控制站進行驗證。
NETSETUP_MACHINE_PWD_PASSED 0x00000080	指出 lpPassword 參數指定本機電腦帳戶密碼，而不是使用者密碼。此旗標僅適用于不安全的聯結，您必須同時設定NETSETUP_JOIN_UNSECURE旗標來表示。如果您設定此旗標，則在聯結作業成功之後，如果該值是有效的電腦密碼，則電腦密碼會設定為 lpPassword的值。
NETSETUP_DEFER_SPN_SET 0x00000100	表示目前不應該更新電腦物件上 SPN (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	存取遭到拒絕。如果呼叫端不是目的電腦上的 Administrators 本機群組成員，就會傳回此錯誤。
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	不支援遠端程序呼叫通訊協定序列。

備註

將 (和取消加入) 電腦加入網域或工作組，只能由目的電腦上的 Administrators 本機群組成員執行。請注意，網域系統管理員可以使用委派和指派許可權來設定加入網域的其他需求。

如果您從遠端呼叫 NetJoinDomain 函式，您必須提供認證，因為您無法在這些情況下委派認證。

相同進程的不同進程或不同執行緒不應該同時呼叫 NetJoinDomain 函式。這種情況可能會讓電腦處於不一致的狀態。

如果您在聯結作業期間遇到問題，則不應該刪除電腦帳戶，並立即依照刪除作業進行另一個聯結嘗試。這可能會導致難以調查的複寫相關問題。當您刪除電腦帳戶時，請先等到變更複寫到所有網域控制站，再嘗試另一個加入作業。

呼叫 NetJoinDomain 函式之後需要系統重新開機，才能完成作業。

Windows Server 2003 和 Windows XP： 呼叫 NetJoinDomain 函式之前呼叫 NetRenameMachineInDomain 函式時，您應該延遲更新電腦物件上的 SPN 和 DnsHostName 屬性，直到重新命名作業為止。這是因為聯結作業在某些情況下可能會失敗。這類情況的範例是，從目前電腦名稱稱衍生的 SPN 在電腦加入的新網域中無效，但衍生自電腦在重新命名作業有效之後，從新名稱衍生的 SPN 無效。在此情況下，除非您在呼叫NetJoinDomain 時指定 fJoinOptions參數中的 NETSETUP_DEFER_SPN_SET 旗標，以延遲兩個屬性的更新，否則呼叫NetJoinDomain會失敗。

需求


最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	lmjoin.h (包含 Lm.h)
程式庫	Netapi32.lib
Dll	Netapi32.dll