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

Статья
02/29/2024

FltAttachVolumeAtAltitude — это подпрограмма поддержки отладки, которая присоединяет экземпляр драйвера минифильтра к тому на указанной высоте, переопределяя все параметры в INF-файле драйвера минифильтра.

Синтаксис

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

Параметры

[in, out] Filter

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

[in, out] Volume

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

[in] Altitude

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

[in, optional] InstanceName

Указатель на структуру UNICODE_STRING , содержащую имя экземпляра для нового экземпляра. Этот параметр является необязательным и может иметь значение NULL. Если значение равно NULL, FltAttachVolumeAtAltitude создает имя экземпляра из имени драйвера минифильтра и строки высоты, на которую указывает Altitude . Созданное имя при необходимости усекается для INSTANCE_NAME_MAX_CHARS символов.

[out, optional] RetInstance

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

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

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

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

Термин "высота" относится к положению, которое экземпляр занимает (или должен занимать) в стеке экземпляров драйвера минифильтра для тома. Чем выше высота, тем дальше экземпляр находится от базовой файловой системы в стеке. На заданной высоте на заданном томе можно подключить только один экземпляр.

Высота задается строкой высоты, которая представляет собой массив расширенных символов, содержащий одну или несколько десятичных цифр от 0 до 9; массив может содержать одну десятичную запятую. Например, "100,123456" и "03333" являются допустимыми строками высоты.

Строка "03333" представляет большую высоту, чем "100,123456" (начальные и конечные нули игнорируются.) Другими словами, экземпляр с высотой 03333 находится дальше от базовой файловой системы, чем экземпляр с высотой 100,123456. Однако это сравнение имеет смысл только в том случае, если оба экземпляра подключены к одному тому.

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

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

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

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

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

Требования

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