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 值：

傳回碼	Description
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);
設定 VolumeNameSizeBuffer 的集區位元組，並將 MaximumLength 設定為 VolumeNameSize。
再次呼叫 FltGetVolumeName 以取得磁碟區名稱。例如：FltGetVolumeName(VolumePtr, &VolumeNameStruct, NULL);