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 |
|---|---|
|
Restituisce il nome dell'unità normalizzata. Questo è il valore predefinito. |
|
Restituisce il nome file aperto (non normalizzato). |
Questo parametro può includere anche uno dei valori seguenti.
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 |
|---|---|
|
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. |
|
Memoria insufficiente per completare l'operazione. |
|
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 | 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
| 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 |