Funzione GetFullPathNameA (fileapi.h)
Recupera il percorso completo e il nome file del file specificato.
Per eseguire questa operazione come operazione transazionata, utilizzare la funzione GetFullPathNameTransacted .
Per altre informazioni sui nomi di file e percorsi, vedere Nomi file, percorsi e spazi dei nomi.
Sintassi
DWORD GetFullPathNameA(
[in] LPCSTR lpFileName,
[in] DWORD nBufferLength,
[out] LPSTR lpBuffer,
[out] LPSTR *lpFilePart
);
Parametri
[in] lpFileName
Nome del file.
Questo parametro può essere breve (formato 8.3) o nome di file lungo. Questa stringa può anche essere un nome di condivisione o di volume.
[in] nBufferLength
Dimensioni del buffer per ricevere la stringa con terminazione Null per l'unità e il percorso, in TCHAR.
[out] lpBuffer
Puntatore a un buffer che riceve la stringa con terminazione Null per l'unità e il percorso.
[out] lpFilePart
Puntatore a un buffer che riceve l'indirizzo (all'interno di lpBuffer) del componente del nome file finale nel percorso.
Questo parametro può essere NULL.
Se lpBuffer fa riferimento a una directory e non a un file, lpFilePart riceve zero.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è la lunghezza, in TCHARs, della stringa copiata in lpBuffer, senza includere il carattere Null di terminazione.
Se il buffer lpBuffer è troppo piccolo per contenere il percorso, il valore restituito è la dimensione, in TCHAR, del buffer necessario per contenere il percorso e il 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.
Commenti
GetFullPathName unisce il nome dell'unità e della directory corrente con un nome di file specificato per determinare il percorso completo e il nome file di un file specificato. Calcola anche l'indirizzo della parte del nome file del percorso completo e del nome file.
Questa funzione non verifica che il percorso e il nome file risultanti siano validi o che visualizzino un file esistente nel volume associato.
Si noti che il parametro lpFilePart non richiede spazio buffer stringa, ma sufficiente solo per un singolo indirizzo. Questo perché restituisce semplicemente un indirizzo all'interno del buffer già esistente per lpBuffer.
I nomi di condivisione e volume sono input validi per lpFileName. Ad esempio, l'elenco seguente identità il percorso restituito e i nomi di file se test-2 è un computer remoto e U: è un'unità mappata di rete la cui directory corrente è la radice del volume:
- Se si specifica "\\test-2\q$\lh", il percorso restituito è "\\test-2\q$\lh"
- Se si specifica "\\?\UNC\test-2\q$\lh", il percorso restituito è "\\?\UNC\test-2\q$\lh"
- Se si specifica "U:" il percorso restituito è la directory corrente nell'unità "U:\"
Se il valore restituito è maggiore o uguale al valore specificato in nBufferLength, è possibile chiamare di nuovo la funzione con un buffer sufficientemente grande da contenere il percorso. Per un esempio di questo caso oltre all'uso del buffer di lunghezza zero per l'allocazione dinamica, vedere la sezione Codice di esempio.
I percorsi relativi passati alla funzione GetFullPathName vengono interpretati come relativi alla directory corrente del processo. Lo stato della directory corrente scritto dalla funzione SetCurrentDirectory è globale per il processo e può essere modificato da qualsiasi thread in qualsiasi momento. Le applicazioni devono tenere presente che le chiamate consecutive alla funzione GetFullPathName con un percorso relativo possono produrre risultati diversi se la directory corrente cambia tra le due chiamate.
Per evitare problemi causati da risultati incoerenti, le applicazioni multithreading e il codice della libreria condivisa devono evitare l'uso di percorsi relativi. Se viene ricevuto un percorso relativo, deve essere utilizzato una sola volta, passando il percorso relativo direttamente a una funzione come CreateFile oppure convertendolo in un percorso assoluto e usando il percorso assoluto da tale punto in avanti.
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
L'esempio C++ seguente illustra un uso di base di GetFullPathName, GetLongPathName e GetShortPathName. Per un altro esempio che usa l'allocazione dinamica, vedere GetShortPathName.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#define BUFSIZE 4096
#define LONG_DIR_NAME TEXT("c:\\longdirectoryname")
void _tmain(int argc, TCHAR *argv[])
{
DWORD retval=0;
BOOL success;
TCHAR buffer[BUFSIZE]=TEXT("");
TCHAR buf[BUFSIZE]=TEXT("");
TCHAR** lppPart={NULL};
if( argc != 2 )
{
_tprintf(TEXT("Usage: %s [file]\n"), argv[0]);
return;
}
// Retrieve the full path name for a file.
// The file does not need to exist.
retval = GetFullPathName(argv[1],
BUFSIZE,
buffer,
lppPart);
if (retval == 0)
{
// Handle an error condition.
printf ("GetFullPathName failed (%d)\n", GetLastError());
return;
}
else
{
_tprintf(TEXT("The full path name is: %s\n"), buffer);
if (lppPart != NULL && *lppPart != 0)
{
_tprintf(TEXT("The final component in the path name is: %s\n"), *lppPart);
}
}
// Create a long directory name for use with the next two examples.
success = CreateDirectory(LONG_DIR_NAME,
NULL);
if (!success)
{
// Handle an error condition.
printf ("CreateDirectory failed (%d)\n", GetLastError());
return;
}
// Retrieve the short path name.
retval = GetShortPathName(LONG_DIR_NAME,
buf,
BUFSIZE);
if (retval == 0)
{
// Handle an error condition.
printf ("GetShortPathName failed (%d)\n", GetLastError());
return;
}
else _tprintf(TEXT("The short name for %s is %s\n"),
LONG_DIR_NAME, buf);
// Retrieve the long path name.
retval = GetLongPathName(buf,
buffer,
BUFSIZE);
if (retval == 0)
{
// Handle an error condition.
printf ("GetLongPathName failed (%d)\n", GetLastError());
return;
}
else _tprintf(TEXT("The long name for %s is %s\n"), buf, buffer);
// Clean up the directory.
success = RemoveDirectory(LONG_DIR_NAME);
if (!success)
{
// Handle an error condition.
printf ("RemoveDirectory failed (%d)\n", GetLastError());
return;
}
}
Nota
L'intestazione fileapi.h definisce GetFullPathName 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 XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | fileapi.h (include Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |