SetupDiCreateDeviceInfoW 함수(setupapi.h)

아티클
08/26/2023

SetupDiCreateDeviceInfo 함수는 새 디바이스 정보 요소를 만들고 지정된 디바이스 정보 집합에 새 멤버로 추가합니다.

구문

WINSETUPAPI BOOL SetupDiCreateDeviceInfoW(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PCWSTR           DeviceName,
  [in]            const GUID       *ClassGuid,
  [in, optional]  PCWSTR           DeviceDescription,
  [in, optional]  HWND             hwndParent,
  [in]            DWORD            CreationFlags,
  [out, optional] PSP_DEVINFO_DATA DeviceInfoData
);

매개 변수

[in] DeviceInfoSet

로컬 컴퓨터에 대해 설정된 디바이스 정보에 대한 핸들입니다.

[in] DeviceName

전체 디바이스 instance ID(예: "Root*PNP0500\0000") 또는 열거자 접두사 및 instance 식별자 접미사가 없는 루트 열거형 디바이스 ID(예: "*PNP0500")를 제공하는 NULL로 끝나는 문자열에 대한 포인터입니다. 루트 열거형 디바이스 식별자는 DICD_GENERATE_ID 플래그가 CreationFlags 매개 변수에 지정된 경우에만 사용할 수 있습니다.

[in] ClassGuid

디바이스에 대한 디바이스 설정 클래스 GUID에 대한 포인터입니다. 디바이스의 디바이스 설정 클래스를 알 수 없는 경우 *ClassGuid 를 GUID_NULL 구조로 설정합니다.

[in, optional] DeviceDescription

디바이스의 텍스트 설명을 제공하는 NULL로 끝나는 문자열에 대한 포인터입니다. 이 포인터는 선택 사항이며 NULL일 수 있습니다.

[in, optional] hwndParent

디바이스 설치와 관련된 모든 사용자 인터페이스에 사용할 최상위 창에 대한 핸들입니다. 이 핸들은 선택 사항이며 NULL일 수 있습니다.

[in] CreationFlags

디바이스 정보 요소를 만드는 방법을 제어하는 DWORD 형식의 변수입니다. 다음 값의 조합일 수 있습니다.

DICD_GENERATE_ID

이 플래그를 지정하면 DeviceName에는 루트 열거형 디바이스 ID만 포함되고 시스템은 해당 ID를 사용하여 새 디바이스 정보 요소에 대한 전체 디바이스 instance ID를 생성합니다.

SetupDiGetDeviceInstanceId를 호출하여 이 디바이스 정보 요소에 대해 생성된 디바이스 instance ID를 검색합니다.

DICD_INHERIT_CLASSDRVS

이 플래그를 지정하면 결과 디바이스 정보 요소는 디바이스 정보 집합과 연결된 클래스 드라이버 목록(있는 경우)을 상속합니다. 또한 디바이스 정보 집합에 대해 선택한 드라이버가 있는 경우 새 디바이스 정보 요소에 대해 동일한 드라이버가 선택됩니다.

[out, optional] DeviceInfoData

새 디바이스 정보 요소를 수신하는 SP_DEVINFO_DATA 구조체에 대한 포인터입니다. 이 포인터는 선택 사항이며 NULL일 수 있습니다. 구조체가 제공되면 호출자는 함수를 호출하기 전에 이 구조체의 cbSize 멤버를 sizeof(SP_DEVINFO_DATA) 로 설정해야 합니다. 자세한 내용은 다음 주의 섹션을 참조 하세요 .

반환 값

함수가 성공하면 TRUE 를 반환합니다. 그렇지 않으면 FALSE 를 반환하고 GetLastError를 호출하여 기록된 오류를 검색할 수 있습니다.

설명

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

이 디바이스 instance 연결된 클래스가 있는 집합에 추가되는 경우 디바이스 클래스는 동일해야 합니다. 그렇지 않으면 호출이 실패합니다. 이 경우 GetLastError 호출은 ERROR_CLASS_MISMATCH 반환합니다.

지정된 디바이스 instance 레지스트리의 기존 디바이스 instance 키와 같으면 호출이 실패합니다. 이 경우 GetLastError 호출은 ERROR_DEVINST_ALREADY_EXISTS 반환합니다. DICD_GENERATE_ID 플래그가 설정되지 않은 경우에만 발생합니다.

새 디바이스 정보 요소가 성공적으로 만들어졌지만 호출자가 제공한 DeviceInfoData 버퍼가 잘못된 경우 함수는 FALSE를 반환합니다. 이 경우 GetLastError 호출은 ERROR_INVALID_USER_BUFFER 반환합니다. 그러나 디바이스 정보 요소는 이미 집합의 새 멤버로 추가됩니다.

DeviceInfoSet에는 로컬 컴퓨터의 요소만 포함되어야 합니다.

참고

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

요구 사항

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