共用方式為

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中的 lpszFilePath 大小。 此值必須包含 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。

最後一個路徑是完整解析路徑時傳回的路徑。 例如，針對指向 「D：\yourdir」 之名為 「C：\tmp\mydir」 的符號鏈接，最後的路徑會是 「D：\yourdir」。。

使用 VOLUME_NAME_DOS時，此函式傳回的字串會使用 “\\？\” 語法。 如需詳細資訊，請參閱 CreateFile。

使用 VOLUME_NAME_GUID時，傳回的路徑會以格式為 “\\？\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\” 的磁碟區 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 標頭會根據 UNICODE 預處理器常數的定義，將 GetFinalPathNameByHandle 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的 慣例。

要求

要求 價值
最低支援的用戶端 Windows Vista [傳統型應用程式 |UWP 應用程式]
支援的最低伺服器 Windows Server 2008 [傳統型應用程式 |UWP 應用程式]
目標平臺 窗戶
標頭 fileapi.h （包括 Windows.h）
連結庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

檔案管理功能