Функция 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
Тип возвращаемого результата. Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
Возвращает нормализованное имя диска. Это значение по умолчанию. |
|
Возвращает имя открытого файла (не нормализованное). |
Этот параметр также может включать одно из следующих значений.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение — это длина строки, полученной lpszFilePath, в TCHARs. Это значение не включает размер завершающего символа NULL.
Windows Server 2008 и Windows Vista: Для версии ANSI этой функции GetFinalPathNameByHandleA возвращаемое значение включает размер завершающего символа NULL.
Если функция завершается ошибкой из-за того, что значение lpszFilePath слишком мало для хранения строки и завершающего символа NULL, возвращаемое значение является требуемым размером буфера в TCHARs. Это значение включает размер завершающего символа NULL.
Если функция завершается сбоем по какой-либо другой причине, возвращаемое значение равно нулю. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
| Код возврата | Описание |
|---|---|
|
Может быть возвращено, если вы ищете букву диска, а ее не существует. Например, дескриптор был открыт на диске, который в данный момент не подключен, или, если вы создаете том и не назначаете ему букву диска. Если у тома нет буквы диска, можно использовать путь GUID тома для его идентификации.
Это возвращаемое значение также может быть возвращено при поиске пути GUID тома в сетевой папке. Пути GUID тома не создаются для общих сетевых ресурсов. |
|
Недостаточно памяти для завершения операции. |
|
Для 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 |