SetupDiCreateDevRegKeyA 함수(setupapi.h)

아티클
03/15/2023

SetupDiCreateDevRegKey 함수는 디바이스별 구성 정보에 대한 레지스트리 키를 만들고 키에 대한 핸들을 반환합니다.

구문

WINSETUPAPI HKEY SetupDiCreateDevRegKeyA(
  [in]           HDEVINFO         DeviceInfoSet,
  [in]           PSP_DEVINFO_DATA DeviceInfoData,
  [in]           DWORD            Scope,
  [in]           DWORD            HwProfile,
  [in]           DWORD            KeyType,
  [in, optional] HINF             InfHandle,
  [in, optional] PCSTR            InfSectionName
);

매개 변수

[in] DeviceInfoSet

레지스트리 키를 만들 디바이스를 나타내는 디바이스 정보 요소가 포함된 디바이스 정보 집합 에 대한 핸들입니다.

[in] DeviceInfoData

DeviceInfoSet에서 디바이스 정보 요소를 지정하는 SP_DEVINFO_DATA 구조체에 대한 포인터입니다.

[in] Scope

만들 레지스트리 키의 scope. scope 정보가 저장되는 위치를 결정합니다. 만든 키는 전역 또는 하드웨어 프로필에 따라 다를 수 있습니다. 다음 값 중 하나일 수 있습니다.

DICS_FLAG_GLOBAL

전역 구성 정보를 저장할 키를 만듭니다. 이 정보는 특정 하드웨어 프로필에만 해당되지 않습니다. NT 기반 운영 체제에서는 HKEY_LOCAL_MACHINE 루팅된 키를 만듭니다. 열린 정확한 키는 KeyType 매개 변수의 값에 따라 달라집니다.

DICS_FLAG_CONFIGSPECIFIC

하드웨어 프로필 관련 구성 정보를 저장하는 키를 만듭니다. 이 키는 HKEY_LOCAL_MACHINE 대신 하드웨어 프로필 특정 분기 중 하나에 루팅됩니다.

[in] HwProfile

HwProfileFlags가 SPDICS_FLAG_CONFIGSPECIFIC 설정된 경우 키를 만들 하드웨어 프로필입니다. HwProfile이 0이면 현재 하드웨어 프로필의 키가 만들어집니다. HwProfileFlags가 SPDICS_FLAG_GLOBAL 경우 HwProfile은 무시됩니다.

[in] KeyType

만들 레지스트리 스토리지 키의 유형입니다. 다음 값 중 하나일 수 있습니다.

DIREG_DEV

디바이스에 대한 하드웨어 키를 만듭니다.

DIREG_DRV

디바이스에 대한 소프트웨어 키를 만듭니다.

[in, optional] InfHandle

새로 만든 키에 대해 실행할 INF DDInstall 섹션 이 포함된 열려 있는 INF 파일에 대한 핸들입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 이 매개 변수를 지정하는 경우 InfSectionName 도 지정해야 합니다.

[in, optional] InfSectionName

InfHandle에서 지정한 INF 파일의 INF DDInstall 섹션 이름입니다. 이 섹션은 새로 만든 키에 대해 실행됩니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 이 매개 변수를 지정하는 경우 InfHandle 도 지정해야 합니다.

반환 값

SetupDiCreateDevRegKey가 성공하면 함수는 디바이스별 구성 데이터를 저장하고 검색할 수 있는 지정된 레지스트리 키에 대한 핸들을 반환합니다. SetupDiCreateDevRegKey가 실패하면 함수는 INVALID_HANDLE_VALUE 반환합니다. GetLastError를 호출하여 확장 오류 정보를 가져옵니다.

설명

SetupDiCreateDevRegKey의 호출자는 Administrators 그룹의 구성원이어야 합니다.

RegCloseKey를 호출하여 SetupDiCreateDevRegKey에서 반환된 핸들을 닫습니다.

지정된 키가 이미 있는 경우 SetupDiCreateDevRegKey 는 해당 키에 대한 핸들을 반환합니다. 그렇지 않으면 SetupDiCreateDevRegKey 가 지정된 키를 만들고 새 키에 대한 핸들을 반환합니다. Windows Server 2003 이상 버전의 Windows의 경우 키 핸들에는 KEY_READ 및 KEY_WRITE 액세스만 있습니다. 이전 Windows 버전의 경우 이 핸들에는 KEY_ALL_ACCESS 액세스 권한이 있습니다.

SetupDiCreateDevRegKey가 호출되기 전에 지정된 디바이스 instance 등록해야 합니다. 그러나 운영 체제는 PnP 디바이스 인스턴스를 자동으로 등록합니다. 비 PnP 디바이스 인스턴스를 등록하는 방법에 대한 자세한 내용은 SetupDiRegisterDeviceInfo를 참조하세요.

레이아웃 파일(INF 버전 섹션의 LayoutFile 항목으로 지정됨)을 사용하는 설치의 경우 SetupDiCreateDevRegKey가 호출되기 전에 SetupOpenAppendInfFile(Microsoft Windows SDK 설명서에 설명됨)을 호출하여 레이아웃 파일을 열어야 합니다.

제공된 디바이스 정보 집합에 원격 시스템에 대한 디바이스 정보 요소가 포함되어 있고 InfHandle 및 InfSectionName 도 지정된 경우 만들기 요청이 실패하고 GetLastError 에 대한 후속 호출은 ERROR_REMOTE_REQUEST_UNSUPPORTED 반환합니다.

참고

setupapi.h 헤더는 SETUPDiCreateDevRegKey를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Microsoft Windows 2000 이상 버전의 Windows에서 사용할 수 있습니다.
대상 플랫폼	데스크톱
머리글	setupapi.h(Setupapi.h 포함)
라이브러리	Setupapi.lib