IoSetDeviceInterfaceState 함수(wdm.h)

아티클
02/07/2025

IoSetDeviceInterfaceState 루틴은 이전에 등록된 디바이스 인터페이스 클래스의 인스턴스를 사용하거나 사용하지 않도록 설정합니다.

통사론

NTSTATUS IoSetDeviceInterfaceState(
  [in] PUNICODE_STRING SymbolicLinkName,
  [in] BOOLEAN         Enable
);

매개 변수

[in] SymbolicLinkName

사용하거나 사용하지 않도록 설정 중인 디바이스 인터페이스 인스턴스를 식별하는 문자열에 대한 포인터입니다. 이 문자열은 IoRegisterDeviceInterface 또는 IoGetDeviceInterfaces대한 이전 호출에서 가져옵니다.

[in] Enable

TRUE 디바이스 인터페이스가 사용하도록 설정되어 있음을 나타냅니다. FALSE 디바이스 인터페이스가 비활성화되고 있음을 나타냅니다.

반환 값

IoSetDeviceInterfaceState 호출에 성공하면 STATUS_SUCCESS 반환합니다. 이 루틴은 호출자가 이미 사용하도록 설정된 디바이스 인터페이스를 사용하도록 요청한 경우 STATUS_OBJECT_NAME_EXISTS 정보 상태를 반환합니다. 가능한 오류 반환 값은 다음과 같습니다.

반환 코드	묘사
STATUS_OBJECT_NAME_NOT_FOUND	호출자가 사용하도록 설정되지 않은 디바이스 인터페이스를 사용하지 않도록 설정하려고 했습니다.

발언

IoSetDeviceInterfaceState 애플리케이션 및 기타 시스템 구성 요소에서 사용할 등록된 디바이스 인터페이스의 인스턴스를 사용하도록 설정합니다. 인터페이스 클래스는 이전에 IoRegisterDeviceInterface 또는 사용자 모드에서 등록되어 있어야 합니다.

애플리케이션 및 기타 시스템 구성 요소는 사용하도록 설정된 인터페이스만 열 수 있습니다.

함수 또는 필터 드라이버는 일반적으로 IRP_MN_START_DEVICE IRP에 대한 응답으로 디바이스를 성공적으로 시작한 후 사용 TRUE 설정하여 이 루틴을 호출합니다. 이러한 드라이버는 IRP_MN_REMOVE_DEVICE IRP 또는 IRP_MN_SURPRISE_REMOVAL IRP에 대한 응답으로 디바이스를 제거할 때 디바이스 인터페이스 인스턴스(즉, IoSetDeviceInterfaceState 호출하고 FALSE사용하도록 설정)를 사용하지 않도록 설정해야 합니다. 드라이버가 이러한 제거 IRP를 처리할 때 디바이스 인터페이스를 사용하지 않도록 설정하지 않는 경우 PnP 관리자가 디바이스를 제거할 때 PnP 관리자가 인터페이스를 사용하지 않도록 설정하므로 드라이버에서 이 작업을 시도하지 않아야 합니다.

디바이스가 갑자기 제거되었지만(예: 깜짝 제거에 의해) 유효한 디바이스 인터페이스 인스턴스가 여전히 있는 경우 디바이스를 다시 연결하면 문제가 발생합니다. 이 문제는 PnP 관리자가 새로 연결된 디바이스를 열거하고 기존 디바이스 인터페이스 인스턴스와 동일한 레지스트리 경로에 존재하는 디바이스 인터페이스 인스턴스를 사용하도록 설정할 때 발생합니다.

드라이버가 IoSetDeviceInterfaceState 호출하여 IRP_MN_SURPRISE_REMOVAL IRP에 대한 응답으로 디바이스 인터페이스 인스턴스를 사용하지 않도록 설정하는 경우 드라이버는 IRP_MN_REMOVE_DEVICE IRP에 대한 응답으로 동일한 디바이스 인터페이스 인스턴스를 사용하지 않도록 설정하려고 시도해서는 안 됩니다.

IoSetDeviceInterfaceState에 대한 호출이 디바이스 인터페이스 인스턴스를 성공적으로 노출할 경우 시스템은 PnP에 등록된 모든 구성 요소에 디바이스 클래스 변경에 대해 알림을 제공합니다. 마찬가지로 이 루틴을 호출하면 기존 디바이스 인터페이스 인스턴스를 사용하지 않도록 설정하면 시스템에서 적절한 알림을 보냅니다.

PnP 관리자는 IRP_MN_START_DEVICE IRP가 완료될 때까지 인터페이스 인스턴스 도착 알림을 보내지 않으며, 이는 디바이스의 모든 드라이버가 시작 작업을 완료했음을 나타냅니다. 또한 PnP 관리자는 IRP_MN_START_DEVICE IRP가 완료될 때까지 디바이스에 대한 만들기 요청을 실패합니다.

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

요구 사항

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