Функция WdfIoTargetWdmGetTargetFileHandle (wdfiotarget.h)

Статья
03/22/2025

[Применимо к KMDF и UMDF]

Метод WdfIoTargetWdmGetTargetFileHandle возвращает дескриптор файла, связанного с указанным удаленным целевым объектом ввода-вывода.

Синтаксис

HANDLE WdfIoTargetWdmGetTargetFileHandle(
  [in] WDFIOTARGET IoTarget
);

Параметры

[in] IoTarget

Дескриптор удаленного целевого объекта ввода-вывода. Этот дескриптор был получен из предыдущего вызова WdfIoTargetCreate.

Возвращаемое значение

Если драйвер указал имя объекта при вызове WdfIoTargetOpen, WdfIoTargetWdmGetTargetFileHandle возвращает дескриптор файла, связанный с указанным целевым объектом ввода-вывода. В противном случае WdfIoTargetGetTargetFileHandle возвращает NULL.

Ошибка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Замечания

Для KMDF возвращенный дескриптор файла — это дескриптор режима ядра, допустимый в произвольном контексте потока. Сведения о том, как драйвер может использовать этот дескриптор файла, см. в использованиедескриптора файлов.

Дескриптор файла, который возвращает метод WdfIoTargetGetTargetFileHandle, пока драйвер не вызывает WdfIoTargetClose или WdfIoTargetCloseForQueryRemoveили до удаления удаленного целевого объекта ввода-вывода. Если драйвер предоставляет функцию EvtCleanupCallback для удаленного целевого объекта ввода-вывода и если объект удаляется до закрытия удаленного целевого объекта ввода-вывода, указатель действителен до тех пор, пока не будет возвращена функция EvtCleanupCallback.

Если драйвер пытается получить доступ к объекту устройства WDM после его удаления, драйвер может вызвать сбой системы. В примере toastmon показано, как драйвер может предоставить функцию обратного вызова EvtIoTargetQueryRemove, чтобы она была уведомлена об удалении целевого объекта ввода-вывода.

Для UMDF WdfIoTargetWdmGetTargetFileHandle возвращает допустимый ДЕСКРиптор Win32 только в текущем процессе. Устаревший драйвер UMDF (версия 1.x) вызывает вызовы IWDFDevice::RetrieveDeviceName, чтобы получить имя базового устройства в режиме ядра, а затем открывает к нему дескриптор с CreateFile. Затем драйвер может отправлять ввод-вывод непосредственно на более низкие устройства с помощью DeviceIoControl. Начиная с версии UMDF 2.15 драйверы UMDF версии 2 могут открывать локальный целевой объект ввода-вывода по файлу (WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE) и извлекать дескриптор файла с помощью WdfIoTargetGetTargetFileHandle. Платформа открывает и закрывает дескриптор файла при закрытии или удалении удаленного целевого объекта. Дескриптор файла остается допустимым в контракте WdfIoTargetGetTargetFileHandle описано выше.

Предупреждение

Если драйвер UMDF версии 2 вызывает WdfIoTargetGetTargetFileHandle для получения дескриптора Win32 из удаленного целевого объекта, открытого с помощью WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, не отправляйте перекрывающиеся и асинхронные операции ввода-вывода с api, например DeviceIoControl. Это может завершить процесс размещения драйвера. Если драйвер должен отправить перекрывающиеся операции ввода-вывода, он также должен задать низкоупорядоченный бит hEvent элемента OVERLAPPED структуры. Это связано с тем, что платформа внутренне привязывает дескриптор к порту завершения ввода-вывода. Допустимый дескриптор событий, бит которого имеет низкий порядок, сохраняет завершение ввода-вывода от очереди до порта завершения.

Дополнительные сведения о WdfIoTargetWdmGetTargetFileHandleсм. в получении сведений об общем целевом объекте ввода-вывода.

Дополнительные сведения о целевых объектах ввода-вывода см. в разделе Использование целевых объектов ввода-вывода.

Примеры

В следующем примере кода получается дескриптор файла, связанного с указанным удаленным целевым объектом ввода-вывода.

HANDLE h;

h = WdfIoTargetWdmGetTargetFileHandle(IoTarget);

Устаревший драйвер UMDF (версия 1.x) вызывает вызовы IWDFDevice::RetrieveDeviceName, чтобы получить имя базового устройства в режиме ядра, а затем открыть к нему дескриптор с CreateFile. Затем драйвер отправляет ввод-вывод непосредственно на устройство с помощью DeviceIoControl.

Начиная с версии UMDF 2.15 драйвер открывает локальный целевой объект ввода-вывода по файлу и извлекает его дескриптор. Платформа открывается и закрывает дескриптор файла. Дескриптор файла остается допустимым в контракте WdfIoTargetGetTargetFileHandle.

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 (include Wdf.h)
Библиотека	Wdf01000.sys (см. управление версиями библиотеки Платформы).)
IRQL	<=DISPATCH_LEVEL
правил соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

См. также

WdfIoTargetCreate

WdfIoTargetWdmGetTargetFileObject

Поделиться через