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

另請參閱

檔案管理功能