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

Статья
12/21/2024

Подпрограмма 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 для объекта файла, представляющего файл или каталог, для которого необходимо выполнить указанное действие. Объект файла должен быть открыт для асинхронного ввода-вывода, если вызывающий объект указывает 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 в документации по пакету SDK для Microsoft Windows.

[in, optional] InputBuffer

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

[in] InputBufferLength

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

[out, optional] OutputBuffer

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

[in] OutputBufferLength

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

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

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

Замечания

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

Если вызывающий объект открыл файл для асинхронного ввода-вывода (без FILE_SYNCHRONOUS_XXX набора параметров создания и открытия), указанное событие, если таковой есть, будет задано сигнальное состояние при завершении операции управления устройством. В противном случае объект файла, указанный 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 в документации по пакету SDK для Microsoft Windows.

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

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

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

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

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

Требования

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