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

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

  • Статья

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

Чтобы выполнить эту операцию как транзакцию, используйте функцию 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 получает ноль.

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

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

Если буфер lpBuffer слишком мал, чтобы содержать путь, возвращаемое значение — это размер TCHARs, буфера, который требуется для хранения пути и конца null-символа.

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

Замечания

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

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

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

Имена общих ресурсов и томов являются допустимыми входами для lpFileName. Например, следующий список удостоверяет возвращаемый путь и имена файлов, если тест-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, можно снова вызвать функцию с буфером, достаточно большим для хранения пути. Пример этого дела в дополнение к использованию буфера нулевой длины для динамического выделения см. в разделе "Пример кода".

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

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

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

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

Технологии Поддержанный
Протокол SMB 3.0 Да
Отработка отказа SMB 3.0 (TFO) Да
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]
целевая платформа Виндоус
заголовка fileapi.h (включая Windows.h)
библиотеки Kernel32.lib
DLL Kernel32.dll

См. также

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

GetFullPathNameTransacted

GetLongPathName

GetShortPathName

GetTempPath

SearchPath