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

Статья
12/21/2024

Подпрограмма 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) и коды ввода и вывода устройств документации по пакету SDK для Microsoft Windows.

[in, optional] InputBuffer

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

[in] InputBufferLength

Размер буфера в байтах в InputBuffer. Если InputBufferNULL, задайте для InputBufferLeng th значение нулю.

[out, optional] OutputBuffer

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

[in] OutputBufferLength

Размер буфера в байтах в OutputBuffer. Если OutputBufferNULL, задайте для OutputBufferLeng th значение нулю.

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

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

Замечания

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

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

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

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

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

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

Для вызовов драйверов в режиме ядра версии **Nt*Xxx** и **Zw*Xxx*** подпрограммы системных служб Windows Native System Services могут вести себя по-разному так, как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связях между подпрограммами **Nt*Xxx** и **Zw*Xxx*** подпрограммы см. в разделе [Использование программ собственных системных служб с использованием nt и Zw](/windows-hardware/drivers/kernel/using-nt-and-zw-versions-of-native-system-services-routines).

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000.
целевая платформа	Всеобщий
заголовка	ntifs.h (include Ntifs.h, Ntddk.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")
правил соответствия DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)