getLongPathNameA 函式 (fileapi.h)

發行項
03/05/2024

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

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

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

語法

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

參數

[in] lpszShortPath

要轉換的路徑。

[out] lpszLongPath

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

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

[in] cchBuffer

緩衝區 lpszLongPath 的大小會指向 TCHAR 中的。

傳回值

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

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

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

備註

在許多文件系統上，簡短檔名包含一個波浪 (~) 字元。不過，並非所有文件系統都遵循此慣例。因此，如果路徑不包含磚 (~) 字元，請勿假設您可以略過呼叫 GetLongPathName 。

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

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

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

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

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

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

範例

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

注意

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

規格需求

需求	值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	fileapi.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll