GetLongPathNameTransactedW 函式（winbase.h）

發行項
11/20/2024

[Microsoft強烈建議開發人員利用替代方法來達成應用程式的需求。 TxF 開發的許多案例都可以透過更簡單且更容易使用的技術來達成。此外，未來版本的 Microsoft Windows 可能無法使用 TxF。如需詳細資訊和 TxF 的替代方案，請參閱使用交易式 NTFS的替代專案。

將指定的路徑轉換為其完整格式做為交易作業。

若要在沒有交易的情況下執行這項作業，請使用 GetLongPathName 函式。

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

語法

DWORD GetLongPathNameTransactedW(
  [in]  LPCWSTR lpszShortPath,
  [out] LPWSTR  lpszLongPath,
  [in]  DWORD   cchBuffer,
  [in]  HANDLE  hTransaction
);

參數

[in] lpszShortPath

要轉換的路徑。

路徑必須位於本機計算機上;否則，函式會失敗，且最後一個錯誤碼會設定為 ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE。

根據預設，名稱限製為MAX_PATH個字元。若要將此限制延伸至 32,767 寬字元，請在路徑前面加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間。

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需預先加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

[out] lpszLongPath

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

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

[in] cchBuffer

TCHAR中，緩衝區大小 lpszLongPath 指向。

[in] hTransaction

交易的句柄。此句柄是由 createTransaction 函式傳回。

傳回值

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

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

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

言論

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

如果找不到長路徑，此函式會傳回 lpszLongPath 參數中 lpszShortPath 參數中指定的名稱。

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

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

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

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

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

SMB 3.0 不支援 TxF。

注意

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

要求

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