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

Статья
02/26/2024

FltSetVolumeContext задает контекст для тома.

Синтаксис

NTSTATUS FLTAPI FltSetVolumeContext(
  [in]            PFLT_VOLUME               Volume,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

Параметры

[in] Volume

Указатель непрозрачного тома.

[in] Operation

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

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

Flag

Значение

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

Если контекст для volume уже задан, FltSetVolumeContext заменит его на NewContext>. В противном случае он вставляет NewContext в список контекстов для тома.

FLT_SET_CONTEXT_KEEP_IF_EXISTS

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

[in] NewContext

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

[out, optional] OldContext

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Чтобы выделить новый контекст, вызовите FltAllocateContext.
Чтобы получить контекст тома, вызовите Метод FltGetVolumeContext.
Чтобы удалить контекст тома, вызовите Метод FltDeleteVolumeContext или FltDeleteContext.

Требования

Требование	Значение
Минимальная версия клиента	Доступно и поддерживается в накопительном пакете обновления 1 для Microsoft Windows 2000 с пакетом обновления 1 (SP4), Windows XP с пакетом обновления 2 (SP2), Windows Server 2003 с пакетом обновления 1 (SP1) и более поздних версий.
Целевая платформа	Универсальное
Верхняя часть	fltkernel.h (включая Fltkernel.h)
Библиотека	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL