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

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

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

Синтаксис

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, в TCHARs. Это значение не включает размер завершающего символа NULL.

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

Если функция завершается ошибкой из-за того, что значение lpszFilePath слишком мало для хранения строки и завершающего символа NULL, возвращаемое значение является требуемым размером буфера в TCHARs. Это значение включает размер завершающего символа 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".

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

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

При использовании 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 Да
Прозрачная отработка отказа (TFO) SMB 3.0 Да
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

См. также

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