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

Статья
01/07/2025

Программа 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 для объекта файла, представляющего файл или каталог, в котором выполняется указанное действие. Объект файла должен быть открыт для асинхронного ввода-вывода, если вызывающий объект указывает event, ApcRoutineи контекст APC (в ApcContext) или контекст завершения (в ApcContext).

[in, optional] Event

Дескриптор для события, созданного вызывающим. Если этот параметр указан, вызывающий объект будет помещен в состояние ожидания до завершения запрошенной операции, и заданное событие имеет состояние Signaled. Этот параметр является необязательным и может иметь значение NULL. Значение 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_XXX набора параметров создания и открытия), указанное событие, если таковой есть, будет задано сигнальное состояние при завершении операции управления устройством. В противном случае объект файла, указанный FileHandle, будет установлен в сигнальное состояние. Если был указан ApcRoutine, он вызывается с указателями ApcContext и IoStatusBlock.

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

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

Дополнительные сведения о системных кодах IOCTL_XXX и определении кодов IOCTL_IOCTL_XXX или FSCTL_XXX см. в использование кодов управления ввода-вывода и кодов ввода-вывода и кодов управления устройствами.

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

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

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

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

Требования

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