FltGetVolumeGuidName 函数 (fltkernel.h)

  • 项目

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 结构的指针，该结构在返回STATUS_SUCCESS时接收卷的 GUID 名称。 请注意，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 VolumeGuidName 指向的缓冲区为 NULL 或太小，无法容纳卷 GUID。 如果调用方为 BufferSizeNeeded 提供非 NULL 值，则 FltGetVolumeGuidName 会将所需的缓冲区大小存储在 BufferSizeNeeded 中。 这被视为错误代码，因为未检索卷 GUID 名称。
STATUS_INSUFFICIENT_RESOURCES FltGetVolumeGuidName 遇到池分配失败。 这是错误代码。
STATUS_INVALID_DEVICE_REQUEST Volume 参数是网络卷的句柄。 这是错误代码。
STATUS_FLT_VOLUME_NOT_FOUND 找不到匹配的卷。 这是错误代码。

注解

返回的卷 GUID 名称采用以下格式表示：

\??\Volume{GUID}

其中 GUID 是标识卷的全局唯一标识符。 此格式与装载管理器使用的格式相同，在 存储类驱动程序中支持装载管理器请求中介绍。

如果 BufferSizeNeeded 未知，请调用 FltGetVolumeGuidName 两次：

  • 在第一次调用时，将 VolumeGuidName 设置为 NULL ，将 BufferSizeNeeded 设置为非 NULL。 FltGetVolumeGuidName 将在 BufferSizeNeeded 中存储卷名称 GUID 所需的字节数，并返回STATUS_BUFFER_TOO_SMALL。
  • 在第二次调用中，将 VolumeGuidName 设置为指向结构，该结构是第一次调用中返回的 BufferSizeNeeded 值的大小。

无法从装载前或装载后回调安全地调用 FltGetVolumeGuidName。 无法安全地调用它，因为即使调用了装载后回调，I/O 管理器也尚未完成装载处理，这在某些情况下会导致装载管理器出现死锁。

在 Windows Vista 及更高版本上，微筛选器驱动程序可以从其 InstanceSetupCallback 例程安全地调用 FltGetVolumeGuidName， (PFLT_INSTANCE_SETUP_CALLBACK) ，因为在完成所有装载处理后，对新卷的第一个 I/O 操作调用回调。

在早于 Windows Vista 的 Windows 操作系统上，无法从 InstanceSetupCallback 例程安全地调用 FltGetVolumeGuidName，因为装载管理器可能会在持有锁时发出文件 I/O 操作，从而导致死锁。

请务必注意，卷 GUID 与卷对象 ID 不同。 卷 GUID 或唯一卷名称是独立于文件系统的值;它由装载管理器分配给基础存储卷。 卷对象 ID 由文件系统分配给文件系统卷。

若要获取卷的卷对象 ID，请调用 ZwQueryVolumeInformationFile，为 FsInformationClass 参数指定 FileFsObjectIdInformation。

FltGetVolumeGuidName 大致相当于 Win32 GetVolumeNameForVolumeMountPoint 函数。 (.Microsoft Windows SDK.) 中记录了 GetVolumeNameForVolumeMountPoint

要求

要求 值
目标平台 通用
标头 fltkernel.h (包括 Fltkernel.h)
Library FltMgr.lib
DLL Fltmgr.sys
IRQL PASSIVE_LEVEL

另请参阅

FILE_FS_OBJECTID_INFORMATION

PFLT_INSTANCE_SETUP_CALLBACK

UNICODE_STRING

ZwQueryVolumeInformationFile