Condividi tramite


Funzione GetFinalPathNameByHandleA (fileapi.h)

Recupera il percorso finale per il file specificato.

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

Sintassi

DWORD GetFinalPathNameByHandleA(
  [in]  HANDLE hFile,
  [out] LPSTR  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
Restituire il percorso con il percorso del dispositivo del volume.

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".

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

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

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

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

Requisito Valore
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 (include Windows.h)
Libreria Kernel32.lib
DLL Kernel32.dll

Vedere anche

Funzioni di gestione file