SetupDiGetClassDevsExA 함수(setupapi.h)
SetupDiGetClassDevsEx 함수는 로컬 또는 원격 컴퓨터에 대해 요청된 디바이스 정보 요소가 포함된 디바이스 정보 집합에 대한 핸들을 반환합니다.
구문
WINSETUPAPI HDEVINFO SetupDiGetClassDevsExA(
[in, optional] const GUID *ClassGuid,
[in, optional] PCSTR Enumerator,
[in, optional] HWND hwndParent,
[in] DWORD Flags,
[in, optional] HDEVINFO DeviceInfoSet,
[in, optional] PCSTR MachineName,
PVOID Reserved
);
매개 변수
[in, optional] ClassGuid
디바이스 설정 클래스 또는 디바이스인터페이스 클래스의 GUID에 대한 포인터입니다. 이 포인터는 선택 사항이며 NULL일 수 있습니다. GUID 값을 사용하여 디바이스를 선택하지 않으면 ClassGuid 를 NULL로 설정합니다. ClassGuid를 사용하는 방법에 대한 자세한 내용은 다음 설명 섹션을 참조하세요.
[in, optional] Enumerator
다음을 지정하는 NULL로 끝나는 문자열에 대한 포인터입니다.
- PnP(플러그 앤 플레이) 열거자의 ID(식별자)입니다. 이 ID는 열거자의 GUID(Globally Unique Identifier) 또는 기호 이름일 수 있습니다. 예를 들어 "PCI"를 사용하여 PCI PnP 열거자를 지정할 수 있습니다. PnP 열거자에 대한 기호 이름의 다른 예로는 "USB", "PCMCIA" 및 "SCSI"가 있습니다.
- PnP 디바이스 instance ID. PnP 디바이스 instance ID를 지정할 때 Flags 매개 변수에서 DIGCF_DEVICEINTERFACE 설정해야 합니다.
열거자 값을 설정하는 방법에 대한 자세한 내용은 다음 설명 섹션을 참조하세요.
[in, optional] hwndParent
디바이스 정보 집합에 디바이스 instance 설치와 연결된 사용자 인터페이스에 사용할 최상위 창에 대한 핸들입니다. 이 핸들은 선택 사항이며 NULL일 수 있습니다.
[in] Flags
디바이스 정보 집합에 추가되는 디바이스 정보 요소를 필터링하는 제어 옵션을 지정하는 DWORD 형식의 변수입니다. 이 매개 변수는 다음 플래그 중 하나 이상의 비트 OR일 수 있습니다. 이러한 컨트롤 옵션을 결합하는 방법에 대한 자세한 내용은 다음 설명 섹션을 참조하세요 .
DIGCF_ALLCLASSES
지정된 디바이스 설정 클래스 또는 디바이스 인터페이스 클래스에 대해 설치된 디바이스 목록을 반환합니다.
DIGCF_DEVICEINTERFACE
지정된 디바이스 인터페이스 클래스에 대한 디바이스 인터페이스를 지원하는 디바이스를 반환합니다. Enumerator매개 변수가 디바이스 instance ID를 지정하는 경우 Flags 매개 변수에서 이 플래그를 설정해야 합니다.
DIGCF_DEFAULT
지정된 디바이스 인터페이스 클래스에 대해 시스템 기본 디바이스 인터페이스(설정된 경우)와 연결된 디바이스만 반환합니다.
DIGCF_PRESENT
현재 있는 디바이스만 반환합니다.
DIGCF_PROFILE
현재 하드웨어 프로필의 일부인 디바이스만 반환합니다.
[in, optional] DeviceInfoSet
SetupDiGetClassDevsEx에서 요청된 디바이스 정보 요소를 추가하는 기존 디바이스 정보 집합에 대한 핸들입니다. 이 매개 변수는 선택 사항이며 NULL로 설정할 수 있습니다. 이 매개 변수를 사용하는 방법에 대한 자세한 내용은 다음 설명 섹션을 참조하세요 .
[in, optional] MachineName
디바이스가 있는 원격 컴퓨터의 이름을 포함하는 상수 문자열에 대한 포인터입니다. MachineName에 대한 NULL 값은 디바이스가 로컬 컴퓨터에 설치되도록 지정합니다.
주의
이 기능이 제거되었으므로 이 함수를 사용하여 원격 머신에 액세스하는 것은 Windows 8 및 Windows Server 2012 시작되지 않습니다.
Reserved
내부용으로 예약된 속성입니다. 이 매개 변수는 NULL로 설정해야 합니다.
반환 값
작업이 성공하면 SetupDiGetClassDevsEx 는 제공된 매개 변수와 일치하는 설치된 모든 디바이스가 포함된 디바이스 정보 집합 에 대한 핸들을 반환합니다. 작업이 실패하면 함수는 INVALID_HANDLE_VALUE 반환합니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.
설명
SetupDiGetClassDevsEx의 호출자는 SetupDiDestroyDeviceInfoList를 호출하여 더 이상 필요하지 않은 경우 반환된 디바이스 정보 집합을 삭제해야 합니다.
DeviceInfoSet이 NULL인 경우 SetupDiGetClassDevsEx는 검색된 디바이스 정보 요소가 포함된 새 디바이스 정보 집합을 만들고 새 디바이스 정보 집합에 대한 핸들을 반환합니다. 호출자가 ClassGuid 매개 변수에서 제공하는 디바이스 설정 클래스에 대해 함수가 디바이스를 검색하도록 요청하는 경우 함수는 새 디바이스 정보의 디바이스 설정 클래스를 제공된 클래스 GUID로 설정합니다.
DeviceInfoSet이 NULL로 설정되지 않은 경우 함수는 검색된 디바이스 정보 요소를 제공된 핸들과 연결된 디바이스 정보 집합에 추가하고 제공된 핸들을 반환합니다. ClassGuid가 디바이스 설정 클래스를 제공하는 경우 제공된 디바이스 정보 집합의 디바이스 설정 클래스를 제공된 클래스 GUID로 설정해야 합니다.
디바이스 설정 클래스 제어 옵션
다음 필터링 옵션을 사용하여 SetupDiGetClassDevsEx 가 모든 디바이스 설정 클래스에 대해 디바이스를 반환하는지 또는 지정된 디바이스 설정 클래스에 대해서만 디바이스를 반환하는지 제어합니다.- 모든 디바이스 설정 클래스에 대한 디바이스를 반환하려면 DIGCF_ALLCLASSES 플래그를 설정하고 ClassGuid 매개 변수를 NULL로 설정합니다.
- 특정 디바이스 설정 클래스에 대해서만 디바이스를 반환하려면 DIGCF_ALLCLASSES 설정하지 말고 ClassGuid 를 사용하여 디바이스 설정 클래스의 GUID를 입력합니다.
- 시스템에 있는 디바이스만 반환하려면 DIGCF_PRESENT 플래그를 설정합니다.
- 현재 하드웨어 프로필의 일부인 디바이스만 반환하려면 DIGCF_PROFILE 플래그를 설정합니다.
- 특정 PnP 열거자에 대해서만 디바이스를 반환하려면 열거자 매개 변수를 사용하여 열거자의 GUID 또는 기호 이름을 입력합니다. Enumerator가 NULL이면 SetupDiGetClassDevsEx는 모든 PnP 열거자에 대한 디바이스를 반환합니다.
디바이스 인터페이스 클래스 컨트롤 옵션
다음 필터링 옵션을 사용하여 SetupDiGetClassDevsEx 가 디바이스 인터페이스 클래스를 지원하는 디바이스를 반환하는지 또는 지정된 디바이스 인터페이스 클래스를 지원하는 디바이스만 반환하는지 여부를 제어합니다.- 모든 클래스의 디바이스 인터페이스를 지원하는 디바이스를 반환하려면 DIGCF_DEVICEINTERFACE 플래그를 설정하고, DIGCF_ALLCLASSES 플래그를 설정하고, ClassGuid 를 NULL로 설정합니다. 함수는 디바이스 정보 집합에 해당 디바이스를 나타내는 디바이스 정보 요소를 추가한 다음 디바이스 정보 요소에 디바이스에서 지원하는 모든 디바이스 인터페이스가 포함된 디바이스 인터페이스 목록을 추가합니다.
- 지정된 클래스의 디바이스 인터페이스를 지원하는 디바이스만 반환하려면 DIGCF_DEVICEINTERFACE 플래그를 설정하고 ClassGuid 매개 변수를 사용하여 디바이스 인터페이스 클래스의 클래스 GUID를 제공합니다. 함수는 디바이스 정보 집합에 해당 디바이스를 나타내는 디바이스 정보 요소를 추가한 다음 지정된 클래스의 디바이스 인터페이스를 해당 디바이스 정보 요소의 디바이스 인터페이스 목록에 추가합니다.
- 시스템 기본 인터페이스를 지원하는 디바이스만 반환하려면 시스템 기본 인터페이스가 설정된 경우 지정된 디바이스 인터페이스 클래스에 대해 DIGCF_DEVICEINTERFACE 플래그를 설정하고, DIGCF_DEFAULT 플래그를 설정하고, ClassGuid 를 사용하여 디바이스 인터페이스 클래스의 클래스 GUID를 제공합니다. 함수는 디바이스 정보 집합에 해당 디바이스를 나타내는 디바이스 정보 요소를 추가한 다음 해당 디바이스 정보 요소의 디바이스 인터페이스 목록에 시스템 기본 인터페이스를 추가합니다.
- 지정되지 않은 디바이스 인터페이스 클래스에 대한 시스템 기본 인터페이스를 지원하는 디바이스를 반환하려면 DIGCF_DEVICEINTERFACE 플래그를 설정하고, DIGCF_ALLCLASSES 플래그를 설정하고, DIGCF_DEFAULT 플래그를 설정하고, ClassGuid 를 NULL로 설정합니다. 함수는 디바이스 정보 집합에 해당 디바이스를 나타내는 디바이스 정보 요소를 추가한 다음 해당 디바이스 정보 요소의 디바이스 인터페이스 목록에 시스템 기본 인터페이스를 추가합니다.
- 시스템에 있는 디바이스만 반환하려면 DIGCF_PRESENT 플래그를 설정합니다.
- 현재 하드웨어 프로필의 일부인 디바이스만 반환하려면 DIGCF_PROFILE 플래그를 설정합니다.
- 특정 디바이스만 반환하려면 DIGCF_DEVICEINTERFACE 플래그를 설정하고 Enumerator 매개 변수를 사용하여 디바이스의 디바이스 instance ID를 입력합니다. 가능한 모든 디바이스를 포함하려면 열거자를NULL로 설정합니다.
디바이스 인터페이스 클래스를 지원하는 디바이스 설정 클래스에서 디바이스 검색
설치 관리자는 SetupDiGetClassDevsEx 를 사용하여 지정된 디바이스 인터페이스 클래스의 디바이스 인터페이스를 지원하는 특정 디바이스 설정 클래스의 디바이스 목록을 검색할 수 있습니다. 예를 들어 "탑재된 디바이스" 인터페이스 클래스에서 디바이스 인터페이스를 지원하고 "볼륨" 디바이스 설정 클래스의 멤버인 로컬 컴퓨터의 모든 디바이스 목록을 검색하려면 설치 관리자가 다음 작업을 수행해야 합니다.- SetupDiCreateDeviceInfoList를 호출하여 "볼륨" 디바이스 설정 클래스에 대한 빈 디바이스 정보 집합을 만듭니다. ClassGuid를 "Volume" 디바이스 설정 클래스의 클래스 GUID에 대한 포인터로 설정하고 hwndParent를 적절하게 설정합니다. 이러한 호출에 대한 응답으로 함수는 HDEVINFO를 입력하는 핸들을 디바이스 정보 집합에 반환합니다.
- 다음 설정을 사용하여 SetupDiGetClassDevsEx 를 호출합니다.
- ClassGuid를 "탑재된 디바이스" 디바이스 인터페이스 클래스의 클래스 GUID에 대한 포인터로 설정합니다.
- 플래그를 DIGCF_DEVICEINTERFACE 설정합니다.
- DeviceInfoSet을 1단계에서 가져온 HDEVINFO 핸들로 설정합니다.
- hwndParent를 적절하게 설정하고 나머지 매개 변수를 NULL로 설정합니다.
참고
setupapi.h 헤더는 SETUPDiGetClassDevsEx를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Microsoft Windows 2000 이상 버전의 Windows에서 사용할 수 있습니다. |
| 대상 플랫폼 | 데스크톱 |
| 머리글 | setupapi.h(Setupapi.h 포함) |
| 라이브러리 | Setupapi.lib |
추가 정보
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기