Funzione GetFinalPathNameByHandleW (fileapi.h)

Articolo
03/14/2023

Recupera il percorso finale per il file specificato.

Per altre informazioni sui nomi di file e percorsi, vedere Denominazione di un file.

Sintassi

DWORD GetFinalPathNameByHandleW(
  [in]  HANDLE hFile,
  [out] LPWSTR lpszFilePath,
  [in]  DWORD  cchFilePath,
  [in]  DWORD  dwFlags
);

Parametri

[in] hFile

Handle di un file o di una directory.

[out] lpszFilePath

Puntatore a un buffer che riceve il percorso di hFile.

[in] cchFilePath

Dimensioni di lpszFilePath, in TCHARs. Questo valore deve includere un carattere di terminazione NULL .

[in] dwFlags

Tipo di risultato da restituire. Questo parametro può avere uno dei valori seguenti.

Valore	Significato
FILE_NAME_NORMALIZED 0x0	Restituisce il nome dell'unità normalizzata. Questo è il valore predefinito.
FILE_NAME_OPENED 0x8	Restituisce il nome file aperto (non normalizzato).

Questo parametro può includere anche uno dei valori seguenti.

Valore	Significato
VOLUME_NAME_DOS 0x0	Restituisce il percorso con la lettera di unità. Questo è il valore predefinito.
VOLUME_NAME_GUID 0x1	Restituisce il percorso con un percorso GUID del volume anziché il nome dell'unità.
VOLUME_NAME_NONE 0x4	Restituisce il percorso senza informazioni sull'unità.
VOLUME_NAME_NT 0x2	Restituisce il percorso dell'oggetto dispositivo NT.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è la lunghezza della stringa ricevuta da lpszFilePath, in TCHARs. Questo valore non include le dimensioni del carattere Null di terminazione.

Windows Server 2008 e Windows Vista: Per la versione ANSI di questa funzione, GetFinalPathNameByHandleA, il valore restituito include le dimensioni del carattere Null di terminazione.

Se la funzione ha esito negativo perché lpszFilePath è troppo piccolo per contenere la stringa più il carattere Null di terminazione, il valore restituito è la dimensione del buffer richiesta, in TCHARs. Questo valore include le dimensioni del carattere Null di terminazione.

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

Codice restituito	Descrizione
ERROR_PATH_NOT_FOUND	Può essere restituito se si cerca una lettera di unità e non esiste. Ad esempio, l'handle è stato aperto in un'unità non montata o se si crea un volume e non si assegna una lettera di unità. Se un volume non ha una lettera di unità, è possibile usare il percorso GUID del volume per identificarlo. Questo valore restituito può essere restituito anche se si sta cercando un percorso GUID del volume in una condivisione di rete. I percorsi GUID del volume non vengono creati per le condivisioni di rete.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente per completare l'operazione.
ERROR_INVALID_PARAMETER	Sono stati specificati flag non validi per dwFlags.

Commenti

Il protocollo SMB (Server Message Block) non supporta le query per i percorsi normalizzati. Di conseguenza, quando si chiama questa funzione passando l'handle di un file aperto usando SMB e con il flag FILE_NAME_NORMALIZED, la funzione suddivide il percorso nei relativi componenti e tenta di eseguire una query per il nome normalizzato di ognuno di questi componenti. Se l'utente non dispone dell'autorizzazione di accesso a uno di questi componenti, la chiamata di funzione ha esito negativo con ERROR_ACCESS_DENIED.

Un percorso finale è il percorso restituito quando un percorso viene risolto completamente. Ad esempio, per un collegamento simbolico denominato "C:\tmp\mydir" che punta a "D:\yourdir", il percorso finale sarà "D:\yourdir".

Quando si usa VOLUME_NAME_DOS, la stringa restituita da questa funzione usa la sintassi "\\?\". Per altre informazioni, vedere CreateFile.

Quando si usa VOLUME_NAME_GUID, il percorso restituito inizierà con un percorso GUID del volume formattato come "\\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\".

Quando si usa VOLUME_NAME_NT, il percorso restituito è relativo a un oggetto dispositivo NT e inizia con un nome di dispositivo, ad esempio "\Device\HarddiskVolume1\". Questo tipo di percorso non può essere usato direttamente dai programmi Windows, perché è simile a un percorso relativo.

Alcuni driver di terze parti possono creare una lettera di unità o un punto di montaggio senza usare Mount Manager. Se gestione montaggio non è stato usato per creare l'unità, VOLUME_NAME_DOS o VOLUME_NAME_GUID non avrà esito positivo; saranno disponibili solo VOLUME_NAME_NT . Per determinare la lettera di unità per il percorso del dispositivo del volume, usare la funzione QueryDosDevice in ogni lettera di unità fino a quando non viene trovato un nome di dispositivo corrispondente.

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

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

Esempi

Nell'esempio seguente viene illustrato l'uso della funzione GetFinalPathNameByHandle .

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

#define BUFSIZE MAX_PATH

void __cdecl _tmain(int argc, TCHAR *argv[])
{
    TCHAR Path[BUFSIZE];
    HANDLE hFile;
    DWORD dwRet;

    printf("\n");
    if( argc != 2 )
    {
        printf("ERROR:\tIncorrect number of arguments\n\n");
        printf("%s <file_name>\n", argv[0]);
        return;
    }

    hFile = CreateFile(argv[1],               // file to open
                       GENERIC_READ,          // open for reading
                       FILE_SHARE_READ,       // share for reading
                       NULL,                  // default security
                       OPEN_EXISTING,         // existing file only
                       FILE_ATTRIBUTE_NORMAL, // normal file
                       NULL);                 // no attr. template

    if( hFile == INVALID_HANDLE_VALUE)
    {
        printf("Could not open file (error %d\n)", GetLastError());
        return;
    }

    dwRet = GetFinalPathNameByHandle( hFile, Path, BUFSIZE, VOLUME_NAME_NT );
    if(dwRet < BUFSIZE)
    {
        _tprintf(TEXT("\nThe final path is: %s\n"), Path);
    }
    else printf("\nThe required buffer size is %d.\n", dwRet);

    CloseHandle(hFile);
}

Nota

L'intestazione fileapi.h definisce GetFinalPathNameByHandle come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti


Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	fileapi.h (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll

Vedere anche

Funzioni di gestione file

Condividi tramite