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

Статья
07/11/2023

Подпрограмма 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_DELETE_REPARSE_POINT

FSCTL_GET_REPARSE_POINT

FSCTL_OPBATCH_ACK_CLOSE_PENDING

FSCTL_OPLOCK_BREAK_ACK_NO_2

FSCTL_OPLOCK_BREAK_ACKNOWLEDGE

FSCTL_OPLOCK_BREAK_NOTIFY

FSCTL_REQUEST_BATCH_OPLOCK

FSCTL_REQUEST_FILTER_OPLOCK

FSCTL_REQUEST_OPLOCK_LEVEL_1

FSCTL_REQUEST_OPLOCK_LEVEL_2

FSCTL_SET_REPARSE_POINT

Дополнительные сведения о системных кодах FSCTL_XXX см. в разделе "Примечания" справочной записи по DeviceIoControl в документации по Microsoft Windows SDK.

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

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

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

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

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

Требования

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