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 |