GetFullPathNameTransactedA 函式 (winbase.h)

發行項
03/03/2024

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

擷取指定檔案的完整路徑和檔名做為交易作業。

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

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

語法

DWORD GetFullPathNameTransactedA(
  [in]  LPCSTR lpFileName,
  [in]  DWORD  nBufferLength,
  [out] LPSTR  lpBuffer,
  [out] LPSTR  *lpFilePart,
  [in]  HANDLE hTransaction
);

參數

[in] lpFileName

檔案的名稱。

此字串可以使用簡短 (8.3 格式) 或長檔名。此字串可以是共用或磁碟區名稱。

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

[in] nBufferLength

要接收 TCHAR 中磁碟驅動器和路徑之 Null 終止字串的緩衝區大小。

[out] lpBuffer

緩衝區的指標，接收磁碟驅動器和路徑的 Null 終止字串。

[out] lpFilePart

緩衝區的指標，該緩衝區會在路徑中最後檔名元件的 lpBuffer) 中接收位址 (。如果您不需要收到這項資訊，請指定 NULL 。

如果 lpBuffer 指向目錄而非檔案， lpFilePart 會收到 0 (零) 。

[in] hTransaction

交易的句柄。 CreateTransaction 函式會傳回這個句柄。

傳回值

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

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

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

備註

GetFullPathNameTransacted 會將目前磁碟驅動器和目錄的名稱與指定的檔名合併，以判斷指定檔案的完整路徑和檔名。它也會計算完整路徑和檔名之檔名部分的位址。此函式不會驗證產生的路徑和檔名是否有效，或看到相關聯磁碟區上的現有檔案。

共用和磁碟區名稱是 lpFileName 的有效輸入。例如，如果 test-2 是遠端電腦且 U：是網路對應磁碟驅動器，下列清單會識別傳回的路徑和檔名：

如果您指定 “\\test-2\q$\lh” 傳回的路徑為 “\\test-2\q$\lh”
如果您指定 “\\？\UNC\test-2\q$\lh” 傳回的路徑為 “\\？\UNC\test-2\q$\lh”
如果您指定 “U：” 傳回的路徑為 “U：\”

GetFullPathNameTransacted 不會轉換指定的檔名 lpFileName。如果指定的檔名存在，您可以使用 GetLongPathNameTransacted、 GetLongPathName 或 GetShortPathName 分別轉換成長或短路徑名稱。

如果傳回值大於 nBufferLength 中指定的值，您可以使用足以保存路徑的緩衝區再次呼叫函式。如需此案例的範例，以及針對動態配置使用零長度緩衝區，請參閱範例程式代碼一節。

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

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

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

SMB 3.0 不支援 TxF。

注意

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

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll