FltGetVolumeName 函数 (fltkernel.h)

项目
02/26/2024

FltGetVolumeName 例程获取给定卷的卷名。

语法

NTSTATUS FLTAPI FltGetVolumeName(
  [in]                PFLT_VOLUME     Volume,
  [in, out, optional] PUNICODE_STRING VolumeName,
  [out, optional]     PULONG          BufferSizeNeeded
);

参数

[in] Volume

卷的不透明指针。此参数是必需的，不能为 NULL。

[in, out, optional] VolumeName

指向调用方分配 的UNICODE_STRING 结构的指针，该结构包含卷的非永久性设备对象名称 (，例如，返回STATUS_SUCCESS时，“\Device\HarddiskVolume1”) 。请注意，VolumeName-Buffer> 的池也是调用方分配的。

此参数是可选的，可以为 NULL;但是，如果 BufferSizeNeeded 为 NULL，则它必须为非 NULL。如果此参数为 NULL 且 BufferSizeNeeded 不为 NULL， 则 FltGetVolumeName 将请求的卷名称所需的缓冲区大小存储在 BufferSizeNeeded 参数中，并返回STATUS_BUFFER_TOO_SMALL。请参阅“备注”。

[out, optional] BufferSizeNeeded

指向调用方分配的变量的指针，该变量接收所请求卷名称的大小（以字节为单位）。此参数是可选的，可以为 NULL;但是，如果 VolumeName 为 NULL，则它必须为非 NULL，以便 FltGetVolumeName 可以存储请求的卷名称所需的缓冲区大小。

返回值

FltGetVolumeName 返回以下 NTSTATUS 值之一：

返回代码	说明
STATUS_SUCCESS	VolumeName 指向的 UNICODE_STRING 结构包含结构的 Buffer 成员中卷的名称，以及 Length 成员中名称的长度（以字节为单位）。
STATUS_BUFFER_TOO_SMALL	VolumeName 指向的 UNICODE_STRING 结构的 Buffer 成员太小， (其 MaximumLength 成员) 指示，无法包含整个卷名称。这是错误代码。
STATUS_INVALID_PARAMETER	VolumeName 和 BufferSizeNeeded 均为 NULL。这是错误代码。

注解

要使此例程成功，VolumeName) (指向的 UNICODE_STRING 结构的 Buffer 成员必须足够大（由其 MaximumLength 成员指示）才能包含整个卷名称字符串。

以下伪代码显示了一种在 BufferSizeNeeded 未知的情况下成功获取卷名称的可能方法：

调用 FltGetVolumeName 以确定 Buffer 所需的池和 MaximumLength 所需的大小。例如： FltGetVolumeName(VolumePtr, NULL, &VolumeNameSize);
为 Buffer 分配VolumeNameSize池的字节数，并将 MaximumLength 设置为 VolumeNameSize。
再次调用 FltGetVolumeName 以获取卷名称。例如： FltGetVolumeName(VolumePtr, &VolumeNameStruct, NULL);