Функция GetFullPathNameA (fileapi.h)

Статья
02/28/2024

Извлекает полный путь и имя указанного файла.

Чтобы выполнить эту операцию как транзакцию, используйте функцию GetFullPathNameTransacted .

Дополнительные сведения об именах файлов и путей см. в разделе Имена файлов, пути и пространства имен.

Примечание Сведения об использовании относительных путей с функцией GetFullPathName в многопоточных приложениях или коде общей библиотеки см. в разделе Примечания.

Синтаксис

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

Параметры

[in] lpFileName

Имя файла.

Этот параметр может быть коротким (форма 8.3) или длинным именем файла. Эта строка также может быть общей папкой или именем тома.

[in] nBufferLength

Размер буфера для получения строки, заканчивающейся значением NULL, для диска и пути в TCHARs.

[out] lpBuffer

Указатель на буфер, получающий строку, завершающуюся значением NULL, для диска и пути.

[out] lpFilePart

Указатель на буфер, получающий адрес (в lpBuffer) конечного компонента имени файла в пути.

Этот параметр может принимать значение NULL.

Если lpBuffer ссылается на каталог, а не на файл, lpFilePart получает ноль.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение — это длина строки, скопированной в lpBuffer, в TCHARs, не включая завершающий символ NULL.

Если буфер lpBuffer слишком мал, чтобы содержать путь, возвращаемым значением в TCHAR является размер буфера, необходимого для хранения пути, и завершающего символа NULL.

Если функция завершается сбоем по какой-либо другой причине, возвращаемое значение равно нулю. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

GetFullPathName объединяет имя текущего диска и каталога с указанным именем файла, чтобы определить полный путь и имя файла к указанному файлу. Он также вычисляет адрес части имени файла полного пути и имени файла.

Эта функция не проверяет допустимость результирующего пути и имени файла или наличие существующего файла в связанном томе.

Обратите внимание, что для параметра lpFilePart не требуется пространство буфера строки, а достаточно только для одного адреса. Это связано с тем, что он просто возвращает адрес в буфере, который уже существует для lpBuffer.

Имена общих ресурсов и томов являются допустимыми входами для lpFileName. Например, следующий список удостоверений возвращает путь и имена файлов, если test-2 — удаленный компьютер, а U: — сетевой подключенный диск, текущий каталог которого является корнем тома:

Если указать "\\test-2\q$\lh", возвращается путь "\\test-2\q$\lh".
Если указать "\?\UNC\test-2\q$\lh", возвращается путь "\?\UNC\test-2\q$\lh".
Если указать "U:", возвращается путь к текущему каталогу на диске "U:\".

GetFullPathName не преобразует указанное имя файла lpFileName. Если указанное имя файла существует, можно использовать GetLongPathName или GetShortPathName для преобразования в длинные или короткие имена соответственно.

Если возвращаемое значение больше или равно значению, указанному в nBufferLength, можно снова вызвать функцию с буфером, достаточно большим для хранения пути. Пример этого случая, помимо использования буфера нулевой длины для динамического выделения, см. в разделе Пример кода.

Примечание Хотя возвращаемое значение в данном случае является длиной, которая включает завершающий символ NULL, возвращаемое значение при успешном выполнении не включает завершающий символ NULL в счетчике.

Относительные пути, передаваемые в функцию GetFullPathName , интерпретируются как относительные относительно текущего каталога процесса. Текущее состояние каталога, записанное функцией SetCurrentDirectory , является глобальным для процесса и может быть изменено любым потоком в любое время. Приложениям следует учитывать, что последовательные вызовы функции GetFullPathName с относительным путем могут привести к разным результатам, если текущий каталог изменяется между двумя вызовами.

Чтобы избежать проблем, вызванных несогласованными результатами, многопоточные приложения и код общей библиотеки должны избегать использования относительных путей. Если получен относительный путь, его следует использовать ровно один раз, либо передав относительный путь непосредственно в функцию , например CreateFile, либо преобразовав его в абсолютный путь и используя абсолютный путь от этой точки вперед.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
Прозрачная отработка отказа (TFO) SMB 3.0	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Восстанавливаемая файловая система (ReFS)	Да

Примеры

В следующем примере C++ показано базовое использование GetFullPathName, GetLongPathName и GetShortPathName. Еще один пример использования динамического выделения см. в разделе 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;
    }
}

Примечание

Заголовок fileapi.h определяет GetFullPathName в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll