Функция NtDeviceIoControlFile (ntifs.h)

Статья
07/11/2023

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

Синтаксис

__kernel_entry NTSYSCALLAPI NTSTATUS NtDeviceIoControlFile(
  [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) и Кодах управления входными и выходными данными устройств.

[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 см. в разделах Использование кодов управления вводом-выводом и Коды управления входными и выходными данными устройства.

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

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

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

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

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

Требования

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