Condividi tramite


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.

Nota Vedere la sezione Osservazioni per informazioni sull'uso dei percorsi relativi con la funzione GetFullPathName nelle applicazioni multithreading o nel codice della libreria condivisa.

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:\"
GetFullPathName non converte il nome file specificato, lpFileName. Se il nome file specificato esiste, è possibile usare GetLongPathName o GetShortPathName per eseguire la conversione rispettivamente in nomi di percorso lunghi o brevi.

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.

Nota Anche se il valore restituito in questo caso è una lunghezza che include il carattere Null di terminazione, il valore restituito in caso di esito positivo non include il carattere null di terminazione nel conteggio.

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

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

Vedere anche

Funzioni di gestione file

GetFullPathNameTransacted

GetLongPathName

GetShortPathName

GetTempPath

Searchpath