Функция NtFsControlFile (ntifs.h)
Подпрограмма 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_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.
Дополнительные сведения о системных кодах 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 |