Бөлісу құралы:

Функция 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в 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.

Заметка

Windows 10 версии 1709 и более поздних версий и Windows Server версии 1709 и более поздних версий поддерживают класс сведений FileNormalizedNameInformation через SMB. Дополнительные сведения см. в спецификации [MS-SMB2] (/openpecs/windows_protocols/ms-smb2/a64e55aa-1152-48e4-8206-edd9644e7f7#Appendix_A_414) Приложение A, раздел 3.3.5.20.1.

Окончательный путь — это путь, возвращаемый при полном разрешении пути. Например, для символьной ссылки "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

См. также

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

  • Last updated on