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

Статья
08/08/2023

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

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

Синтаксис

HANDLE WdfIoTargetWdmGetTargetFileHandle(
  [in] WDFIOTARGET IoTarget
);

Параметры

[in] IoTarget

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

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

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

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

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

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

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

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

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

Если драйвер UMDF версии 2 вызывает WdfIoTargetWdmGetTargetFileHandle для получения дескриптора 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, драйвер открывает локальный целевой объект ввода-вывода по файлу и извлекает его дескриптор. Платформа открывает и закрывает дескриптор файла. Дескриптор файла остается действительным в контракте 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

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