NetRequestProvisioningPackageInstall 함수(lmjoin.h)

아티클
03/14/2023

NetRequestProvisioningPackageInstall 함수는 컴퓨터에서 로컬로 실행되어 볼륨에 탑재된 Windows 운영 체제 이미지를 수정합니다. 레지스트리는 이미지에서 로드되고 프로비전 패키지 데이터는 오프라인 도메인 조인 작업의 완료 단계에서 검색할 수 있는 위치에 기록됩니다.

구문

NET_API_STATUS NET_API_FUNCTION NetRequestProvisioningPackageInstall(
  [in] BYTE    *pPackageBinData,
  [in] DWORD   dwPackageBinDataSize,
  [in] DWORD   dwProvisionOptions,
  [in] LPCWSTR lpWindowsPath,
       PVOID   pvReserved
);

매개 변수

[in] pPackageBinData

오프라인 도메인 조인 작업의 완료 단계에서 최종 로컬 상태 변경을 처리하기 위해 Windows 운영 체제 이미지의 레지스트리를 초기화하는 데 필요한 버퍼에 대한 포인터입니다.

pPackageBinData 매개 변수에 전달된 직렬화된 메타데이터의 불투명 이진 Blob은 NetCreateProvisioningPackage 함수에 의해 반환됩니다.

[in] dwPackageBinDataSize

pPackageBinData 매개 변수가 가리키는 버퍼의 크기(바이트)입니다.

이 매개 변수는 NULL이 아니어야 합니다.

[in] dwProvisionOptions

이 함수에 대한 옵션을 정의하는 비트 플래그 집합입니다. 이 매개 변수는 Lmjoin.h 헤더 파일에 정의된 다음 값 중 하나 이상을 사용합니다.

값	의미
NETSETUP_PROVISION_ONLINE_CALLER 0x40000000	lpWindowsPath 매개 변수가 액세스 가능한 볼륨에 탑재된 오프라인 Windows 운영 체제 이미지가 아닌 현재 실행 중인 Windows 운영 체제 디렉터리를 참조하는 경우 이 플래그가 필요합니다. 이 플래그를 지정하면 로컬 Administrators 그룹의 멤버가 NetRequestProvisioningPackageInstall 함수를 호출해야 합니다.

[in] lpWindowsPath

레지스트리 하이브가 있는 Windows 운영 체제 이미지의 경로를 지정하는 NULL로 끝나는 문자열에 대한 포인터입니다. dwProvisionOptions 매개 변수에 NETSETUP_PROVISION_ONLINE_CALLER 포함되어 있지 않으면 이 이미지는 오프라인 상태여야 하며 현재 부팅되지 않아야 합니다. 이 경우 로컬로 실행 중인 운영 체제 디렉터리가 허용됩니다.

이 경로는 원격 서버의 UNC 경로일 수 있습니다.

pvReserved

다음에 사용하도록 예약됩니다.

반환 값

함수가 성공하면 반환 값이 NERR_Success.

함수가 실패하면 반환 값은 다음 네트워크 관리 오류 코드 중 하나일 수 있습니다.

반환 코드	설명
NERR_NoOfflineJoinInfo	오프라인 조인 완료 정보를 찾을 수 없습니다.
NERR_BadOfflineJoinInfo	오프라인 조인 완료 정보가 잘못되었습니다.
NERR_CantCreateJoinInfo	오프라인 조인 정보를 만들 수 없습니다. 지정된 경로 위치에 대한 액세스 권한과 해당 콘텐츠를 수정할 수 있는 권한이 있는지 확인하세요. 관리자 권한으로 실행해야 할 수 있습니다.
NERR_BadDomainJoinInfo	저장되는 도메인 가입 정보가 불완전하거나 잘못되었습니다.
NERR_JoinPerformedMustRestart	오프라인 조인 작업이 성공적으로 완료되었지만 다시 시작해야 합니다.
NERR_NoJoinPending	보류 중인 오프라인 조인 작업이 없습니다.
NERR_ValuesNotSet	로컬 컴퓨터에서 하나 이상의 요청된 컴퓨터 또는 도메인 이름 값을 설정할 수 없습니다.
NERR_CantVerifyHostname	조인 완료 정보의 저장된 값에 대해 현재 컴퓨터의 호스트 이름을 확인할 수 없습니다.
NERR_CantLoadOfflineHive	지정된 오프라인 레지스트리 하이브를 로드할 수 없습니다. 지정된 경로 위치에 대한 액세스 권한과 해당 콘텐츠를 수정할 수 있는 권한이 있는지 확인하세요. 관리자 권한으로 실행해야 할 수 있습니다.
NERR_ConnectionInsecure	이 작업에 대한 최소 세션 보안 요구 사항이 충족되지 않았습니다.
NERR_ProvisioningBlobUnsupported	컴퓨터 계정 프로비저닝 Blob 버전은 지원되지 않습니다.

설명

NetRequestProvisioningPackageInstall 함수는 오프라인 도메인 조인 작업에 대해 Windows 8에서 지원됩니다. Windows 7의 경우 NetRequestOfflineDomainJoin을 사용합니다.

오프라인 도메인 조인 시나리오에서는 다음 두 가지 함수를 사용합니다.

NetCreateProvisioningPackage 는 Active Directory에서 컴퓨터 개체를 만들고 구성하는 데 필요한 네트워크 작업을 수행하기 위해 먼저 호출되는 프로비저닝 함수입니다. NetCreateProvisioningPackage의 출력은 다음 단계에서 사용되는 패키지입니다.
이미지 초기화 함수인 NetRequestProvisioningPackageInstall은 설치 중에 사용할 Windows 운영 체제 이미지에 NetCreateProvisioningPackage 프로비저닝 함수의 출력을 삽입하기 위해 호출됩니다.

Windows 초기화 코드를 변경하면 이 저장된 상태를 검색하고 도메인 조인의 로컬 전용 부분에 영향을 미치고 패키지에 있을 수 있는 인증서 및 정책 정보를 설치합니다.

NetCreateProvisioningPackage 함수는 도메인에서 컴퓨터 계정을 만들거나 다시 사용하고, 필요한 모든 메타데이터를 수집하고, 패키지에 반환합니다. 패키지는 네트워크 작업 없이 첫 번째 부팅 중에 도메인 조인을 완료하는 데 필요한 모든 입력을 제공하는 오프라인 도메인 조인 요청 작업에서 사용할 수 있습니다(로컬 상태 업데이트만 해당).

보안 참고 사항: NetCreateProvisioningPackage 함수에서 만든 패키지에는 매우 중요한 데이터가 포함되어 있습니다. 일반 텍스트 암호처럼 안전하게 처리해야 합니다. 패키지에는 도메인 이름, 도메인 컨트롤러 이름 및 도메인의 SID(보안 ID)를 포함하여 컴퓨터 계정 암호 및 도메인에 대한 기타 정보가 포함됩니다. 패키지를 물리적으로 또는 네트워크를 통해 전송하는 경우 안전하게 전송하려면 주의해야 합니다. 디자인에서는 이 데이터를 보호하기 위한 프로비저닝을 수행하지 않습니다. 이 문제는 도메인 사용자 암호를 포함하여 많은 비밀을 전달할 수 있는 무인 설정 응답 파일에서 현재 존재합니다. 호출자는 패키지를 보호해야 합니다. 이 문제에 대한 해결 방법은 다양합니다. 예를 들어 미리 교환된 키를 사용하여 소비자와 프로비전 엔터티 간의 세션을 암호화하여 패키지를 안전하게 전송할 수 있습니다.

NetCreateProvisioningPackage 함수에 의해 pPackageBinData 매개 변수에 반환된 패키지는 클라이언트 조인, 컴퓨터 프로비전 및 도메인 컨트롤러 사용과 같은 다양한 버전의 Windows 간의 상호 운용성 및 서비스 가능성 시나리오를 허용하도록 버전이 지정됩니다. 오프라인 조인 시나리오는 현재 NetCreateProvisioningPackage 함수에서 반환하는 패키지의 수명을 제한하지 않습니다.

프로비전 프로세스의 모든 단계는 로컬 컴퓨터의 NetSetup.log 파일에 추가됩니다. 프로비저닝 프로세스에는 프로비전 패키지가 만들어진 컴퓨터, 패키지 설치를 요청하는 컴퓨터 및 패키지가 설치된 컴퓨터 등 최대 세 대의 컴퓨터가 포함될 수 있습니다. 수행된 작업에 따라 세 컴퓨터 모두에 NetSetup.log 파일 정보가 저장됩니다. 이러한 파일의 내용을 검토하는 것은 온라인 및 오프라인 프로비저닝 오류를 해결하는 가장 일반적인 방법입니다. 관리자가 수행하는 프로비전 작업은 %WINDIR%\Debug의 NetSetup.log 파일에 기록됩니다. 관리자가 아닌 사용자가 수행하는 프로비저닝 작업은 %USERPROFILE%\Debug 폴더의 NetSetup.log 파일에 기록됩니다.

요구 사항


지원되는 최소 클라이언트	Windows 8 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2012 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	lmjoin.h(Lm.h 포함)
라이브러리	Netapi32.lib
DLL	Netapi32.dll