Функция ZwDeviceIoControlFile (ntddk.h)

Статья
08/07/2023

Подпрограмма ZwDeviceIoControlFile отправляет управляющий код непосредственно указанному драйверу устройства, в результате чего соответствующий драйвер выполняет указанную операцию.

Синтаксис

NTSYSAPI NTSTATUS ZwDeviceIoControlFile(
  [in]            HANDLE           FileHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            IoControlCode,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength
);

Параметры

[in] FileHandle

Дескриптор, возвращаемый ZwCreateFile или ZwOpenFile для объекта файла, представляющего устройство, которому должны быть предоставлены сведения об элементе управления или из которого должны быть возвращены сведения. Файловый объект должен быть открыт для асинхронного ввода-вывода, если вызывающий объект задает event, ApcRoutine и контекст APC (в ApcContext) или контекст завершения (в ApcContext). Для ввода-вывода на базовое запоминающее устройство файловый объект должен быть открыт для прямого доступа к устройству хранения данных (DASD).

[in, optional] Event

Дескриптор для события, созданного вызывающим. Если указан этот параметр, вызывающий объект будет переведен в состояние ожидания, пока запрошенная операция не будет завершена, а заданному событию будет присвоено состояние Signaled . Этот параметр является необязательным и может иметь значение NULL. Он должен иметь значение NULL , если вызывающий объект будет ожидать, пока FileHandle будет установлен в состояние Signaled.

[in, optional] ApcRoutine

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

[in, optional] ApcContext

Указатель на область контекста, определяемую вызывающим объектом. Это значение параметра используется в качестве контекста APC, если вызывающий объект предоставляет APC, или в качестве контекста завершения, если объект завершения ввода-вывода был связан с объектом файла. После завершения операции в APC передается контекст APC, если он был указан, или контекст завершения включается в сообщение о завершении, которое диспетчер операций ввода-вывода отправляет в связанный объект завершения ввода-вывода.

Этот параметр является необязательным и может иметь значение NULL. Он должен иметь значение NULL , если ApcRoutine имеет значение NULL и с ним не связан объект завершения ввода-вывода.

[out] IoStatusBlock

Указатель на переменную, которая получает окончательное состояние завершения и сведения об операции. Для успешных вызовов, возвращающих данные, число байтов, записанных в OutputBuffer , возвращается в элементе Information .

[in] IoControlCode

IOCTL_ кодXXX , указывающий, на какой операции управления вводом-выводом устройства должен выполняться, как правило, базовым драйвером устройства. Значение этого параметра определяет формат и необходимую длину InputBuffer и OutputBuffer, а также какие из следующих пар параметров являются обязательными. Подробные сведения о системных кодах IOCTL_XXX см. в разделе о конкретных технологиях устройства в документации по пакету драйверов Microsoft Windows (WDK) и коде управления входными и выходными данными устройства в документации по Microsoft Windows SDK.

[in, optional] InputBuffer

Указатель на выделенный вызывающим объектом входной буфер, содержащий сведения о конкретном устройстве, которые должны быть переданы целевому устройству. Если IoControlCode указывает операцию, которая не требует входных данных, этот указатель может иметь значение NULL.

[in] InputBufferLength

Размер (в байтах) буфера в InputBuffer. Если inputBuffer имеет значение NULL, задайте для параметра InputBufferLength значение 0.

[out, optional] OutputBuffer

Указатель на выделенный вызывающей стороны выходной буфер, в котором данные возвращаются с целевого устройства. Если IoControlCode указывает операцию, которая не создает выходные данные, этот указатель может иметь значение NULL.

[in] OutputBufferLength

Размер буфера в байтах в OutputBuffer. Если OutputBuffer имеет значение NULL, задайте для OutputBufferLength значение 0.

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

ZwDeviceIoControlFile возвращает STATUS_SUCCESS, если базовые драйверы успешно выполнили запрошенную операцию. В противном случае возвращаемое значение может быть кодом состояния ошибки, распространяемым из базового драйвера. Возможные коды состояния ошибок:

ZwDeviceIoControlFile обеспечивает согласованное представление входных и выходных данных для системы и драйверов в режиме ядра, предоставляя приложениям и базовым драйверам зависимый от устройства метод указания интерфейса связи.

Дополнительные сведения о системных кодах IOCTL_XXX, а также об определении значений IOCTL_XXX или FSCTL_XXX см. в разделах Использование кодов управления вводом-выводом в руководстве по архитектуре режима ядра и коды управления вводом и выводом устройства в документации по Microsoft Windows SDK.

Если вызывающий объект открыл файл для асинхронного ввода-вывода (ни с FILE_SYNCHRONOUS_ набором параметров create/openXXX), указанное событие, если таковое есть, будет установлено в состояние сигналов после завершения операции управления устройством. В противном случае объекту файла, указанному fileHandle , будет присвоено состояние сигнала. Если указан ApcRoutine , он вызывается с указателями ApcContext и IoStatusBlock .

Минифильтры должны использовать FltDeviceIoControlFile вместо ZwDeviceIoControlFile.

Вызывающие файлы ZwDeviceIoControlFile должны выполняться в среде IRQL = PASSIVE_LEVEL и с включенными специальными интерфейсами API ядра.

Если вызов функции ZwDeviceIoControlFile происходит в пользовательском режиме, следует использовать имя NtDeviceIoControlFile вместо ZwDeviceIoControlFile.

Для вызовов из драйверов режима ядра версии NtXxx и ZwXxx подпрограммы Собственные системные службы Windows могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями подпрограмм NtXxx и ZwXxx см. в разделе Использование версий NT и Zw подпрограмм собственных системных служб.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	ntddk.h (включая Ntifs.h, Ntddk.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")
Правила соответствия DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)