共用方式為


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 s 中的 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
傳回具有磁碟區裝置路徑的路徑。

傳回值

如果函式成功,則傳回值是 TCHARs 中 lpszFilePath 所收到的字串長度。 這個值不包含終止 Null 字元的大小。

Windows Server 2008 和 Windows Vista: 針對此函式的 ANSI 版本 GetFinalPathNameByHandleA,傳回值會包含終止 Null 字元的大小。

如果函式因為 lpszFilePath 太小而無法儲存字串加上終止 Null 字元,則傳回值是 TCHARs 中所需的緩衝區大小。 這個值包含終止 Null 字元的大小。

如果函式因任何其他原因而失敗,則傳回值為零。 若要取得擴充的錯誤資訊,請呼叫 GetLastError

傳回碼 Description
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」 的符號連結,最後一個路徑會是 「D:\yourdir」。。

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

在 Windows 8 和 Windows Server 2012 中,下列技術支援此函式。

技術 支援
伺服器消息塊 (SMB) 3.0 通訊協定 Yes
SMB 3.0 透明故障轉移 (TFO) Yes
具有向外延展檔案共用的SMB 3.0 (SO) Yes
叢集共用磁碟區文件系統 (CsvFS) Yes
彈性檔案系統 (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

另請參閱

檔案管理功能