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

Статья
11/20/2024

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

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

Синтаксис

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

Параметры

[in] hFile

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

[out] lpszFilePath

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

[in] cchFilePath

Размер lpszFilePathв TCHAR. Это значение должно содержать символ завершения 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, в TCHAR. Это значение не включает размер завершающего символа NULL.

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

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

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

Возвращаемый код	Описание
ERROR_PATH_NOT_FOUND	Можно вернуть, если вы ищете букву диска, и она не существует. Например, дескриптор был открыт на диске, который в настоящее время не подключен, или если вы создаете том и не назначаете его букву диска. Если в томе нет буквы диска, для его идентификации можно использовать GUID 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 (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]
целевая платформа	Виндоус
заголовка	fileapi.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll

См. также

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

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