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

  • Статья

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

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

Синтаксис

DWORD GetFinalPathNameByHandleA(
  [in]  HANDLE hFile,
  [out] LPSTR  lpszFilePath,
  [in]  DWORD  cchFilePath,
  [in]  DWORD  dwFlags
);

Параметры

[in] hFile

Дескриптор файла или каталога.

[out] lpszFilePath

Указатель на буфер, который получает путь к hFile.

[in] cchFilePath

Размер lpszFilePath в TCHARs. Это значение должно содержать символ завершения NULL .

[in] dwFlags

Тип возвращаемого результата. Этот параметр может принимать одно из указанных ниже значений.

Значение Значение
FILE_NAME_NORMALIZED
0x0
 Возвращает имя нормализованного диска. Это значение по умолчанию.
FILE_NAME_OPENED
0x8
 Возвращает имя открытого файла (не нормализованное).
 

Этот параметр также может включать одно из следующих значений.

Значение Значение
VOLUME_NAME_DOS
0x0
 Возвращает путь с буквой диска. Это значение по умолчанию.
VOLUME_NAME_GUID
0x1
 Возвращает путь с guid пути тома вместо имени диска.
VOLUME_NAME_NONE
0x4
 Возвращает путь без сведений о диске.
VOLUME_NAME_NT
0x2
 Возвращает путь с путем к устройству тома.

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

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

Windows Server 2008 и Windows Vista: Для версии ANSI этой функции , GetFinalPathNameByHandleA, возвращаемое значение включает размер завершающего символа NULL.

Если функция завершается сбоем из-за того, что lpszFilePath слишком мал для хранения строки и завершающего символа NULL, возвращаемое значение является требуемым размером буфера в TCHAR. Это значение включает размер завершающего символа NULL.

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

Код возврата Описание
ERROR_PATH_NOT_FOUND
 Может быть возвращено, если вы ищете букву диска и ее не существует. Например, дескриптор был открыт на диске, который в настоящее время не подключен, или если создать том и не назначить ему букву диска. Если в томе нет буквы диска, можно использовать путь GUID тома для его идентификации.

Это возвращаемое значение также может быть возвращено при поиске пути GUID тома в сетевой папке. Пути GUID тома не создаются для общих сетевых ресурсов.
ERROR_NOT_ENOUGH_MEMORY
 Недостаточно памяти для завершения операции.
ERROR_INVALID_PARAMETER
 Для dwFlags указаны недопустимые флаги.

Комментарии

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

Последний путь — это путь, который возвращается при полном разрешении пути. Например, для символьной ссылки "C:\tmp\mydir", указывающей на "D:\yourdir", конечным путем будет "D:\yourdir".

Строка, возвращаемая этой функцией, использует синтаксис "\\?\". Дополнительные сведения см. в разделе CreateFile.

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

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

Примеры

В следующем примере показано использование функции GetFinalPathNameByHandle .

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

#define BUFSIZE MAX_PATH

void __cdecl _tmain(int argc, TCHAR *argv[])
{
    TCHAR Path[BUFSIZE];
    HANDLE hFile;
    DWORD dwRet;

    printf("\n");
    if( argc != 2 )
    {
        printf("ERROR:\tIncorrect number of arguments\n\n");
        printf("%s <file_name>\n", argv[0]);
        return;
    }

    hFile = CreateFile(argv[1],               // file to open
                       GENERIC_READ,          // open for reading
                       FILE_SHARE_READ,       // share for reading
                       NULL,                  // default security
                       OPEN_EXISTING,         // existing file only
                       FILE_ATTRIBUTE_NORMAL, // normal file
                       NULL);                 // no attr. template

    if( hFile == INVALID_HANDLE_VALUE)
    {
        printf("Could not open file (error %d\n)", GetLastError());
        return;
    }

    dwRet = GetFinalPathNameByHandle( hFile, Path, BUFSIZE, VOLUME_NAME_NT );
    if(dwRet < BUFSIZE)
    {
        _tprintf(TEXT("\nThe final path is: %s\n"), Path);
    }
    else printf("\nThe required buffer size is %d.\n", dwRet);

    CloseHandle(hFile);
}

Примечание

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

Требования

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

См. также

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