다음을 통해 공유

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(&params, NULL);

status = WdfIoTargetOpen(ioTarget, &params);

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)

추가 정보

WdfIoTargetCreate

WdfIoTargetWdmGetTargetFileObject