Поделиться через


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

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

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

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

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

Синтаксис

DWORD GetFullPathNameW(
  [in]  LPCWSTR lpFileName,
  [in]  DWORD   nBufferLength,
  [out] LPWSTR  lpBuffer,
  [out] LPWSTR  *lpFilePart
);

Параметры

[in] lpFileName

Имя файла.

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

По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 символов в ширину, добавьте к пути "\\?\". Дополнительные сведения см. в статье Именование файлов, путей и пространств имен.

Совет

Начиная с Windows 10 версии 1607, вы можете согласиться на удаление ограничения MAX_PATH без добавления "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" статьи Именование файлов, путей и пространств имен .

[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

См. также

Функции управления файлами

GetFullPathNameTransacted

GetLongPathName

GetShortPathName

GetTempPath

SearchPath