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

  • Статья

Подпрограмма FltSetStreamHandleContext задает контекст для дескриптора потока.

Синтаксис

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

Параметры

[in] Instance

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

[in] FileObject

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

[in] Operation

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

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

[in] NewContext

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

[out, optional] OldContext

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

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

Подпрограмма FltSetStreamHandleContext возвращает 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 было указано недопустимое значение.
STATUS_NOT_SUPPORTED Возникла неподдерживаемая ситуация, например файловая система не поддерживает контексты каждого потока для этого файлового потока или вызывающий объект предоставил null FileObject.

Комментарии

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

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

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

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

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

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

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

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

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

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

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

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

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

Требования

Требование Значение
Минимальная версия клиента Доступно и поддерживается в накопительном пакете обновления 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

См. также раздел

FltAllocateContext

FltDeleteContext

FltDeleteStreamHandleContext

FltGetStreamHandleContext

FltReleaseContext