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

Статья
11/20/2024

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

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

Синтаксис

DWORD GetFinalPathNameByHandleW(
  [in]  HANDLE hFile,
  [out] LPWSTR 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	Возвращает путь объекта устройства NT.

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

Если функция завершается успешно, возвращаемое значением строки, полученной 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".

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

При использовании VOLUME_NAME_GUIDвозвращенный путь начинается с пути GUID тома, форматированного как "\\?\Volume{xxxx-xxxxx-xxxx}\".

При использовании VOLUME_NAME_NTвозвращается путь для объекта устройства NT и начинается с имени устройства, например \Device\HarddiskVolume1\. Этот тип пути не может использоваться непосредственно программами Windows, так как он напоминает относительный путь.

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

В 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

См. также

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

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