Функция FltSetFileContext (fltkernel.h)

Статья
08/07/2023

Подпрограмма FltSetFileContext задает контекст для файла.

Синтаксис

NTSTATUS FLTAPI FltSetFileContext(
  [in]  PFLT_INSTANCE             Instance,
  [in]  PFILE_OBJECT              FileObject,
  [in]  FLT_SET_CONTEXT_OPERATION Operation,
  [in]  PFLT_CONTEXT              NewContext,
  [out] PFLT_CONTEXT              *OldContext
);

Параметры

[in] Instance

Непрозрачный указатель на экземпляр драйвера минифильтра для вызывающего объекта. Этот параметр является обязательным и не может иметь значение NULL.

[in] FileObject

Указатель на объект файла для файла. Этот параметр является обязательным и не может иметь значение NULL.

[in] Operation

Флаг, указывающий тип операции, выполняемой FltSetFileContext . Этот параметр должен иметь один из следующих флагов:

Flag	Значение
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	Если для файла, на который указывает параметр FileObject , уже задан контекст, FltSetFileContext заменит этот контекст контекстом, указанным в NewContext. В противном случае он вставляет NewContext в список контекстов для файла.
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Если для файла, на который указывает FileObject , уже задан контекст, FltSetFileContext вернет STATUS_FLT_CONTEXT_ALREADY_DEFINED и не заменит существующий контекст или не увеличит число ссылок. Если контекст еще не задан, подпрограмма вставляет контекст, указанный в NewContext , в список контекстов для файла и увеличивает количество ссылок.

Flag

Значение

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

Если для файла, на который указывает параметр FileObject , уже задан контекст, FltSetFileContext заменит этот контекст контекстом, указанным в NewContext. В противном случае он вставляет NewContext в список контекстов для файла.

FLT_SET_CONTEXT_KEEP_IF_EXISTS

Если для файла, на который указывает FileObject , уже задан контекст, FltSetFileContext вернет STATUS_FLT_CONTEXT_ALREADY_DEFINED и не заменит существующий контекст или не увеличит число ссылок. Если контекст еще не задан, подпрограмма вставляет контекст, указанный в NewContext , в список контекстов для файла и увеличивает количество ссылок.

[in] NewContext

Указатель на новый контекст, который необходимо задать для файла. Этот параметр является обязательным и не может иметь значение NULL.

[out] OldContext

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

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

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

Код возврата	Описание
STATUS_FLT_CONTEXT_ALREADY_DEFINED	Если для параметра Operation был указан FLT_SET_CONTEXT_KEEP_IF_EXISTS, этот код ошибки указывает, что контекст уже присоединен к файлу.
STATUS_FLT_CONTEXT_ALREADY_LINKED	Контекст, на который указывает параметр NewContext , уже связан с объектом . Другими словами, этот код ошибки указывает, что NewContext уже используется из-за успешного предыдущего вызова процедурыКонтекста FltSetXxx.
STATUS_FLT_DELETING_OBJECT	Экземпляр, указанный в параметре Instance , сносится. Это код ошибки.
STATUS_INVALID_PARAMETER	Передан недопустимый параметр. Например, параметр NewContext не указывает на допустимый контекст файла или для параметра Operation было указано недопустимое значение. Это код ошибки.
STATUS_NOT_SUPPORTED	Контексты файлов для этого файла не поддерживаются. Это код ошибки.

Драйвер минифильтра вызывает FltSetFileContext , чтобы задать или заменить собственный контекст файла. Драйвер минифильтра может прикрепить к файлу только один контекст для каждого экземпляра драйвера минифильтра.

Не удается вызвать FltSetFileContext для нераскрытого объекта FileObject. Следовательно , fltSetFileContext нельзя вызвать из предварительно созданного обратного вызова для файла, так как файл не был открыт на этом этапе. Однако драйвер минифильтра может выделить и настроить контекст файла в обратном вызове перед созданием, передать его в обратный вызов после создания с помощью параметра контекста завершения и задать контекст файла для файла, соответствующего этому потоку в обратном вызове после создания.

Подсчет ссылок

Если fltSetFileContext успешно выполняется:

Число ссылок в NewContext увеличивается. Если NewContext больше не требуется, минифильтр должен вызвать FltReleaseContext для уменьшения количества ссылок.

В противном случае, если fltSetFileContext завершается сбоем :

Количество ссылок в NewContext остается неизменным.
Если значение OldContext не равно NULL и не указывает на NULL_CONTEXT то OldContext является указателем на контекст, связанный в данный момент с файлом. Фильтр, вызывающий FltSetFileContext , должен в конечном итоге вызвать FltReleaseContext для OldContext , если указатель контекста больше не нужен.

Независимо от успеха:

Фильтр, вызывающий FltSetFileContext , должен вызывать FltReleaseContext для уменьшения количества ссылок в объекте NewContext , который был увеличен с помощью FltAllocateContext.

Дополнительные сведения см. в разделе Ссылки на контексты.

Другие контекстные операции

Дополнительные сведения см . в разделах Настройка контекстов и Освобождение контекстов:

Чтобы выделить новый контекст, вызовите FltAllocateContext.
Чтобы получить контекст файла, вызовите FltGetFileContext.
Чтобы удалить контекст файла, вызовите Метод FltDeleteFileContext или FltDeleteContext.
Чтобы определить, поддерживаются ли контексты файлов для данного файла, вызовите FltSupportsFileContexts или FltSupportsFileContextsEx.

Требования

Требование	Значение
Минимальная версия клиента	Доступно и поддерживается начиная с Windows Vista.
Целевая платформа	Универсальное
Верхняя часть	fltkernel.h (включая Fltkernel.h)
Библиотека	Fltmgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL