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

Статья
07/11/2023

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

Синтаксис

__kernel_entry NTSYSCALLAPI NTSTATUS NtFsControlFile(
  [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

Дескриптор, возвращаемый ntCreateFile или NtOpenFile для объекта 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.

[in, optional] InputBuffer

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

[in] InputBufferLength

Размер буфера в байтах в InputBuffer. Это значение игнорируется, если inputBuffer имеет значение NULL.

[out, optional] OutputBuffer

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

[in] OutputBufferLength

Размер буфера в байтах в OutputBuffer. Это значение игнорируется, если OutputBuffer имеет значение NULL.

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

NtFsControlFile возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например одно из следующих значений:

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

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

Ниже приведены некоторые коды FSCTL, задокументированные для драйверов в режиме ядра.

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

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

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

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

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

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

Требования

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