GetLongPathNameA 函式（fileapi.h）

發行項
11/20/2024

將指定的路徑轉換成其長格式。

若要以交易作業的形式執行這項作業，請使用 GetLongPathNameTransacted 函式。

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

語法

DWORD GetLongPathNameA(
  [in]  LPCSTR lpszShortPath,
  [out] LPSTR  lpszLongPath,
  [in]  DWORD  cchBuffer
);

參數

[in] lpszShortPath

要轉換的路徑。

[out] lpszLongPath

要接收長路徑之緩衝區的指標。

您可以使用用於 lpszShortPath 參數的相同緩衝區。

[in] cchBuffer

緩衝區大小 lpszLongPath 指向，TCHAR。

傳回值

如果函式成功，傳回值會是複製到 lpszLongPath之字串的長度，TCHAR，不包含終止的 null 字元。

如果 lpBuffer 緩衝區太小而無法包含路徑，則傳回值會是大小，以 TCHAR為保留路徑和終止 Null 字元所需的緩衝區。

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

言論

在許多檔案系統上，簡短的檔名包含一個並排字元（~）字元。不過，並非所有文件系統都遵循此慣例。因此，如果路徑不包含tilde （~）字元，請勿假設您可以略過呼叫 getLongPathName 。

如果檔案或目錄存在但找不到長路徑，GetLongPathName 成功，將 lpszShortPath 參數所參考的字串複製到 lpszLongPath 參數所參考的緩衝區。

如果傳回值大於 cchBuffer中指定的值，您可以使用足以保存路徑的緩衝區再次呼叫函式。如需此案例的範例，請參閱 getFullPathName範例程式代碼一節。

Note 雖然此案例中的傳回值是包含終止 Null 字元的長度，但成功時的傳回值不包含計數中的終止 Null 字元。

可以存取檔案或目錄，但無法存取該檔案或目錄的某些父目錄。因此，當 GetLongPathName 無法查詢路徑元件的父目錄以判斷該元件的長名稱時，可能會失敗。對於擴展名超過 3 個字元的目錄元件，或長度總計超過 12 個字元的目錄元件，可以略過這項檢查。如需詳細資訊，請參閱命名檔案、路徑和命名空間的 Short 與 Long Names 一節。

在 Windows 8 和 Windows Server 2012 中，下列技術支援此功能。

科技	支援
伺服器消息塊（SMB） 3.0 通訊協定	是的
SMB 3.0 透明故障轉移（TFO）	是的
具有向外延展檔案共用的SMB 3.0（SO）	是的
叢集共用磁碟區檔案系統（CsvFS）	是的
復原檔案系統（ReFS）	是的

例子

如需使用 getLongPathName的範例，請參閱 getFullPathName範例程式代碼一節。

注意

fileapi.h 標頭會將 GetLongPathName 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
支援的最低伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平臺	窗戶
標頭	fileapi.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll