Функция GetFullPathNameW (fileapi.h)
Извлекает полный путь и имя указанного файла.
Чтобы выполнить эту операцию как транзакцию, используйте функцию GetFullPathNameTransacted .
Дополнительные сведения об именах файлов и путей см. в разделе Имена файлов, пути и пространства имен.
Синтаксис
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:\" Диске
Если возвращаемое значение больше или равно значению, указанному в nBufferLength, можно снова вызвать функцию с буфером, достаточно большим для хранения пути. Пример этого случая, помимо использования буфера нулевой длины для динамического выделения, см. в разделе Пример кода.
Относительные пути, передаваемые в функцию 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 |