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

Статья
08/07/2023

Подпрограмма FltGetVolumeInstanceFromName возвращает непрозрачный указатель экземпляра для заданного экземпляра драйвера минифильтра на заданном томе.

Синтаксис

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

Параметры

[in, optional] Filter

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

[in] Volume

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

[in, optional] InstanceName

Указатель на структуру UNICODE_STRING , выделенную вызывающим объектом, которая содержит имя экземпляра на томе. (Это значение InstanceName , переданное во FltAttachVolume или FltAttachVolumeAtAltitude при создании экземпляра.) Этот параметр является необязательным и может иметь значение NULL. Если значение равно NULL, Функция FltGetVolumeInstanceFromName возвращает найденный экземпляр с наибольшим соответствием.

[out] RetInstance

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

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

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

Код возврата	Описание
STATUS_FLT_DELETING_OBJECT	Экземпляр сносится. Это код ошибки.
STATUS_FLT_INSTANCE_NOT_FOUND	Соответствующий экземпляр не найден. Это код ошибки.

FltGetVolumeInstanceFromName выполняет поиск в списке экземпляров драйвера минифильтра, присоединенных к тому, указанному в параметре Volume , в порядке уменьшения высоты, начиная с самого верхнего экземпляра. Если несколько экземпляров совпадают с заданными значениями для параметров Filter, Volume и InstanceName , Функция FltGetVolumeInstanceFromName возвращает найденный экземпляр с наибольшим соответствием.

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

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

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

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

Требования

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

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

FltAttachVolume

FltAttachVolumeAtAltitude

FltObjectDereference

UNICODE_STRING

Share via