Функция ZwFsControlFile (ntifs.h)
Подпрограмма ZwFsControlFile отправляет управляющий код непосредственно в указанную файловую систему или драйвер фильтра файловой системы, в результате чего соответствующий драйвер будет выполнять указанное действие.
Синтаксис
NTSYSAPI NTSTATUS ZwFsControlFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG FsControlCode,
[in, optional] PVOID InputBuffer,
[in] ULONG InputBufferLength,
[out, optional] PVOID OutputBuffer,
[in] ULONG OutputBufferLength
);
Параметры
[in] FileHandle
Дескриптор, возвращенный ZwCreateFile или ZwOpenFile для объекта file, представляющего файл или каталог, в котором выполняется указанное действие. Файловый объект должен быть открыт для асинхронного ввода-вывода, если вызывающий объект задает event, ApcRoutine и контекст APC (в ApcContext) или контекст завершения (в ApcContext).
[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
Указатель на структуру IO_STATUS_BLOCK, которая получает окончательное состояние завершения и сведения об операции. Для успешных вызовов, возвращающих данные, количество байтов, записанных в OutputBuffer , возвращается в элементе Information этой структуры.
[in] FsControlCode
FSCTL_ кодXXX , указывающий, какая операция управления файловой системой должна быть выполнена. Значение этого параметра определяет форматы и длину inputBuffer и OutputBuffer, а также то, какие из следующих пар параметров являются обязательными. Подробные сведения о системных кодах FSCTL_XXX см. в разделе "Примечания" справочной записи по DeviceIoControl в документации по Microsoft Windows SDK.
[in, optional] InputBuffer
Указатель на выделенный вызывающим объектом входной буфер, содержащий сведения о конкретном устройстве, которые должны быть переданы целевому драйверу. Если FsControlCode указывает операцию, которая не требует входных данных, этот указатель является необязательным и может иметь значение NULL.
[in] InputBufferLength
Размер (в байтах) буфера в InputBuffer. Это значение игнорируется, если InputBuffer имеет значение NULL.
[out, optional] OutputBuffer
Указатель на выделенный вызывающим выходной буфер, в котором данные возвращаются из целевого драйвера. Если FsControlCode указывает операцию, которая не создает выходные данные, этот указатель является необязательным и может иметь значение NULL.
[in] OutputBufferLength
Размер буфера в байтах в OutputBuffer. Это значение игнорируется, если OutputBuffer имеет значение NULL.
Возвращаемое значение
ZwFsControlFile возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например одно из следующих значений:
Комментарии
ZwFsControlFile обеспечивает согласованное представление входных и выходных данных для системы и драйверов режима ядра, предоставляя приложениям и базовым драйверам зависимый от драйвера метод указания интерфейса связи.
Если вызывающий объект открыл файл для асинхронного ввода-вывода (ни с FILE_SYNCHRONOUS_ набором параметров create/openXXX), указанное событие, если таковое есть, будет установлено в состояние сигналов после завершения операции управления устройством. В противном случае объекту файла, указанному fileHandle , будет присвоено состояние сигнала. Если указан ApcRoutine , он вызывается с указателями ApcContext и IoStatusBlock .
Следующие коды FSCTL в настоящее время задокументированы для драйверов режима ядра:
FSCTL_OPBATCH_ACK_CLOSE_PENDING
FSCTL_OPLOCK_BREAK_ACKNOWLEDGE
Дополнительные сведения о системных кодах FSCTL_XXX см. в разделе "Примечания" справочной записи по DeviceIoControl в документации по Microsoft Windows SDK.
Дополнительные сведения о системных кодах IOCTL_XXX , а также об определении значений IOCTL_XXX или FSCTL_XXX см. в разделах Использование кодов управления вводом-выводом в руководстве по архитектуре режима ядра и коды управления вводом и выводом устройств в документации по пакету SDK для Windows.
Минифильтры должны использовать FltFsControlFile вместо ZwFsControlFile.
Вызывающие файлы ZwFsControlFile должны выполняться в IRQL = PASSIVE_LEVEL и с включенными специальными api ядра.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000. |
| Целевая платформа | Универсальное |
| Верхняя часть | ntifs.h (включая Ntifs.h) |
| Библиотека | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (см. раздел "Примечания") |
| Правила соответствия DDI | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |
См. также раздел
Использование кодов элементов управления вводом-выводом