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

Статья
12/21/2024

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->буфера также выделяется вызывающим объектом.

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

[out, optional] BufferSizeNeeded

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

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

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

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

Замечания

Возвращаемое имя GUID тома выражается в следующем формате:

\?? \Volume{GUID}

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

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

При первом вызове задайте VolumeGuidName значение NULL и BufferSizeNeeded значение NULLnull. 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 документируется в пакете SDK для Microsoft Windows.)

Требования

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

См. также

FILE_FS_OBJECTID_INFORMATION

PFLT_INSTANCE_SETUP_CALLBACK

UNICODE_STRING

ZwQueryVolumeInformationFile

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