Функция NtDeviceIoControlFile (ntifs.h)
Подпрограмма 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 |