Funzione FltGetVolumeGuidName (fltkernel.h)

Articolo
12/21/2024

FltGetVolumeGuidName ottiene il nome del volume per un determinato volume, in formato GUID (Global Unique Identifier).

Sintassi

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

Parametri

[in] Volume

Puntatore opaco per il volume. Deve essere un volume del file system locale. Questo parametro è obbligatorio e non può essere NULL.

[in/out, optional] VolumeGuidName

Puntatore a una struttura UNICODE_STRING allocata dal chiamante che riceve il nome GUID del volume quando viene restituito STATUS_SUCCESS. Tenere presente che anche il pool per VolumeGuidName->buffer viene allocato dal chiamante.

Se VolumeGuidName è null e bufferSizeNeeded non è null, FltGetVolumeGuidName archivia le dimensioni del buffer necessarie per il GUID del volume richiesto nel parametro BufferSizeNeeded e restituisce STATUS_BUFFER_TOO_SMALL. Vedere la sezione Osservazioni.

[out, optional] BufferSizeNeeded

Puntatore a una variabile allocata dal chiamante che riceve le dimensioni, in byte, del nome GUID del volume richiesto. Questo parametro è facoltativo e può essere NULL; Tuttavia, deve essere nonnull se VolumeGuidName è NULL in modo che FltGetVolumeGuidName possa archiviare le dimensioni del buffer necessarie per il GUID del volume richiesto.

Valore restituito

FltGetVolumeGuidName restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice restituito	Descrizione
STATUS_BUFFER_TOO_SMALL	Il buffer a cui punta volumeGuidName è NULL o troppo piccolo per contenere il GUID del volume. Se il chiamante fornisce un valore di NULL nonper BufferSizeNeeded, FltGetVolumeGuidName archivia le dimensioni del buffer necessarie in BufferSizeNeeded. Si tratta di un codice di errore perché il nome GUID del volume non è stato recuperato.
STATUS_INSUFFICIENT_RESOURCES	FltGetVolumeGuidName rilevato un errore di allocazione del pool. Si tratta di un codice di errore.
STATUS_INVALID_DEVICE_REQUEST	Il parametro Volume è un handle per un volume di rete. Si tratta di un codice di errore.
STATUS_FLT_VOLUME_NOT_FOUND	Non è stato trovato alcun volume corrispondente. Si tratta di un codice di errore.

Osservazioni

Il nome GUID del volume restituito è espresso nel formato seguente:

\?? \Volume{GUID}

dove GUID è un identificatore univoco globale che identifica il volume. Questo formato, uguale a quello usato dal gestore di montaggio, è descritto in supporto delle richieste di Gestione montaggio in un driver di classe di archiviazione.

Se BufferSizeNeeded è sconosciuto, chiamare FltGetVolumeGuidName due volte:

Nella prima chiamata impostare VolumeGuidName su NULL e BufferSizeNeeded suNULL. FltGetVolumeGuidName archivierà il numero di byte necessari per il GUID del nome del volume in BufferSizeNeeded e restituirà STATUS_BUFFER_TOO_SMALL.
Nella seconda chiamata impostare VolumeGuidName in modo che punti a una struttura che corrisponde alle dimensioni del valore BufferSizeNeeded restituito nella prima chiamata.

FltGetVolumeGuidName non può essere chiamato in modo sicuro da un callback di pre-montaggio o post-montaggio. Non può essere chiamato in modo sicuro perché anche quando viene chiamato il callback post-montaggio, l'elaborazione del montaggio non è stata completata dal gestore di I/O e questo causa un deadlock con il gestore di montaggio in determinati casi.

In Windows Vista e versioni successive, un driver minifiltro può chiamare in modo sicuro FltGetVolumeGuidName dalla relativa routine InstanceSetupCallback (PFLT_INSTANCE_SETUP_CALLBACK) perché il callback viene chiamato nella prima operazione di I/O per un nuovo volume dopo il completamento dell'elaborazione del montaggio.

Nei sistemi operativi Windows precedenti a Windows Vista, FltGetVolumeGuidName non può essere chiamato in modo sicuro da una routine InstanceSetupCallback perché la gestione montaggio potrebbe emettere un'operazione di I/O di file mantenendo un blocco, che può causare un deadlock.

È importante notare che il GUID del volume non è uguale all'ID oggetto volume. Il GUID del volume o nome di volume univoco, è un valore indipendente dal file system; viene assegnato al volume di archiviazione sottostante dal gestore di montaggio. L'ID oggetto volume viene assegnato al volume del file system dal file system.

Per ottenere l'ID oggetto volume per un volume, chiamare ZwQueryVolumeInformationFile, specificando fileFsObjectIdInformation per il parametro FsInformationClass.

fltGetVolumeGuidName equivale approssimativamente alla funzione Win32 GetVolumeNameForVolumeMountPoint. (GetVolumeNameForVolumeMountPoint è documentato in Microsoft Windows SDK.