Функция 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

При необходимости указывает указатель на константную строку символов, завершающуюся null, которая содержит имя в формате RFC 1779 подразделения для учетной записи компьютера. Если указать этот параметр, строка должна содержать полный путь, например OU=testOU,DC=domain,DC=Domain,DC=com. В противном случае этот параметр должен иметь значение NULL.

[in] lpAccount

Указатель на константную символьную строку, завершающуюся null, которая указывает имя учетной записи, используемое при подключении к контроллеру домена. В строке должно быть указано имя netBIOS домена и учетная запись пользователя (например, REDMOND\user) или имя участника-пользователя (UPN) пользователя в виде имени входа в интернет-стиле (например, "someone@example.com"). Если этот параметр имеет значение NULL, используется контекст вызывающего объекта.

[in] lpPassword

Если параметр lpAccount указывает имя учетной записи, этот параметр должен указывать на пароль, используемый при подключении к контроллеру домена. В противном случае этот параметр должен иметь значение NULL.

Для незащищенных соединений можно указать пароль учетной записи локального компьютера, а не пароль пользователя. Дополнительные сведения см. в описании флага NETSETUP_MACHINE_PWD_PASSED, описанном в параметре fJoinOptions .

[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 с пакетом обновления 1 (SP1) и Windows Server 2008 небезопасное присоединение не выполняло проверку подлинности на контроллере домена. Все обмен данными выполнялись с использованием сеанса со значением NULL (без проверки подлинности). Начиная с Windows Vista с пакетом обновления 1 (SP1) и Windows Server 2008, имя и пароль учетной записи компьютера используются для проверки подлинности на контроллере домена.
NETSETUP_MACHINE_PWD_PASSED 0x00000080	Указывает, что параметр lpPassword задает пароль учетной записи локального компьютера, а не пароль пользователя. Этот флаг действителен только для незащищенных соединений, которые необходимо указать, также задав флаг NETSETUP_JOIN_UNSECURE. Если этот флаг установлен, то после успешного объединения пароль компьютера будет установлен в значение lpPassword, если это значение является допустимым паролем компьютера.
NETSETUP_DEFER_SPN_SET 0x00000100	Указывает, что в данный момент не следует обновлять имя субъекта-службы и свойства 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: Когда вызов функции NetJoinDomain предшествует вызову функции NetRenameMachineInDomain , следует отложить обновление свойств SPN и DnsHostName объекта-компьютера до операции переименования. Это связано с тем, что операция соединения может завершиться сбоем в определенных ситуациях. Примером такой ситуации является ситуация, когда имя субъекта-службы, производное от текущего имени компьютера, не является допустимым в новом домене, к которому присоединен компьютер, но имя субъекта-службы, полученное от нового имени, которое будет иметь компьютер после операции переименования, является допустимым в новом домене. В этом случае вызов NetJoinDomain завершается ошибкой, если не отложить обновление двух свойств до операции переименования, указав флаг NETSETUP_DEFER_SPN_SET в параметре fJoinOptions при вызове NetJoinDomain.

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	lmjoin.h (включая Lm.h)
Библиотека	Netapi32.lib
DLL	Netapi32.dll