IoRegisterDeviceInterface 함수(wdm.h)

  • 아티클

IoRegisterDeviceInterface 루틴은 이전에 등록되지 않은 경우 디바이스 인터페이스 클래스를 등록하고, 이후에 드라이버가 애플리케이션 또는 다른 시스템 구성 요소에서 사용하도록 설정할 수 있는 인터페이스 클래스의 새 instance 만듭니다.

구문

NTSTATUS IoRegisterDeviceInterface(
  [in]           PDEVICE_OBJECT  PhysicalDeviceObject,
  [in]           const GUID      *InterfaceClassGuid,
  [in, optional] PUNICODE_STRING ReferenceString,
  [out]          PUNICODE_STRING SymbolicLinkName
);

매개 변수

[in] PhysicalDeviceObject

디바이스의 PDO에 대한 포인터입니다.

[in] InterfaceClassGuid

등록되는 기능(디바이스 인터페이스 클래스)을 식별하는 클래스 GUID에 대한 포인터입니다.

[in, optional] ReferenceString

필요에 따라 UNICODE_STRING 가리킵니다. 문자열에는 경로 구분 기호 문자("/" 또는 "\")가 포함되어서는 안 됩니다. 함수 드라이버는 일반적으로 이 매개 변수에 대해 NULL 을 지정합니다. 필터 드라이버는 NULL을 지정해야 합니다.

참조 문자열은 요청 시 생성된 소프트웨어 디바이스의 자리 표시자로 디바이스 인터페이스 인스턴스를 사용하는 버스 드라이버인 swenum과 같은 몇 가지 버스 드라이버에서만 사용됩니다. 인터페이스의 instance 열리면 I/O 관리자가 instance 참조 문자열을 드라이버에 전달합니다. 문자열은 인터페이스 instance 이름(추가된 경로 구성 요소)의 일부가 됩니다. 그런 다음 드라이버는 참조 문자열을 사용하여 단일 디바이스에 대해 동일한 클래스의 두 인터페이스 인스턴스를 구분할 수 있습니다.

Microsoft Windows 98/Me 시스템에서 ReferenceString 값은 더 이상 MAX_PATH 문자가 될 수 없습니다. Windows 2000 이상 버전의 Windows에는 길이 제한이 없습니다.

[out] SymbolicLinkName

호출자가 할당한 유니코드 문자열 구조체에 대한 포인터입니다. 이 루틴이 성공하면 유니코드 문자열을 초기화하고 커널 모드 경로가 포함된 문자열 버퍼를 지정된 디바이스 인터페이스 클래스의 instance 대한 기호 링크에 할당합니다.

호출자는 SymbolicLinkName 을 불투명으로 처리해야 하며 이를 디스어셈블해서는 안 합니다.

호출자는 더 이상 필요하지 않은 경우 RtlFreeUnicodeString을 사용하여 SymbolicLinkName을 해제할 책임이 있습니다.

반환 값

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

반환 코드 설명
STATUS_INVALID_DEVICE_REQUEST
 매개 변수가 잘못되었습니다. PhysicalDeviceObject가 유효한 PDO를 가리키지 않거나 ReferenceString 문자열에 잘못된 문자가 포함될 수 있습니다.

설명

IoRegisterDeviceInterface는 이전에 등록되지 않은 경우 디바이스 인터페이스 클래스를 등록하고 인터페이스 클래스의 새 instance 만듭니다. 드라이버는 지정된 디바이스가 여러 인터페이스 클래스를 등록하고 클래스의 인스턴스를 만들기 위해 이 루틴을 여러 번 호출할 수 있습니다. 함수 또는 필터 드라이버는 일반적으로 AddDevice 루틴에 디바이스 인터페이스를 등록합니다. 예를 들어 내결함성 볼륨 드라이버는 내결함성 볼륨 인터페이스의 instance 특정 볼륨에 대한 볼륨 인터페이스의 instance 등록할 수 있습니다.

디바이스 인터페이스 클래스가 이전에 등록되지 않은 경우 I/O 관리자는 키 아래에 instance 특정 영구 스토리지와 함께 레지스트리 키를 만듭니다. 드라이버는 IoOpenDeviceInterfaceRegistryKey를 사용하여 이 영구 스토리지에 액세스할 수 있습니다.

드라이버는 인터페이스 instance 한 번 등록한 다음 IoSetDeviceInterfaceState를 호출하여 인터페이스를 활성화하고 사용하지 않도록 설정합니다.

등록된 인터페이스는 운영 체제 재부팅에서 유지됩니다. 지정된 인터페이스가 이미 등록된 경우 I/O 관리자는 해당 이름을 SymbolicLinkName으로 전달하고 정보 성공 상태 STATUS_OBJECT_NAME_EXISTS 반환합니다.

대부분의 드라이버는 디바이스 인터페이스 instance NULL 참조 문자열을 사용합니다. 드라이버가 NULL 이 아닌 참조 문자열을 사용하는 경우 고유한 네임스페이스 및 보안 관리를 포함하여 추가 작업을 수행해야 합니다. 디바이스 인터페이스를 노출하는 필터 드라이버는 디바이스 스택의 다른 드라이버와 충돌하지 않도록 NULLReferenceString 을 사용해야 합니다.

이 루틴의 호출자는 더 이상 필요하지 않은 디바이스 인터페이스에 대한 등록을 제거할 필요가 없습니다. 필요한 경우 디바이스 인터페이스 등록을 사용자 모드에서 제거할 수 있습니다.

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

요구 사항

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

추가 정보

IoGetDeviceInterfaces

IoOpenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

RtlFreeUnicodeString