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

Статья
08/07/2023

FltAttachVolume создает новый экземпляр драйвера минифильтра и присоединяет его к заданному тому.

Синтаксис

NTSTATUS FLTAPI FltAttachVolume(
  [in, out]      PFLT_FILTER      Filter,
  [in, out]      PFLT_VOLUME      Volume,
  [in, optional] PCUNICODE_STRING InstanceName,
  [out]          PFLT_INSTANCE    *RetInstance
);

Параметры

[in, out] Filter

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

[in, out] Volume

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

[in, optional] InstanceName

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

[out] RetInstance

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

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

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

Код возврата	Описание
STATUS_FLT_DELETING_OBJECT	Указанный фильтр или том будет сноситься. Это код ошибки.
STATUS_FLT_FILTER_NOT_READY	Драйвер минифильтра не начал фильтрацию. Дополнительные сведения см. в разделе FltStartFiltering. Это код ошибки.
STATUS_FLT_INSTANCE_NAME_COLLISION	Экземпляр с таким именем уже существует на указанном томе.
STATUS_INSUFFICIENT_RESOURCES	FltAttachVolume обнаружил сбой выделения пула. Это код ошибки.
STATUS_OBJECT_NAME_COLLISION	Другой экземпляр уже был присоединен на высоте, указанной в атрибутах экземпляра, которые были считаны из реестра. Это код ошибки.

Если вызывающий объект задает для InstanceName значение, отличное от NULL, FltAttachVolume считывает все атрибуты экземпляра, заданные драйвером минифильтра, которые хранятся в реестре в разделе HKLM\CurrentControlSet\Services\ServiceName\Instances\InstanceName, где ServiceName — имя службы драйвера мини-фильтра. Это имя службы указывается в директиве AddService в разделе DefaultInstall.Services INF-файла драйвера минифильтра. (Дополнительные сведения о INF-файлах драйвера фильтра см. в разделе Установка драйвера фильтра файловой системы.)

Если вызывающий объект не задает значение instanceName, FltAttachVolume использует имя, хранящееся в реестре в разделе HKLM\CurrentControlSet\Services\ServiceName\Instances\DefaultInstance для части InstanceName пути реестра.

Имя экземпляра, указанное в параметре InstanceName , должно быть уникальным в системе.

FltAttachVolume возвращает непрозрачный указатель экземпляра для нового экземпляра в *RetInstance. Это значение указателя однозначно идентифицирует экземпляр драйвера минифильтра и остается постоянным до тех пор, пока экземпляр подключен к тому.

FltAttachVolume добавляет ссылку на непрозрачный указатель экземпляра, возвращенный в *RetInstance. Если этот указатель больше не нужен, вызывающий объект должен освободить его, вызвав FltObjectDereference. Таким образом, каждый успешный вызов FltAttachVolume должен соответствовать последующему вызову FltObjectDereference.

Чтобы подключить экземпляр драйвера минифильтра к тому на заданной высоте, вызовите FltAttachVolumeAtAltitude.

Чтобы сравнить высоту двух экземпляров драйвера минифильтра, присоединенных к одному тому, вызовите Метод FltCompareInstanceAltitudes.

Чтобы отсоединить экземпляр драйвера минифильтра от тома, вызовите FltDetachVolume.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	fltkernel.h (включая Fltkernel.h)
Библиотека	FltMgr.lib
IRQL	PASSIVE_LEVEL