IoRegisterDeviceInterface 함수(wdm.h)
IoRegisterDeviceInterface 루틴은 이전에 등록되지 않은 경우 디바이스 인터페이스 클래스등록하고, 이후에 드라이버가 애플리케이션 또는 다른 시스템 구성 요소에서 사용하도록 설정할 수 있는 인터페이스 클래스의 새 인스턴스를 만듭니다.
통사론
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같은 몇 가지 버스 드라이버에서만 사용됩니다. 인터페이스 인스턴스가 열리면 I/O 관리자가 인스턴스의 참조 문자열을 드라이버에 전달합니다. 문자열은 인터페이스 인스턴스 이름(추가된 경로 구성 요소)의 일부가 됩니다. 그런 다음 드라이버는 참조 문자열을 사용하여 단일 디바이스에 대해 동일한 클래스의 두 인터페이스 인스턴스를 구분할 수 있습니다.
Microsoft Windows 98/Me 시스템에서 ReferenceString 값은 더 이상 MAX_PATH 문자가 될 수 없습니다. Windows 2000 이상 버전의 Windows에는 길이 제한이 없습니다.
[out] SymbolicLinkName
호출자가 할당한 유니코드 문자열 구조체에 대한 포인터입니다. 이 루틴이 성공하면 유니코드 문자열을 초기화하고 커널 모드 경로가 포함된 문자열 버퍼를 지정된 디바이스 인터페이스 클래스의 인스턴스에 대한 기호 링크에 할당합니다.
호출자는 SymbolicLinkName 불투명으로 처리해야 하며 디스어셈블해서는 안 됩니다.
호출자는 더 이상 필요하지 않은 경우 RtlFreeUnicodeString 사용하여 SymbolicLinkName 해제할 책임이 있습니다.
반환 값
IoRegisterDeviceInterface 호출에 성공하면 STATUS_SUCCESS 반환합니다. 가능한 오류 반환 값은 다음과 같습니다.
| 반환 코드 | 묘사 |
|---|---|
|
매개 변수가 잘못되었습니다. PhysicalDeviceObject 유효한 PDO를 가리키지 않거나 ReferenceString 문자열에 잘못된 문자가 포함되어 있는 것일 수 있습니다. |
발언
IoRegisterDeviceInterface 이전에 등록되지 않은 경우 디바이스 인터페이스 클래스를 등록하고 인터페이스 클래스의 새 인스턴스를 만듭니다. 드라이버는 지정된 디바이스가 여러 인터페이스 클래스를 등록하고 클래스의 인스턴스를 만들기 위해 이 루틴을 여러 번 호출할 수 있습니다. 함수 또는 필터 드라이버는 일반적으로 AddDevice 루틴에 디바이스 인터페이스를 등록합니다. 예를 들어 내결함성 볼륨 드라이버는 내결함성 볼륨 인터페이스의 인스턴스와 특정 볼륨에 대한 볼륨 인터페이스의 인스턴스를 등록할 수 있습니다.
디바이스 인터페이스 클래스가 이전에 등록되지 않은 경우 I/O 관리자는 키 아래에 인스턴스별 영구 스토리지와 함께 레지스트리 키를 만듭니다. 드라이버는 IoOpenDeviceInterfaceRegistryKey사용하여 이 영구 스토리지에 액세스할 수 있습니다.
드라이버는 인터페이스 인스턴스를 한 번 등록한 다음 IoSetDeviceInterfaceState 호출하여 인터페이스를 사용하도록 설정하고 사용하지 않도록 설정합니다.
등록된 인터페이스는 운영 체제 재부팅에서 유지됩니다. 지정된 인터페이스가 이미 등록된 경우 I/O 관리자는 SymbolicLinkName 해당 이름을 전달하고 정보 성공 상태 STATUS_OBJECT_NAME_EXISTS 반환합니다.
대부분의 드라이버는 디바이스 인터페이스 인스턴스에 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) |
참고 항목
IoOpenDeviceInterfaceRegistryKey
rtlFreeUnicodeString