createDirectoryTransactedA 函式 (winbase.h)

發行項
03/03/2024

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

使用指定範本目錄的屬性，建立新的目錄做為交易作業。如果基礎文件系統支援檔案和目錄的安全性，函式會將指定的安全性描述元套用至新的目錄。新目錄會保留指定範本目錄的其他屬性。

語法

BOOL CreateDirectoryTransactedA(
  [in, optional] LPCSTR                lpTemplateDirectory,
  [in]           LPCSTR                lpNewDirectory,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           HANDLE                hTransaction
);

參數

[in, optional] lpTemplateDirectory

建立新目錄時，要當做範本使用的目錄路徑。此參數可以是 Null。

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

提示

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

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

[in] lpNewDirectory

要建立之目錄的路徑。

提示

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

[in, optional] lpSecurityAttributes

SECURITY_ATTRIBUTES 結構的指標。結構的 lpSecurityDescriptor 成員會指定新目錄的安全性描述元。

如果 lpSecurityAttributes 為 NULL，目錄會取得預設的安全性描述元。訪問控制會在目錄的預設安全性描述元中列出 (ACL) 繼承自其父目錄。

目標文件系統必須支援檔案和目錄的安全性，這個參數才能生效。當 GetVolumeInformation 傳回 FS_PERSISTENT_ACLS時，就會指出這點。

[in] hTransaction

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

傳回值

如果函式成功，則傳回非零的值。

如果函式失敗，傳回值會是零 (0) 。若要取得擴充的錯誤資訊，請呼叫 GetLastError。可能的錯誤包括下列各項。

傳回碼	Description
ERROR_ALREADY_EXISTS	指定的目錄已經存在。
ERROR_EFS_NOT_ALLOWED_IN_TRANSACTION	您無法使用已停用加密的父目錄來建立子目錄。
ERROR_PATH_NOT_FOUND	一或多個中繼目錄不存在。此函式只會在路徑中建立最終目錄。

備註

CreateDirectoryTransacted 函式可讓您建立從其他目錄繼承數據流信息的目錄。例如，當您使用 Macintosh 目錄時，此函式很有用，其具有適當識別目錄內容作為屬性所需的資源數據流。

某些文件系統，例如 NTFS 檔案系統，支援個別檔案和目錄的壓縮或加密。在針對這類文件系統格式化的磁碟區上，新目錄會繼承其父目錄的壓縮和加密屬性。

如果您嘗試建立已停用加密之父目錄的子目錄，此函式會失敗 並ERROR_EFS_NOT_ALLOWED_IN_TRANSACTION 。

您可以使用FILE_FLAG_BACKUP_SEMANTICS旗標集呼叫 CreateFileTransacted 函式，以取得目錄的句柄。

在 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 預處理器常數的定義，將 CreateDirectoryTransacted 定義為別名，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

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