[KMDF 및 UMDF에 적용]
WdfIoTargetWdmGetTargetFileHandle 메서드는 지정된 원격 I/O 대상과 연결된 파일에 대한 핸들을 반환합니다.
구문론
HANDLE WdfIoTargetWdmGetTargetFileHandle(
[in] WDFIOTARGET IoTarget
);
매개 변수
[in] IoTarget
원격 I/O 대상 개체에 대한 핸들입니다. 이 핸들은 WdfIoTargetCreate대한 이전 호출에서 가져온 것입니다.
반환 값
드라이버가 WdfIoTargetOpen호출할 때 개체 이름을 지정한 경우 WdfIoTargetWdmGetTargetFileHandle 지정된 I/O 대상과 연결된 파일 핸들을 반환합니다. 그렇지 않으면 WdfIoTargetWdmGetTargetFileHandle NULL 반환합니다.
드라이버에서 잘못된 개체 핸들을 제공하면 버그 검사가 수행됩니다.
비고
KMDF의 경우 반환된 파일 핸들은 임의의 스레드 컨텍스트에서 유효한 커널 모드 핸들입니다. 드라이버에서 이 파일 핸들을 사용하는 방법에 대한 자세한 내용은 파일 핸들사용합니다.
WdfIoTargetWdmGetTargetFileHandle 메서드가 반환하는 파일 핸들은 드라이버가 WdfIoTargetClose 또는 WdfIoTargetCloseForQueryRemove호출하거나 원격 I/O 대상 개체가 삭제될 때까지 유효합니다. 드라이버가 원격 I/O 대상 개체에 대해 EvtCleanupCallback 함수를 제공하고, 원격 I/O 대상이 닫기 전에 개체가 삭제되면 EvtCleanupCallback 함수가 반환될 때까지 포인터가 유효합니다.
드라이버가 제거된 후 WDM 디바이스 개체에 액세스하려고 하면 드라이버에서 시스템 작동이 중단될 수 있습니다. 알림 샘플은 I/O 대상이 제거될 때 알림을 받도록 드라이버가 EvtIoTargetQueryRemove 콜백 함수를 제공하는 방법을 보여 줍니다.
UMDF의 경우 WdfIoTargetWdmGetTargetFileHandle 현재 프로세스에서만 유효한 Win32 HANDLE을 반환합니다. 레거시 UMDF 드라이버(버전 1.x)는 IWDFDevice::RetrieveDeviceName 호출하여 기본 커널 모드 디바이스의 이름을 가져오고 createFile 핸들을 엽니다. 그런 다음 드라이버는 DeviceIoControl사용하여 I/O를 하위 디바이스로 직접 보낼 수 있습니다. UMDF 2.15부터 UMDF v2 드라이버는 파일(WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE)으로 로컬 I/O 대상을 열고 WdfIoTargetWdmGetTargetFileHandle사용하여 파일 핸들을 검색할 수 있습니다. 프레임워크는 원격 대상이 닫히거나 삭제될 때 파일 핸들을 열고 닫습니다. 파일 핸들은 위에서 설명한 WdfIoTargetWdmGetTargetFileHandle 계약 내에서 유효합니다.
경고
UMDF v2 드라이버가 WdfIoTargetWdmGetTargetFileHandle 호출하여 WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE 사용하여 열린 원격 대상에서 Win32 핸들을 가져오는 경우 DeviceIoControl같은 API와 겹치는/비동기 I/O를 제출하지 마세요. 이렇게 하면 드라이버를 호스팅하는 프로세스가 충돌할 수 있습니다. 드라이버가 겹치는 I/O를 제출해야 하는 경우 OVERLAPPED 구조체의 hEvent 멤버의 하위 비트도 설정해야 합니다. 프레임워크가 내부적으로 핸들을 I/O 완성 포트에 바인딩하기 때문입니다. 낮은 순서의 비트가 설정된 유효한 이벤트 핸들은 I/O 완료가 완료 포트에 큐에 대기되지 않도록 합니다.
WdfIoTargetWdmGetTargetFileHandle 대한 자세한 내용은 일반 I/O 대상 대한 정보 가져오기참조하세요.
I/O 대상에 대한 자세한 내용은 I/O 대상 사용참조하세요.
예시
다음 코드 예제에서는 지정된 원격 I/O 대상과 연결된 파일에 대한 핸들을 가져옵니다.
HANDLE h;
h = WdfIoTargetWdmGetTargetFileHandle(IoTarget);
레거시 UMDF 드라이버(버전 1.x)는 IWDFDevice::RetrieveDeviceName 호출하여 기본 커널 모드 디바이스의 이름을 가져오고 CreateFile사용하여 핸들을 엽니다. 그런 다음 드라이버는 DeviceIoControl사용하여 디바이스에 직접 I/O를 보냅니다.
UMDF 2.15부터 드라이버는 파일별로 로컬 I/O 대상을 열고 해당 핸들을 검색합니다. 프레임워크가 열리고 파일 핸들이 닫힙니다. 파일 핸들은 WdfIoTargetWdmGetTargetFileHandle계약 내에서 유효합니다.
NTSTATUS status;
WDF_IO_TARGET_OPEN_PARAMS params;
WDFIOTARGET ioTarget = NULL;
HANDLE handle = NULL;
status = WdfIoTargetCreate(Device, &attr, &ioTarget);
if (!NT_SUCCESS(status)) {
// error handling
}
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE(¶ms, NULL);
status = WdfIoTargetOpen(ioTarget, ¶ms);
if (!NT_SUCCESS(status)) {
// error handling
}
handle = WdfIoTargetWdmGetTargetFileHandle(ioTarget);
if (handle == NULL) {
// error handling
}
if (ioTarget != NULL) {
WdfIoTargetClose(ioTarget);
}
// You can now call DeviceIoControl(handle, ...) etc.
// NOTE: See Warning above on submitting overlapped or asynchronous I/O
요구 사항
| 요구 사항 | 가치 |
|---|---|
| 대상 플랫폼 | 보편적 |
| 최소 KMDF 버전 | 1.0 |
| 최소 UMDF 버전 | 2.15 |
| 헤더 | wdfiotarget.h(Wdf.h 포함) |
| 라이브러리 | Wdf01000.sys(프레임워크 라이브러리 버전 관리 참조) |
| IRQL | <=DISPATCH_LEVEL |
| DDI 규정 준수 규칙 | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |