FltGetVolumeGuidName-Funktion (fltkernel.h)

Artikel
02/26/2024

FltGetVolumeGuidName ruft den Volumenamen für ein bestimmtes Volume im GUID-Format (Volume Globally Unique Identifier) 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 darf nicht NULL sein.

[in/out, optional] VolumeGuidName

Zeiger 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> ebenfalls aufruferseitig zugeordnet ist.

Wenn VolumeGuidNameNULL und BufferSizeNeeded nicht NULL ist, speichert FltGetVolumeGuidName die Puffergröße, die für die angeforderte Volume-GUID im Parameter BufferSizeNeeded erforderlich ist, und gibt STATUS_BUFFER_TOO_SMALL zurück. Siehe Hinweise.

[out, optional] BufferSizeNeeded

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

Rückgabewert

FltGetVolumeGuidName gibt STATUS_SUCCESS oder einen entsprechenden 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 ungleich NULL für BufferSizeNeeded bereitstellt, speichert FltGetVolumeGuidName die erforderliche Puffergröße in BufferSizeNeeded. Dies gilt als Fehlercode, da der Volume-GUID-Name nicht abgerufen wurde.
STATUS_INSUFFICIENT_RESOURCES	FltGetVolumeGuidName ist ein Poolzuordnungsfehler aufgetreten. Dies ist ein Fehlercode.
STATUS_INVALID_DEVICE_REQUEST	Der Volume-Parameter 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.

Hinweise

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

\?? \Volume{GUID}

wobei GUID ein global eindeutiger Bezeichner ist, der das Volume identifiziert. Dieses Format, das mit dem vom Bereitstellungs-Manager identisch ist, wird unter Unterstützung von Einbindungs-Manager-Anforderungen in einem Speicherklassentreiber beschrieben.

Wenn BufferSizeNeeded unbekannt ist, rufen Sie FltGetVolumeGuidName zweimal auf:

Legen Sie beim ersten Aufruf VolumeGuidName auf NULL und BufferSizeNeeded auf non-NULL fest. FltGetVolumeGuidName speichert die Anzahl der Bytes, die für den Volumenamen GUID in BufferSizeNeeded benötigt werden, und gibt STATUS_BUFFER_TOO_SMALL zurück.
Legen Sie beim zweiten Aufruf VolumeGuidName so fest, dass er auf eine Struktur verweist, die die Größe des BufferSizeNeeded-Werts entspricht, der beim ersten Aufruf zurückgegeben wird.

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

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

Unter Windows-Betriebssystemen vor Windows Vista kann FltGetVolumeGuidName nicht sicher von einer InstanzSetupCallback-Routine aufgerufen werden, da der Bereitstellungs-Manager möglicherweise einen Datei-E/A-Vorgang ausgibt, während eine Sperre gedrückt wird, 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-GUID oder der eindeutige Volumename ist ein dateisystemunabhängiger Wert. es wird dem zugrunde liegenden Speichervolume vom Bereitstellungs-Manager zugewiesen. Die Volumeobjekt-ID wird dem Dateisystemvolume vom Dateisystem zugewiesen.

Um die Volume-Objekt-ID für ein Volume abzurufen, rufen Sie ZwQueryVolumeInformationFile auf, und geben Sie FileFsObjectIdInformation für den FsInformationClass-Parameter an.

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