Funzione GetVolumePathNameW (fileapi.h)

  • Articolo

Recupera il punto di montaggio del volume in cui viene montato il percorso specificato.

Sintassi

BOOL GetVolumePathNameW(
  [in]  LPCWSTR lpszFileName,
  [out] LPWSTR  lpszVolumePathName,
  [in]  DWORD   cchBufferLength
);

Parametri

[in] lpszFileName

Puntatore alla stringa del percorso di input. Sia i nomi di file assoluti che relativi, ad esempio "..", sono accettabili in questo percorso.

Se si specifica una directory relativa o un nome di file senza un qualificatore di volume, GetVolumePathName restituisce la lettera di unità del volume di avvio.

Se questo parametro è una stringa vuota, "", la funzione ha esito negativo, ma l'ultimo errore è impostato su ERROR_SUCCESS.

[out] lpszVolumePathName

Puntatore a una stringa che riceve il punto di montaggio del volume per il percorso di input.

[in] cchBufferLength

Lunghezza del buffer di output, in TCHAR.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Se viene passato un percorso specificato, GetVolumePathName restituisce il percorso del punto di montaggio del volume, il che significa che restituisce la radice del volume in cui si trova il punto finale del percorso specificato.

Si supponga, ad esempio, che il volume D sia montato in C:\Mnt\Ddrive corrispondenza del volume E montato in C:\Mnt\Ddrive\Mnt\Edrive. Si supponga inoltre di avere un file con il percorso E:\Dir\Subdir\MyFile. Se si passa C:\Mnt\Ddrive\Mnt\Edrive\Dir\Subdir\MyFile a GetVolumePathName, restituisce il percorso C:\Mnt\Ddrive\Mnt\Edrive\.

Se una directory relativa o un file viene passata senza un qualificatore di volume, la funzione restituisce la lettera di unità del volume di avvio. La lettera di unità del volume di avvio viene restituita anche se viene specificato un file o un nome di directory non valido senza un qualificatore di volume valido. Se viene specificato un identificatore di volume valido e il volume esiste, ma viene specificato un file o un nome di directory non valido, la funzione avrà esito positivo e tale nome del volume verrà restituito. Per esempi, vedere la sezione Esempi di questo argomento.

È necessario specificare un percorso dello spazio dei nomi Win32 valido. Se si specifica un percorso dello spazio dei nomi NT, ad esempio \DosDevices\H: o \Device\HardDiskVolume6, la funzione restituisce la lettera di unità del volume di avvio, non la lettera di unità del percorso dello spazio dei nomi NT.

Per altre informazioni sui nomi dei percorsi e sugli spazi dei nomi, vedere Denominazione di file, percorsi e spazi dei nomi.

È possibile specificare sia percorsi locali che remoti. Se si specifica un percorso locale, GetVolumePathName restituisce un percorso completo il cui prefisso è il prefisso più lungo che rappresenta un volume.

Se viene specificata una condivisione di rete, GetVolumePathName restituisce il percorso più breve per cui GetDriveType restituisce DRIVE_REMOTE, ovvero il percorso viene convalidato come unità remota esistente, a cui l'utente corrente può accedere.

Esistono alcuni casi speciali che non restituiscono una barra rovesciata finale. Questi si verificano quando la lunghezza del buffer di output è troppo breve. Ad esempio, se lpszFileName è e lpszVolumePathName è C: di 4 caratteri, il valore restituito è ; tuttavia, se lpszVolumePathName è di 3 caratteri, il valore restituito è C:C:\. Un modo più sicuro ma più lento per impostare le dimensioni del buffer restituito consiste nel chiamare la funzione GetFullPathName e quindi assicurarsi che la dimensione del buffer sia almeno la stessa dimensione del percorso completo restituito da GetFullPathName . Se il buffer di output è troppo breve, la funzione avrà esito negativo e restituirà un errore.

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Tecnologia Supportato
Protocollo SMB (Server Message Block) 3.0 No
Failover trasparente SMB 3.0 (TFO) No
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO) No
File system del volume condiviso del cluster (CsvFS) Sì
File system resiliente (ReFS) Sì

SMB non supporta le funzioni di gestione dei volumi.

Elementi percorso finale

Gli elementi di percorso finali non validi vengono ignorati. Per i percorsi remoti, l'intero percorso (non solo gli elementi finali) è considerato non valido se una delle condizioni seguenti è true:

  • Il percorso non è formato correttamente.
  • Il percorso non esiste.
  • L'utente corrente non ha accesso al percorso.

Punti di giunzione e cartelle montate

Se il percorso specificato attraversa un punto di giunzione, GetVolumePathName restituisce il volume a cui fa riferimento il punto di giunzione. Ad esempio, se W:\Adir è un punto di giunzione che punta a C:\Adir, getVolumePathName richiamato su W:\Adir\Afile restituisce C:\. Se il percorso specificato attraversa più punti di giunzione, viene seguita l'intera catena e GetVolumePathName restituisce il volume a cui fa riferimento l'ultimo punto di giunzione della catena.

Se viene specificato un percorso remoto di una cartella montata o un punto di giunzione, il percorso viene analizzato come percorso remoto e la cartella montata o il punto di giunzione vengono ignorati. Ad esempio, se C:\Dir_C è collegato a e C: viene eseguito il mapping a D:\Dir_DX: in un computer remoto, chiamando GetVolumePathName e specificando X:\Dir_C nel computer remoto restituisce X:\.

Esempio

Per il set di esempi seguente, U: viene mappato al computer \\_YourComputer_\C$remoto e Q è un'unità locale.

Percorso specificato La funzione restituisce
\\_YourComputer_\C$\Windows \\_YourComputer_\C$\
\\?\UNC\_YourComputer_\C$\Windows \\?\UNC\_YourComputer_\C$\
Q:\Windows Q:\
\\?\Q:\Windows \\?\Q:\
\\.\Q:\Windows \\.\Q:\
\\?\UNC\W:\Windows FALSE con errore 123 perché un percorso remoto specificato non era valido; La condivisione W$ non esiste o non è concesso alcun accesso utente.
C:\COM2 (che esiste) \\.\COM2\
C:\COM3 (non esistente) FALSE con errore 123 perché è stato specificato un dispositivo COM non esistente.

Per il set di esempi seguente, i percorsi contengono elementi percorso finale non validi.

Percorso specificato La funzione restituisce
G:\invalid (percorso non valido) G:\
\\.\I:\aaa\invalid (percorso non valido) \\.\I:\
\\_YourComputer_\C$\invalid (elemento percorso finale non valido) \\_YourComputer_\C$\

Requisiti

Requisito Valore
Client minimo supportato Windows XP [solo app desktop]
Server minimo supportato Windows Server 2003 [solo app desktop]
Piattaforma di destinazione Windows
Intestazione fileapi.h (includere Windows.h)
Libreria Kernel32.lib
DLL Kernel32.dll

Vedere anche