GetFinalPathNameByHandleW 函式 (fileapi.h)
擷取指定檔案的最終路徑。
如需檔案和路徑名稱的詳細資訊，請參閱 命名檔案。
語法
DWORD GetFinalPathNameByHandleW(
[in] HANDLE hFile,
[out] LPWSTR lpszFilePath,
[in] DWORD cchFilePath,
[in] DWORD dwFlags
);
參數
[in] hFile
檔案或目錄的控制碼。
[out] lpszFilePath
接收 hFile路徑之緩衝區的指標。
[in] cchFilePath
TCHAR s 中的 lpszFilePath大小。 此值必須包含 Null 終止字元。
[in] dwFlags
要傳回的結果型別。 此參數可以是下列其中一個值。
| 值 | 意義 |
|---|---|
|
傳回標準化磁片磁碟機名稱。 此為預設值。 |
|
傳回開啟的檔案名， (未正規化) 。 |
此參數也可以包含下列其中一個值。
| 值 | 意義 |
|---|---|
|
傳回具有磁碟機號的路徑。 此為預設值。 |
|
傳回具有磁片區 GUID 路徑的路徑，而不是磁片磁碟機名稱。 |
|
傳回沒有磁片磁碟機資訊的路徑。 |
|
傳回 NT 裝置物件路徑。 |
傳回值
如果函式成功，則傳回值是TCHARs 中lpszFilePath所收到的字串長度。 這個值不包含終止 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。
最後一個路徑是完整解析路徑時所傳回的路徑。 例如，對於指向 「D：\yourdir」 的符號連結，最後一個路徑會是 「D：\yourdir」。
使用 VOLUME_NAME_DOS時，此函式傳回的字串會使用 「\\？\」 語法。 如需詳細資訊，請參閱 CreateFile。
使用 VOLUME_NAME_GUID時，傳回的路徑會以格式為 「\\？\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxx-xxxxxxxxx}\」 的磁片區 GUID 路徑開頭。
使用 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 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
需求
| 最低支援的用戶端 | Windows Vista [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | fileapi.h (包含 Windows.h) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |