IoSetDeviceInterfaceState 함수(wdm.h)

아티클
08/08/2023

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

구문

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

매개 변수

[in] SymbolicLinkName

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

[in] Enable

TRUE 는 디바이스 인터페이스가 사용하도록 설정되어 있음을 나타냅니다. FALSE 는 디바이스 인터페이스가 사용하지 않도록 설정되어 있음을 나타냅니다.

반환 값

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

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

설명

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

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

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

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

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

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

PnP 관리자는 IRP_MN_START_DEVICE IRP가 완료될 때까지 인터페이스 instance 도착 알림을 보내지 않으므로 디바이스의 모든 드라이버가 시작 작업을 완료했음을 나타냅니다. 또한 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)