共用方式為

GetFinalPathNameByHandleA 函式 （fileapi.h）

  • 發行項

擷取指定檔案的最終路徑。

如需檔案和路徑名稱的詳細資訊，請參閱 命名檔案。

語法

DWORD GetFinalPathNameByHandleA(
  [in]  HANDLE hFile,
  [out] LPSTR  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
 傳回具有磁碟區裝置路徑的路徑。

傳回值

如果函式成功，傳回值是 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」。。

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

在 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

另請參閱

檔案管理功能