Freigeben über


GetFullPathNameA-Funktion (fileapi.h)

Ruft den vollständigen Pfad und Dateinamen der angegebenen Datei ab.

Verwenden Sie die GetFullPathNameTransacted-Funktion , um diesen Vorgang als transaktionierten Vorgang auszuführen.

Weitere Informationen zu Datei- und Pfadnamen finden Sie unter Dateinamen, Pfade und Namespaces.

Hinweis Weitere Informationen zur Verwendung relativer Pfade mit der GetFullPathName-Funktion in Multithreadanwendungen oder freigegebenem Bibliothekscode finden Sie im Abschnitt Hinweise.

Syntax

DWORD GetFullPathNameA(
  [in]  LPCSTR lpFileName,
  [in]  DWORD  nBufferLength,
  [out] LPSTR  lpBuffer,
  [out] LPSTR  *lpFilePart
);

Parameter

[in] lpFileName

Der Name der Datei.

Bei diesem Parameter kann es sich um einen kurzen (8.3)-Dateinamen oder einen langen Dateinamen handeln. Diese Zeichenfolge kann auch ein Freigabe- oder Volumename sein.

[in] nBufferLength

Die Größe des Puffers, der die NULL-endende Zeichenfolge für das Laufwerk und den Pfad in TCHARs empfangen soll.

[out] lpBuffer

Ein Zeiger auf einen Puffer, der die NULL-endende Zeichenfolge für das Laufwerk und den Pfad empfängt.

[out] lpFilePart

Ein Zeiger auf einen Puffer, der die Adresse (innerhalb von lpBuffer) der endgültigen Dateinamenkomponente im Pfad empfängt.

Dieser Parameter kann NULL sein.

Wenn lpBuffer auf ein Verzeichnis und nicht auf eine Datei verweist, erhält lpFilePart null.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Länge der in lpBuffer kopierten Zeichenfolge in TCHARs, ohne das abschließende NULL-Zeichen.

Wenn der lpBuffer-Puffer zu klein ist, um den Pfad zu enthalten, entspricht der Rückgabewert in TCHARs der Größe des Puffers, der zum Speichern des Pfads und des abschließenden NULL-Zeichens erforderlich ist.

Wenn die Funktion aus einem anderen Grund fehlschlägt, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

GetFullPathName führt den Namen des aktuellen Laufwerks und Verzeichnisses mit einem angegebenen Dateinamen zusammen, um den vollständigen Pfad und Dateinamen einer angegebenen Datei zu ermitteln. Außerdem wird die Adresse des Dateinamenteils des vollständigen Pfads und des Dateinamens berechnet.

Diese Funktion überprüft nicht, ob der resultierende Pfad und Dateiname gültig sind oder ob eine vorhandene Datei auf dem zugeordneten Volume angezeigt wird.

Beachten Sie, dass der lpFilePart-Parameter keinen Zeichenfolgenpufferspeicherplatz benötigt, sondern nur ausreichend für eine einzelne Adresse. Dies liegt daran, dass einfach eine Adresse innerhalb des Puffers zurückgegeben wird, die bereits für lpBuffer vorhanden ist.

Freigabe- und Volumenamen sind gültige Eingaben für lpFileName. In der folgenden Liste werden beispielsweise der zurückgegebene Pfad und die Dateinamen angegeben, wenn test-2 ein Remotecomputer ist, und U: ein im Netzwerk zugeordnetes Laufwerk, dessen aktuelles Verzeichnis der Stamm des Volumes ist:

  • Wenn Sie "\\test-2\q$\lh" angeben, lautet der zurückgegebene Pfad "\\test-2\q$\lh"
  • Wenn Sie "\\?\UNC\test-2\q$\lh" angeben, lautet der zurückgegebene Pfad "\\?\UNC\test-2\q$\lh"
  • Wenn Sie "U:" angeben, ist der zurückgegebene Pfad das aktuelle Verzeichnis auf dem Laufwerk "U:\"
GetFullPathName konvertiert nicht den angegebenen Dateinamen lpFileName. Wenn der angegebene Dateiname vorhanden ist, können Sie GetLongPathName oder GetShortPathName verwenden, um in lange oder kurze Pfadnamen zu konvertieren.

Wenn der Rückgabewert größer oder gleich dem in nBufferLength angegebenen Wert ist, können Sie die Funktion erneut mit einem Puffer aufrufen, der groß genug ist, um den Pfad zu speichern. Ein Beispiel für diesen Fall neben der Verwendung eines Puffers der Länge Null für die dynamische Zuordnung finden Sie im Abschnitt Beispielcode.

Hinweis Obwohl der Rückgabewert in diesem Fall eine Länge ist, die das abschließende NULL-Zeichen enthält, enthält der Rückgabewert bei Erfolg nicht das abschließende NULL-Zeichen in der Anzahl.

Relative Pfade, die an die GetFullPathName-Funktion übergeben werden, werden relativ zum aktuellen Verzeichnis des Prozesses interpretiert. Der aktuelle Verzeichniszustand, der von der SetCurrentDirectory-Funktion geschrieben wird, ist global für den Prozess und kann jederzeit von jedem Thread geändert werden. Anwendungen sollten beachten, dass aufeinander folgende Aufrufe der GetFullPathName-Funktion mit einem relativen Pfad zu unterschiedlichen Ergebnissen führen können, wenn sich das aktuelle Verzeichnis zwischen den beiden Aufrufen ändert.

Um Probleme zu vermeiden, die durch inkonsistente Ergebnisse verursacht werden, sollten Multithreadanwendungen und freigegebener Bibliothekscode die Verwendung relativer Pfade vermeiden. Wenn ein relativer Pfad empfangen wird, sollte er genau einmal verwendet werden, entweder durch direkte Übergabe des relativen Pfads an eine Funktion wie CreateFile oder durch Konvertieren in einen absoluten Pfad und Verwenden des absoluten Pfads von diesem Punkt nach vorne.

Unter Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie Unterstützt
SMB 3.0-Protokoll (Server Message Block) Ja
SMB 3.0 Transparent Failover (TFO) Ja
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO) Ja
Dateisystem mit freigegebenen Clustervolumes (CsvFS) Ja
Robustes Dateisystem (Resilient File System, ReFS) Ja
 

Beispiele

Das folgende C++-Beispiel zeigt eine einfache Verwendung von GetFullPathName, GetLongPathName und GetShortPathName. Ein weiteres Beispiel für die verwendung der dynamischen Zuordnung finden Sie unter 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;
    }
}

Hinweis

Der Fileapi.h-Header definiert GetFullPathName als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile fileapi.h (Einschließen von Windows.h)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

Dateiverwaltungsfunktionen

GetFullPathNameTransacted

GetLongPathName

GetShortPathName

GetTempPath

SearchPath