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

Статья
02/06/2025

Подпрограмма 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. (Установка этого параметра недопустимому значению приводит к тому, что система БУДЕТ УТВЕРЖДАТЬ в проверенной сборке.)

[in, optional] InstanceName

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

[out] RetInstance

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

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

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

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

Замечания

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

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

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

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

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

Требования

Требование	Ценность
целевая платформа	Всеобщий
заголовка	fltkernel.h (include Fltkernel.h)
библиотеки	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL

См. также

FltAttachVolume

FltAttachVolumeAtAltitude

FltObjectDereference

UNICODE_STRING

Поделиться через