FltGetVolumeGuidName-Funktion (fltkernel.h)

Artikel
12/21/2024

FltGetVolumeGuidName ruft den Volumenamen für ein bestimmtes Volume im GUID-Format (Globally Unique Identifier) des Volumes ab.

Syntax

NTSTATUS FLTAPI FltGetVolumeGuidName(
  [in]               PFLT_VOLUME     Volume,
  [in/out, optional] PUNICODE_STRING VolumeGuidName,
  [out, optional]    PULONG          BufferSizeNeeded
);

Parameter

[in] Volume

Undurchsichtiger Zeiger für das Volume. Muss ein lokales Dateisystemvolume sein. Dieser Parameter ist erforderlich und kann nicht NULL-werden.

[in/out, optional] VolumeGuidName

Zeigen Sie auf eine vom Aufrufer zugewiesene UNICODE_STRING Struktur, die den GUID-Namen des Volumes empfängt, wenn STATUS_SUCCESS zurückgegeben wird. Beachten Sie, dass der Pool für VolumeGuidName->Buffer- auch aufrufergeteilt ist.

Wenn VolumeGuidNameNULL- ist und BufferSizeNeededed- nicht NULL-ist, speichert FltGetVolumeGuidName die für die angeforderte Volume-GUID erforderliche Puffergröße im parameter BufferSizeNe ededed und gibt STATUS_BUFFER_TOO_SMALL zurück. Siehe Anmerkungen.

[out, optional] BufferSizeNeeded

Zeiger auf eine vom Aufrufer zugewiesene Variable, die die Größe des angeforderten Volume-GUID-Namens in Byte empfängt. Dieser Parameter ist optional und kann NULL-sein; Es muss jedoch nichtNULL- sein, wenn VolumeGuidName-NULL- ist, damit FltGetVolumeGuidName die für die angeforderte Volume-GUID erforderliche Puffergröße speichern kann.

Rückgabewert

FltGetVolumeGuidName gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert zurück, z. B. einen der folgenden:

Rückgabecode	Beschreibung
STATUS_BUFFER_TOO_SMALL	Der Puffer, auf den VolumeGuidName verweist, ist NULL- oder zu klein, um die Volume-GUID aufzunehmen. Wenn der Aufrufer einen Wert ohneNULL für BufferSizeNeededbereitstellt, speichert FltGetVolumeGuidName die erforderliche Puffergröße in BufferSizeNeeded. Dies wird als Fehlercode betrachtet, da der Volume-GUID-Name nicht abgerufen wurde.
STATUS_INSUFFICIENT_RESOURCES	FltGetVolumeGuidName ein Poolzuordnungsfehler aufgetreten. Dies ist ein Fehlercode.
STATUS_INVALID_DEVICE_REQUEST	Der Parameter Volume ist ein Handle für ein Netzwerkvolume. Dies ist ein Fehlercode.
STATUS_FLT_VOLUME_NOT_FOUND	Es wurde kein übereinstimmende Volume gefunden. Dies ist ein Fehlercode.

Bemerkungen

Der zurückgegebene Volume-GUID-Name wird im folgenden Format ausgedrückt:

\?? \Volume{GUID}

dabei ist GUID- ein global eindeutiger Bezeichner, der das Volume identifiziert. Dieses Format, das vom Bereitstellungs-Manager verwendet wird, wird in Unterstützende Bereitstellungs-Manager-Anforderungen in einem Speicherklassentreiberbeschrieben.

Wenn BufferSizeNeeded unbekannt ist, rufen Sie zweimal FltGetVolumeGuidName auf:

Legen Sie im ersten Aufruf VolumeGuidName- auf NULL- und BufferSizeNeededed- aufNULL-fest. FltGetVolumeGuidName- speichert die Anzahl der Bytes, die für die Volumenamen-GUID in BufferSizeNeededed benötigt werden, und gibt STATUS_BUFFER_TOO_SMALL zurück.
Legen Sie im zweiten Aufruf VolumeGuidName- auf eine Struktur fest, die die Größe des BufferSizeNeededed Werts darstellt, der im ersten Aufruf zurückgegeben wird.

FltGetVolumeGuidName kann nicht sicher von einem Rückruf vor der Bereitstellung oder nach der Bereitstellung aufgerufen werden. Es kann nicht sicher aufgerufen werden, da selbst wenn der Rückruf nach der Bereitstellung aufgerufen wird, die Bereitstellungsverarbeitung nicht vom E/A-Manager abgeschlossen wurde, und dies führt zu einem Deadlock mit dem Bereitstellungs-Manager in bestimmten Fällen.

Unter Windows Vista und höher kann ein Minifiltertreiber sicher FltGetVolumeGuidName aus seiner InstanceSetupCallback-Routine (PFLT_INSTANCE_SETUP_CALLBACK) aufrufen, da der Rückruf für den ersten E/A-Vorgang für ein neues Volume aufgerufen wird, nachdem die Bereitstellungsverarbeitung abgeschlossen wurde.

Unter Windows-Betriebssystemen vor Windows Vista kann FltGetVolumeGuidName- nicht sicher von einer InstanceSetupCallback- Routine aufgerufen werden, da der Bereitstellungs-Manager beim Halten einer Sperre möglicherweise eine Datei-E/A-Operation ausgibt, was zu einem Deadlock führen kann.

Es ist wichtig zu beachten, dass die Volume-GUID nicht mit der Volumeobjekt-ID identisch ist. Die Volume-GUIDoder eindeutigen Volumenamensist ein dateisystemunabhängiger Wert; sie wird dem zugrunde liegenden Speichervolume vom Bereitstellungs-Manager zugewiesen. Die Volumeobjekt-ID wird dem Dateisystemvolume vom Dateisystem zugewiesen.

Rufen Sie zum Abrufen der Volumeobjekt-ID für ein Volume ZwQueryVolumeInformationFile-auf, und geben Sie FileFsObjectIdInformation- für den parameter FsInformationClass an.

FltGetVolumeGuidName entspricht ungefähr der Win32-GetVolumeNameForVolumeMountPoint--Funktion. (GetVolumeNameForVolumeMountPoint ist im Microsoft Windows SDK dokumentiert.)