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

Статья
08/07/2023

FltGetVolumeGuidName получает имя тома для заданного тома в формате глобально уникального идентификатора (GUID).

Синтаксис

NTSTATUS FLTAPI FltGetVolumeGuidName(
  [in]               PFLT_VOLUME     Volume,
  [in/out, optional] PUNICODE_STRING VolumeGuidName,
  [out, optional]    PULONG          BufferSizeNeeded
);

Параметры

[in] Volume

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

[in/out, optional] VolumeGuidName

Указатель на структуру UNICODE_STRING , выделенную вызывающим объектом, которая получает guid-имя тома при возврате STATUS_SUCCESS. Имейте в виду, что пул для VolumeGuidName-Buffer> также выделяется вызывающим объектом.

Если Значение VolumeGuidName имеет значение NULL , а BufferSizeNeeded не равно NULL, FltGetVolumeGuidName сохраняет размер буфера, необходимый для идентификатора GUID запрошенного тома, в параметре BufferSizeNeeded и возвращает STATUS_BUFFER_TOO_SMALL. См. заметки.

[out, optional] BufferSizeNeeded

Указатель на переменную, выделенную вызывающим объектом, которая получает размер в байтах имени GUID запрошенного тома. Этот параметр является необязательным и может иметь значение NULL; Однако если VolumeGuidName имеет значение NULL, оно должно быть не равно NULL, чтобы FltGetVolumeGuidName сохранял размер буфера, необходимый для идентификатора GUID запрошенного тома.

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

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

Код возврата	Описание
STATUS_BUFFER_TOO_SMALL	Буфер, на который указывает Имя_тома , имеет значение NULL или слишком мал для хранения GUID тома. Если вызывающий объект предоставляет значение, отличное от NULL , для BufferSizeNeeded, FltGetVolumeGuidName сохраняет требуемый размер буфера в BufferSizeNeeded. Это считается кодом ошибки, так как идентификатор GUID тома не был получен.
STATUS_INSUFFICIENT_RESOURCES	FltGetVolumeGuidName столкнулся с ошибкой выделения пула. Это код ошибки.
STATUS_INVALID_DEVICE_REQUEST	Параметр Volume — это дескриптор сетевого тома. Это код ошибки.
STATUS_FLT_VOLUME_NOT_FOUND	Соответствующий том не найден. Это код ошибки.

где GUID — это глобальный уникальный идентификатор, идентифицирующий том. Этот формат, который совпадает с форматом, используемым диспетчером подключений, описан в разделе Поддержка запросов диспетчера подключений в драйвере класса хранилища.

Если bufferSizeNeeded неизвестен, вызовите FltGetVolumeGuidName дважды:

При первом вызове задайте для параметра VolumeGuidNameзначение NULL , а для BufferSizeNeeded — значение, отличное от NULL. FltGetVolumeGuidName сохраняет количество байтов, необходимых для GUID имени тома, в BufferSizeNeeded и возвращает STATUS_BUFFER_TOO_SMALL.
Во втором вызове задайте значение VolumeGuidName , чтобы указать на структуру, которая является размером значения BufferSizeNeeded, возвращаемого в первом вызове.

FltGetVolumeGuidName не может быть безопасно вызван из обратного вызова перед подключением или после подключения. Его невозможно вызвать безопасно, так как даже при вызове обратного вызова после подключения диспетчер ввода-вывода не завершил обработку подключения, что в некоторых случаях приводит к взаимоблокировке с диспетчером подключений.

В Windows Vista и более поздних версиях драйвер минифильтра может безопасно вызывать FltGetVolumeGuidName из своей подпрограммы InstanceSetupCallback (PFLT_INSTANCE_SETUP_CALLBACK), так как обратный вызов вызывается при первой операции ввода-вывода для нового тома после завершения обработки подключения.

В операционных системах Windows, предшествующих Windows Vista, невозможно безопасно вызвать FltGetVolumeGuidName из подпрограммы InstanceSetupCallback , так как диспетчер подключения может выполнить операцию ввода-вывода файла при удержании блокировки, что может привести к взаимоблокировке.

Важно отметить, что GUID тома не совпадает с идентификатором объекта тома. GUID тома или уникальное имя тома является независимым от файловой системы значением; Он назначается базовому тому хранилища диспетчером подключения. Идентификатор объекта тома назначается тому файловой системы файловой системой.

Чтобы получить идентификатор объекта тома для тома, вызовите ZwQueryVolumeInformationFile, указав FileFsObjectIdInformation для параметра FsInformationClass .

FltGetVolumeGuidName примерно эквивалентно функции Win32 GetVolumeNameForVolumeMountPoint . (GetVolumeNameForVolumeMountPoint задокументирован в Microsoft Windows SDK.)

Требования

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

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

FILE_FS_OBJECTID_INFORMATION

PFLT_INSTANCE_SETUP_CALLBACK

UNICODE_STRING

ZwQueryVolumeInformationFile

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