GetFullPathNameA 函式 (fileapi.h)
擷取指定檔案的完整路徑和檔名。
若要以交易作業的形式執行此作業，請使用 GetFullPathNameTransacted 函式 。
如需檔案和路徑名稱的詳細資訊，請參閱 檔名、路徑和命名空間。
語法
DWORD GetFullPathNameA(
[in] LPCSTR lpFileName,
[in] DWORD nBufferLength,
[out] LPSTR lpBuffer,
[out] LPSTR *lpFilePart
);
參數
[in] lpFileName
檔案的名稱。
此參數可以是簡短 (8.3 窗體) 或長檔名。 此字串也可以是共用或磁碟區名稱。
[in] nBufferLength
要接收 TCHAR 中磁碟驅動器和路徑之 Null 終止字串的緩衝區大小。
[out] lpBuffer
緩衝區的指標，接收磁碟驅動器和路徑的 Null 終止字串。
[out] lpFilePart
緩衝區的指標，在路徑中最後檔名元件的 lpBuffer) 內接收位址 (。
此參數可以是 Null。
如果 lpBuffer 參考目錄而非檔案， lpFilePart 會收到零。
傳回值
如果函式成功，傳回值會是複製到 lpBuffer 之字串的長度，不包括終止 Null 字元。
如果 lpBuffer 緩衝區太小而無法包含路徑，則傳回值會是保留路徑和終止 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 通訊協定 | Yes |
| SMB 3.0 透明故障轉移 (TFO) | Yes |
| 具有向外延展檔案共用的SMB 3.0 (SO) | Yes |
| 叢集共用磁碟區文件系統 (CsvFS) | Yes |
| 彈性檔案系統 (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 應用程式] |
| 目標平台 | Windows |
| 標頭 | fileapi.h (包含 Windows.h) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |