Функция NetCreateProvisioningPackage (lmjoin.h)

Статья
03/14/2023

Функция NetCreateProvisioningPackage создает пакет подготовки, который подготавливает учетную запись компьютера для последующего использования в операции автономного присоединения к домену. Пакет также может содержать сведения о сертификатах и политиках, которые необходимо добавить на компьютер во время подготовки.

Синтаксис

NET_API_STATUS NET_API_FUNCTION NetCreateProvisioningPackage(
  [in]            PNETSETUP_PROVISIONING_PARAMS pProvisioningParams,
  [out, optional] PBYTE                         *ppPackageBinData,
  [out, optional] DWORD                         *pdwPackageBinDataSize,
  [out, optional] LPWSTR                        *ppPackageTextData
);

Параметры

[in] pProvisioningParams

Указатель на структуру NETSETUP_PROVISIONING_PARAMS , содержащую сведения о пакете подготовки.

Для членов этой структуры определяются следующие значения:

Значение	Значение
dwVersion	Версия Windows в пакете подготовки. Этот член должен использовать следующее значение, определенное в файле заголовка Lmjoin.h : NETSETUP_PROVISIONING_PARAMS_CURRENT_VERSION (0x00000001)
lpDomain	Указатель на константную символьную строку, завершающуюся значением NULL, которая указывает имя домена, в котором создается учетная запись компьютера.
lpMachineName	Указатель на константную символьную строку, завершающуюся null, которая указывает короткое имя компьютера, от которого извлекается атрибут учетной записи компьютера sAMAccountName путем добавления символа "$". Этот параметр должен содержать допустимое имя компьютера DNS или NetBIOS.
lpMachineAccountOU	Необязательный указатель на константную символьную строку, завершающуюся null, которая содержит имя формата RFC 1779 подразделения, в котором будет создана учетная запись компьютера. Если указать этот параметр, строка должна содержать полный путь, например OU=testOU,DC=domain,DC=Domain,DC=com. В противном случае этот параметр должен иметь значение NULL. Если этот параметр имеет значение NULL, будет использоваться хорошо известный контейнер объектов-компьютеров, опубликованный в домене.
lpDcName	Необязательный указатель на константную символьную строку, завершающуюся null, которая содержит имя целевого контроллера домена.
dwProvisionOptions	Набор битовых флагов, определяющих параметры подготовки. Этот параметр может быть одним или несколькими значениями, указанными для параметра dwOptions, передаваемого в функцию NetProvisionComputerAccount . Эти возможные значения определяются в файле заголовка Lmjoin.h . Параметр NETSETUP_PROVISION_ROOT_CA_CERTS поддерживается только в Windows 8 и Windows Server 2012.
aCertTemplateNames	Необязательный указатель на массив имен шаблонов сертификатов, завершаемых null.
cCertTemplateNames	Если параметруCertTemplateNames не задано значение NULL, этот элемент предоставляет явное количество элементов в массиве.
aMachinePolicyNames	Необязательный указатель на массив имен политик компьютеров, завершаемых значением NULL.
cMachinePolicyNames	Если значениеMachinePolicyNames не равно NULL, этот элемент предоставляет явное количество элементов в массиве.
aMachinePolicyPaths	Необязательный указатель на массив символьных строк. Каждый элемент массива представляет собой символьную строку с завершением NULL, которая указывает полный или частичный путь к файлу в формате файла политики реестра. Дополнительные сведения о формате файла политики реестра см. в разделе Формат файла политики реестра. Путь может быть UNC-путем на удаленном сервере.
cMachinePolicyPaths	Если значениеMachinePolicyPaths не равно NULL, этот элемент предоставляет явное количество элементов в массиве.

[out, optional] ppPackageBinData

Необязательный указатель, который получит пакет, необходимый функции NetRequestOfflineDomainJoin для завершения автономного присоединения к домену, если функция NetProvisionComputerAccount успешно завершена. Данные возвращаются в виде непрозрачного двоичного буфера, который может быть передан в функцию NetRequestOfflineDomainJoin .

Если этот параметр имеет значение NULL, параметр pPackageTextData не должен иметь значение NULL. Если этот параметр не имеет значение NULL, то параметр pPackageTextData должен иметь значение NULL.

[out, optional] pdwPackageBinDataSize

Указатель на значение, которое получает размер (в байтах) буфера, возвращаемого в параметре pProvisionBinData .

Этот параметр не должен иметь значение NULL , если параметр pPackageBinData не имеет значения NULL. Этот параметр должен иметь значение NULL , если параметр pPackageBinData имеет значение NULL.

[out, optional] ppPackageTextData

Необязательный указатель, который получит пакет, необходимый функции NetRequestOfflineDomainJoin для завершения автономного присоединения к домену, если функция NetProvisionComputerAccount успешно завершена. Данные возвращаются в строковой форме для внедрения в файл ответов автоматической установки.

Если этот параметр имеет значение NULL, параметр pPackageBinData не должен иметь значение NULL. Если этот параметр не имеет значение NULL, то параметр pPackageBinData должен иметь значение NULL.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение будет NERR_Success.

Если функция завершается сбоем, возвращаемым значением может быть один из следующих кодов ошибок или один из кодов системных ошибок.

Код возврата	Описание
ERROR_ACCESS_DENIED	Отказано в доступе". Эта ошибка возвращается, если вызывающий объект не имеет достаточных привилегий для завершения операции.
ERROR_INVALID_DOMAIN_ROLE	Эта операция разрешена только для основного контроллера домена. Эта ошибка возвращается, если имя контроллера домена было указано в lpDcName структуры NETSETUP_PROVISIONING_PARAMS , на которую указывает параметр pProvisioningParams , но указанный компьютер не может быть проверен как контроллер домена для целевого домена, указанного в lpDomainNETSETUP_PROVISIONING_PARAMS.
ERROR_INVALID_PARAMETER	Неправильный параметр. Эта ошибка также возвращается, если параметр pProvisioningParams имеет значение NULL. Эта ошибка также возвращается, если элемент lpDomain или lpMachineNameструктуры NETSETUP_PROVISIONING_PARAMS , на который указывает параметр pProvisioningParams , имеет значение NULL.
ERROR_NO_SUCH_DOMAIN	Указанный домен не существует.
ERROR_NOT_SUPPORTED	Запрос не поддерживается. Эта ошибка возвращается, если член lpMachineAccountOU был указан в структуре NETSETUP_PROVISIONING_PARAMS , на которую указывает параметр pProvisioningParams , и контроллер домена работает в более ранних версиях Windows, которые не поддерживают этот параметр.
NERR_DS8DCRequired	Указанный контроллер домена не соответствует требованиям к версии для этой операции.
NERR_LDAPCapableDCRequired	Для этой операции требуется контроллер домена, поддерживающий протокол LDAP.
NERR_UserExists	Учетная запись уже существует в домене, и бит NETSETUP_PROVISION_REUSE_ACCOUNT не был указан в элементе dwProvisionOptionsструктуры NETSETUP_PROVISIONING_PARAMS , на которую указывает параметр pProvisioningParams .
NERR_WkstaNotStarted	Служба рабочей станции не запущена.
RPC_S_CALL_IN_PROGRESS	Удаленный вызов процедуры для этого потока уже выполняется.
RPC_S_PROTSEQ_NOT_SUPPORTED	Последовательность протокола удаленного вызова процедур не поддерживается.

Функция NetCreateProvisioningPackage используется для подготовки учетной записи компьютера для последующего использования в операции автономного присоединения к домену с помощью функции NetRequestProvisioningPackageInstall .

Сценарий автономного присоединения к домену использует две функции:

NetCreateProvisioningPackage — это функция подготовки, которая сначала вызывается для выполнения сетевых операций, необходимых для создания и настройки объекта-компьютера в Active Directory. Выходные данные netCreateProvisioningPackage — это пакет, используемый для следующего шага.
NetRequestProvisioningPackageInstall, функция инициализации образа, вызывается для внедрения выходных данных функции подготовки NetCreateProvisioningPackage в образ операционной системы Windows для использования во время предварительной и последующей установки.

Изменения в коде инициализации Windows обнаруживают это сохраненное состояние и влияют на локальную часть присоединения к домену.

При использовании указателей pPackageBinData и pdwPackageBinDataSize задайте для указателя pPackageTextData out значение NULL. При использовании pPackageTextData задайте для указателей pPackageBinData и pdwPackageBinDataSize значение NULL.

Параметр pProvisioningParams указывает данные для включения в пакет подготовки. Пакет содержит сведения, относящиеся к присоединению к домену, а также сведения о политиках и сертификатах для установки на компьютере. Пакет подготовки можно использовать четырьмя способами:

Присоединение к домену
Присоединение к домену и установка сертификатов
Присоединение к домену и установка политик
Присоединение к домену и установка сертификатов и политик

Функция NetCreateProvisioningPackage создает или повторно использует учетную запись компьютера в домене, собирает все необходимые метаданные и возвращает их в пакете. Пакет может быть использован операцией запроса автономного присоединения к домену, предоставляя все необходимые входные данные для завершения присоединения к домену во время первой загрузки без каких-либо сетевых операций (только обновления локального состояния).

Примечание по безопасности: Пакет, возвращаемый функцией NetCreateProvisioningPackage , содержит очень конфиденциальные данные. Он должен рассматриваться так же безопасно, как пароль в виде открытого текста. Пакет содержит пароль учетной записи компьютера и другие сведения о домене, включая доменное имя, имя контроллера домена и идентификатор безопасности (SID) домена. Если пакет транспортируется физически или по сети, необходимо соблюдать осторожность для его безопасной транспортировки. Проект не предусматривает никаких положений для защиты этих данных. Эта проблема возникает в настоящее время с файлами ответов автоматической установки, которые могут содержать ряд секретов, включая пароли пользователей домена. Вызывающий объект должен защитить пакет. Решения этой проблемы разнообразны. Например, для шифрования сеанса между потребителем и сущностью подготовки можно использовать предварительно обменивающийся ключ, обеспечивающий безопасную передачу пакета.

Пакет, возвращаемый в параметре pPackageBinData функцией NetCreateProvisioningPackage , имеет версию, чтобы обеспечить взаимодействие и удобство обслуживания между разными версиями Windows (например, присоединение клиента, подготовка компьютера и использование контроллера домена). Пакет, созданный в Windows 8 или Windows Server 2012, можно использовать Windows 7 или Windows Server 2008 R2, однако вступают в силу только сведения о присоединении к домену (сертификаты и политики не поддерживаются). Сценарий автономного присоединения в настоящее время не ограничивает время существования пакета, возвращаемого функцией NetCreateProvisioningPackage .

При автономном присоединении к домену проверка доступа зависит от конфигурации домена. Создание учетной записи компьютера включено тремя способами:

Администраторы домена имеют права на создание учетных записей компьютеров.
Sd в контейнере может делегировать права на создание учетных записей компьютеров.
По умолчанию пользователи, прошедшие проверку подлинности, могут создавать учетные записи компьютеров по привилегиям. Пользователи, прошедшие проверку подлинности, могут создавать ограниченное количество учетных записей, указанных в качестве квоты в домене (значение по умолчанию — 10). Дополнительные сведения см. в описании атрибута ms-DS-MachineAccountQuota в схеме Active Directory.

Функция NetCreateProvisioningPackage работает только с контроллером домена, доступного для записи, и не работает с контроллером домена только для чтения. После того как подготовка выполняется для контроллера домена, доступного для записи, и учетная запись реплицируется на контроллер домена только для чтения, другие части операции автономного присоединения к домену не требуют доступа к контроллеру домена.

При успешном выполнении функции NetCreateProvisioningPackage указатель в параметре pPackageBinData или pPackageTextData (в зависимости от того, какой параметр не имеет значения NULL) возвращается с сериализованными данными для использования в операции автономного соединения или в виде текста в файле автоматической установки.

Все этапы процесса подготовки добавляются к файлу NetSetup.log на локальном компьютере. Процесс подготовки может включать до трех разных компьютеров: компьютер, на котором создается пакет подготовки, компьютер, запрашивающий установку пакета, и компьютер, на котором установлен пакет. На всех трех компьютерах будут храниться NetSetup.log сведения о файлах в соответствии с выполненной операцией. Просмотр содержимого этих файлов является наиболее распространенным способом устранения ошибок сетевой и автономной подготовки. Операции подготовки, выполняемые администраторами, записываются в файл NetSetup.log в %WINDIR%\Debug. Операции подготовки, выполняемые не администраторами, записываются в файл NetSetup.log в папке %USERPROFILE%\Debug .

Дополнительные сведения об операциях автономного присоединения к домену см. в пошаговом руководстве по автономному присоединению к домену.

Присоединение (и отмена соединения) компьютера с доменом с помощью NetJoinDomain и NetUnjoinDomain выполняется только членом локальной группы администраторов на целевом компьютере. Обратите внимание, что администратор домена может задать дополнительные требования для присоединения к домену с помощью делегирования и назначения привилегий.

Требования


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