WdfIoTargetWdmGetTargetFileHandle 함수(wdfiotarget.h)
[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 드라이버는 파일별 로컬 I/O 대상(WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE)을 열고 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) |