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 Naming a File.

Sintassi

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

Parametri

[in] hFile

Handle per un file o 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ò essere uno dei valori seguenti.

Valore	Significato
FILE_NAME_NORMALIZED 0x0	Restituisce il nome dell'unità normalizzata. Si tratta dell'impostazione predefinita.
FILE_NAME_OPENED 0x8	Restituisce il nome del 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à. Si tratta dell'impostazione predefinita.
VOLUME_NAME_GUID 0x1	Restituire il percorso con un volume GUID percorso 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 piccola per contenere la stringa più il carattere Null di terminazione, il valore restituito è la dimensione del buffer necessaria, 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 ottenere informazioni estese 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à che non è attualmente 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 volume GUID percorso per identificarlo. Questo valore restituito può essere restituito anche se si cerca un volume GUID percorso in una condivisione di rete. I percorsi di 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.

Osservazioni

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 inizierà con un nome di dispositivo, ad esempio "\Device\HarddiskVolume1\". Questo tipo di percorso non può essere usato direttamente dai programmi Windows, in quanto è 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 su ogni lettera di unità finché non viene trovato un nome di dispositivo corrispondente.

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

Tecnologia	Sostenuto
Protocollo SMB (Server Message Block) 3.0	Sì
SMB 3.0 Transparent Failover (TFO)	Sì
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO)	Sì
Cluster Shared Volume File System (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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [app desktop \| App UWP]
server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	fileapi.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll

Vedere anche

funzioni di gestione file

Condividi tramite