IoGetDeviceInterfaces 함수(wdm.h)

아티클
08/08/2023

IoGetDeviceInterfaces 루틴은 특정 디바이스 인터페이스 클래스의 디바이스 인터페이스 인스턴스 목록(예: HID 인터페이스를 지원하는 시스템의 모든 디바이스)을 반환합니다.

구문

NTSTATUS IoGetDeviceInterfaces(
  [in]           const GUID     *InterfaceClassGuid,
  [in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
  [in]           ULONG          Flags,
  [out]          PZZWSTR        *SymbolicLinkList
);

매개 변수

[in] InterfaceClassGuid

디바이스 인터페이스 클래스를 지정하는 클래스 GUID에 대한 포인터입니다. 클래스의 GUID는 디바이스별 헤더 파일에 있어야 합니다.

[in, optional] PhysicalDeviceObject

PDO가 나타내는 디바이스의 디바이스 인터페이스 인스턴스로만 검색 범위를 좁히는 선택적 PDO에 대한 포인터입니다.

[in] Flags

디바이스 인터페이스에 대한 검색을 수정하는 플래그를 지정합니다. 현재 정의되어 있는 플래그는 하나뿐이며 다음 표에 설명되어 있습니다.

플래그	의미
DEVICE_INTERFACE_INCLUDE_NONACTIVE	사용 가능한 인터페이스 인스턴스 외에도 비활성화된 디바이스 인터페이스 인스턴스를 반환합니다.

특정 인터페이스 클래스를 지원하는 디바이스를 검색할 때 호출자는 사용 가능한 인터페이스 instance 필요하므로 DEVICE_INTERFACE_INCLUDE_NONACTIVE 플래그를 설정하지 않습니다.

드라이버는 일반적으로 DEVICE_INTERFACE_INCLUDE_NONACTIVE 플래그를 설정하여 드라이버에서 사용하도록 설정해야 하는 비활성화된 인터페이스 인스턴스를 찾습니다. 예를 들어 디바이스에 대한 클래스 설치 관리자가 INF 파일에서 디바이스에 대해 하나 이상의 인터페이스 인스턴스를 등록하도록 지시했을 수 있습니다. 인터페이스 인스턴스는 등록되지만 드라이버에서 사용하도록 설정될 때까지 사용할 수 없습니다( IoSetDeviceInterfaceState 사용). 지정된 디바이스에서 노출되는 인스턴스로만 반환되는 인터페이스 인스턴스 목록을 좁히기 위해 드라이버는 PhysicalDeviceObject를 지정할 수 있습니다.

[out] SymbolicLinkList

루틴이 성공하면 유니코드 문자열 목록이 포함된 버퍼의 기본 주소를 쓰는 와이드 문자 포인터에 대한 포인터입니다. 이러한 문자열은 검색 조건과 일치하는 디바이스 인터페이스 인스턴스를 식별하는 기호 링크 이름입니다. 목록의 각 유니코드 문자열은 null로 종료됩니다. 전체 목록의 끝에 추가 null 문자가 표시됩니다. 루틴은 페이징된 시스템 메모리에서 이러한 문자열에 대한 버퍼를 할당합니다. 호출자는 더 이상 필요하지 않은 경우( ExFreePool 루틴을 호출하여) 버퍼를 해제할 책임이 있습니다.

검색 조건과 일치하는 디바이스 인터페이스 인스턴스가 없으면 이 루틴은 STATUS_SUCCESS 반환하고 문자열에는 단일 NULL 문자가 포함됩니다.

반환 값

IoGetDeviceInterfaces는 호출이 성공하면 STATUS_SUCCESS 반환합니다. 가능한 오류 반환 값은 다음과 같습니다.

반환 코드	설명
STATUS_INVALID_DEVICE_REQUEST	PhysicalDeviceObject가 유효한 PDO 포인터가 아님을 나타내는 것일 수 있습니다.

설명

IoGetDeviceInterfaces는 검색 조건과 일치하는 디바이스 인터페이스 인스턴스 목록을 반환합니다. 커널 모드 구성 요소는 일반적으로 이 루틴을 호출하여 특정 디바이스 인터페이스 클래스의 활성화된 모든 디바이스 인터페이스 인스턴스 목록을 가져옵니다. 이러한 구성 요소는 IoGetDeviceObjectPointer 또는 ZwCreateFile 루틴을 호출하여 인터페이스에 대한 파일 개체 및/또는 디바이스 개체에 대한 포인터를 가져올 수 있습니다. IoGetDeviceObjectPointer에서 반환된 디바이스 개체 포인터는 디바이스에 대한 디바이스 스택의 위쪽을 가리키며 IoCallDriver 루틴 호출에 사용할 수 있습니다.

요청된 디바이스 인터페이스 클래스에 대한 기본 인터페이스가 있는 경우 먼저 SymbolicLinkList에 나열됩니다. 기본 인터페이스는 사용자 모드로 설정할 수 있지만 커널 모드에서는 설정할 수 없습니다.

기호 링크 이름의 형식은 불투명합니다. 호출자는 기호 링크 이름을 구문 분석하려고 시도해서는 안 됩니다.

시스템 부팅에서 디바이스 인터페이스 인스턴스에 대한 기호 링크를 사용할 수 있습니다.

시스템에서 특정 클래스의 추가 디바이스 인터페이스 인스턴스를 사용하도록 설정할 때 알림을 받도록 하려면 IoRegisterPlugPlayNotification 루틴을 호출하여 디바이스 클래스 변경 알림을 등록합니다.

IoGetDeviceInterfaces의 호출자는 시스템 스레드의 컨텍스트에서 IRQL = PASSIVE_LEVEL 실행되어야 합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000부터 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL(설명 섹션 참조)
DDI 규정 준수 규칙	HwStorPortProhibitedDDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)