GetFullPathNameA 函式 （fileapi.h）
擷取指定檔案的完整路徑和檔名。
若要以交易作業的形式執行這項作業，請使用 GetFullPathNameTransacted 函式。
如需檔案和路徑名稱的詳細資訊，請參閱 檔名、路徑和命名空間。
語法
DWORD GetFullPathNameA(
[in] LPCSTR lpFileName,
[in] DWORD nBufferLength,
[out] LPSTR lpBuffer,
[out] LPSTR *lpFilePart
);
參數
[in] lpFileName
檔名。
此參數可以是簡短的 （8.3 窗體） 或長檔名。 此字串也可以是共用或磁碟區名稱。
[in] nBufferLength
要接收磁碟驅動器和路徑之 null 終止字串的緩衝區大小，TCHAR。
[out] lpBuffer
緩衝區的指標，接收磁碟驅動器和路徑的 Null 終止字串。
[out] lpFilePart
接收路徑中最終檔名元件之位址的緩衝區指標（在 lpBuffer內）。
此參數可以是 NULL
如果 lpBuffer 參照目錄而非檔案，lpFilePart 會收到零。
傳回值
如果函式成功，傳回值會是複製到 lpBuffer之字串的長度，TCHAR，不包含終止的 null 字元。
如果 lpBuffer 緩衝區太小而無法包含路徑，則傳回值會是大小，以 TCHAR為保留路徑和終止 Null 字元所需的緩衝區。
如果函式因任何其他原因而失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
言論
GetFullPathName 合併目前磁碟驅動器和目錄的名稱與指定的檔名，以判斷指定檔案的完整路徑和檔名。 它也會計算完整路徑和檔名之檔名部分的位址。
此函式不會驗證產生的路徑和檔名是否有效，或它們看到相關聯磁碟區上的現有檔案。
請注意，lpFilePart 參數不需要字元串緩衝區空間，但只足夠用於單一位址。 這是因為它只會在緩衝區內傳回已存在 lpBuffer的位址。
共用和磁碟區名稱是 lpFileName的有效輸入。 例如，如果 test-2 是遠端電腦且 U：是目前目錄為磁碟區根目錄的網路對應磁碟驅動器，下列清單會識別傳回的路徑和檔名：
- 如果您指定 “\\test-2\q$\lh” 傳回的路徑為 “\\test-2\q$\lh”
- 如果您指定 “\\？\UNC\test-2\q$\lh” 傳回的路徑是 “\\？\UNC\test-2\q$\lh”
- 如果您指定 “U：” 傳回的路徑是 “U：\” 磁碟驅動器上的目前目錄
如果傳回值大於或等於 nBufferLength 中所指定的值，您可以使用足以保存路徑的緩衝區再次呼叫 函式。 如需此案例的範例，除了使用零長度緩衝區進行動態配置之外，請參閱範例程式代碼一節。
傳遞至 GetFullPathName 函式的相對路徑會解譯為相對於進程的目前目錄。 SetCurrentDirectory 函式所撰寫的目前目錄狀態是進程的全域狀態，而且可以隨時由任何線程變更。 應用程式應該注意，如果目前目錄在兩個呼叫之間變更，GetFullPathName 函式的連續呼叫可能會產生不同的結果。
為了避免產生不一致的結果所造成的問題，多線程應用程式和共用連結庫程式碼應該避免使用相對路徑。 如果收到相對路徑，則應該只取用一次，方法是將相對路徑直接傳遞至 CreateFile之類的函式，或將它轉換成絕對路徑，並使用該點向前的絕對路徑。
在 Windows 8 和 Windows Server 2012 中，下列技術支援此功能。
| 科技 | 支援 |
|---|---|
| 伺服器消息塊 （SMB） 3.0 通訊協定 | 是的 |
| SMB 3.0 透明故障轉移 （TFO） | 是的 |
| 具有向外延展檔案共用的SMB 3.0（SO） | 是的 |
| 叢集共用磁碟區檔案系統 （CsvFS） | 是的 |
| 復原檔案系統 （ReFS） | 是的 |
例子
下列C++範例示範 GetFullPathName、GetLongPathName和 GetShortPathName的基本用法。 如需使用動態配置的另一個範例，請參閱 GetShortPathName。
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#define BUFSIZE 4096
#define LONG_DIR_NAME TEXT("c:\\longdirectoryname")
void _tmain(int argc, TCHAR *argv[])
{
DWORD retval=0;
BOOL success;
TCHAR buffer[BUFSIZE]=TEXT("");
TCHAR buf[BUFSIZE]=TEXT("");
TCHAR** lppPart={NULL};
if( argc != 2 )
{
_tprintf(TEXT("Usage: %s [file]\n"), argv[0]);
return;
}
// Retrieve the full path name for a file.
// The file does not need to exist.
retval = GetFullPathName(argv[1],
BUFSIZE,
buffer,
lppPart);
if (retval == 0)
{
// Handle an error condition.
printf ("GetFullPathName failed (%d)\n", GetLastError());
return;
}
else
{
_tprintf(TEXT("The full path name is: %s\n"), buffer);
if (lppPart != NULL && *lppPart != 0)
{
_tprintf(TEXT("The final component in the path name is: %s\n"), *lppPart);
}
}
// Create a long directory name for use with the next two examples.
success = CreateDirectory(LONG_DIR_NAME,
NULL);
if (!success)
{
// Handle an error condition.
printf ("CreateDirectory failed (%d)\n", GetLastError());
return;
}
// Retrieve the short path name.
retval = GetShortPathName(LONG_DIR_NAME,
buf,
BUFSIZE);
if (retval == 0)
{
// Handle an error condition.
printf ("GetShortPathName failed (%d)\n", GetLastError());
return;
}
else _tprintf(TEXT("The short name for %s is %s\n"),
LONG_DIR_NAME, buf);
// Retrieve the long path name.
retval = GetLongPathName(buf,
buffer,
BUFSIZE);
if (retval == 0)
{
// Handle an error condition.
printf ("GetLongPathName failed (%d)\n", GetLastError());
return;
}
else _tprintf(TEXT("The long name for %s is %s\n"), buf, buffer);
// Clean up the directory.
success = RemoveDirectory(LONG_DIR_NAME);
if (!success)
{
// Handle an error condition.
printf ("RemoveDirectory failed (%d)\n", GetLastError());
return;
}
}
注意
fileapi.h 標頭會將 GetFullPathName 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows XP [傳統型應用程式 |UWP 應用程式] |
| 支援的最低伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
| 目標平臺 | 窗戶 |
| 標頭 | fileapi.h （包括 Windows.h） |
| 連結庫 | Kernel32.lib |
| DLL | Kernel32.dll |