CreateFileTransactedA 函式 (winbase.h)
[Microsoft 強烈建議開發人員利用替代方式來達成應用程式的需求。 許多針對 TxF 開發的案例，都可以透過更簡單且更容易使用的技巧來達成。 此外，未來版本的 Microsoft Windows 可能無法使用 TxF。 如需詳細資訊，以及 TxF 的替代方案，請參閱 使用交易式 NTFS 的替代方案。
建立或開啟檔案、檔案數據流或目錄做為交易作業。 函式會傳回可用來存取 物件的句柄。
若要以非傳輸的作業執行此作業，或存取檔案以外的物件 (，例如命名管道、實體裝置、mailslots) ，請使用 CreateFile 函式。
如需交易的詳細資訊，請參閱本主題的一節。
語法
HANDLE CreateFileTransactedA(
[in] LPCSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[in] DWORD dwCreationDisposition,
[in] DWORD dwFlagsAndAttributes,
[in, optional] HANDLE hTemplateFile,
[in] HANDLE hTransaction,
[in, optional] PUSHORT pusMiniVersion,
PVOID lpExtendedParameter
);
參數
[in] lpFileName
要建立或開啟之對象的名稱。
對象必須位於本機計算機上;否則，函式會失敗，而且最後一個錯誤碼會設定為 ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE。
根據預設，名稱限製為MAX_PATH個字元。 若要將此限制延伸至 32,767 寬字元，請在路徑前面加上 “\\？\”。 如需詳細資訊，請參閱命名檔案、路徑與命名空間。
提示
從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需在前面加上 “\\？\”。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間 的一節。
若要建立檔案數據流，請指定檔名、冒號，然後指定數據流的名稱。 如需詳細資訊，請參閱 檔案數據流。
[in] dwDesiredAccess
物件的存取權，可摘要為讀取、寫入，或兩者皆無法 (零) 。 最常使用的值是GENERIC_READ、GENERIC_WRITE，或 (GENERIC_READ GENERIC_WRITE | ) 。 如需詳細資訊，請參閱 一般訪問許可權 和 檔案安全性和訪問許可權。
如果此參數為零，應用程式可以查詢檔案、目錄或裝置屬性，而不需要存取該檔案或裝置。 如需詳細資訊，請參閱本主題的一節。
您無法要求存取模式，該模式與具有開啟句柄的開啟要求中指定的共用模式發生衝突。 如需詳細資訊，請參閱 建立和開啟檔案。
[in] dwShareMode
對象的共用模式，可以是讀取、寫入、兩者、刪除、全部或無 (請參閱下表) 。
如果此參數為零且 CreateFileTransacted 成功，則對象無法共用，而且在關閉句柄之前無法再次開啟。 如需詳細資訊，請參閱本主題的一節。
您無法要求與具有開啟句柄之開啟要求中指定的存取模式發生衝突的共用模式，因為這會導致下列共用違規： ERROR_SHARING_VIOLATION。 如需詳細資訊，請參閱 建立和開啟檔案。
若要讓進程在另一個進程開啟物件時共享物件，請使用下列一或多個值的組合來指定可以要求開啟物件的存取模式。
[in, optional] lpSecurityAttributes
包含選擇性安全性描述元之SECURITY_ATTRIBUTES結構的指標，也會判斷子進程是否可以繼承傳回的句柄。 參數可以是 NULL。
如果 lpSecurityAttributes 參數為 NULL，則應用程式可能會建立的任何子進程無法繼承 CreateFileTransacted 所傳回的句柄，而且與傳回的句柄相關聯的物件會取得預設的安全性描述元。
結構的 bInheritHandle 成員會指定是否可以繼承傳回的句柄。
結構的 lpSecurityDescriptor 成員會指定對象 的安全性描述元 ，但也可能是 NULL。
如果 lpSecurityDescriptor 成員為 NULL，則會將與傳回句柄相關聯的物件指派為預設安全性描述元。
CreateFileTransacted 會在開啟現有檔案時忽略 lpSecurityDescriptor 成員，但會繼續使用 bInheritHandle 成員。
如需詳細資訊，請參閱本主題的一節。
[in] dwCreationDisposition
對存在且不存在的檔案採取動作。
如需詳細資訊，請參閱本主題的一節。
此參數必須是下列其中一個值，無法合併。
[in] dwFlagsAndAttributes
檔案屬性和旗標， FILE_ATTRIBUTE_NORMAL 為最常見的預設值。
此參數可以包含可用檔案屬性的任何組合， (FILE_ATTRIBUTE_*) 。 所有其他檔案屬性都會覆寫 FILE_ATTRIBUTE_NORMAL。
此參數也可以包含旗標的組合 (FILE_FLAG_) ，以控制緩衝行為、存取模式和其他特殊用途旗標。 這些會與任何 FILE_ATTRIBUTE_ 值結合。
此參數也可以藉由指定 SECURITY_SQOS_PRESENT 旗標來包含安全性服務品質 (SQOS) 資訊。 下表顯示其他 SQOS 相關旗標資訊，如下表的屬性和旗標數據表。
當 CreateFileTransacted 開啟現有的檔案時，通常會將檔案旗標與現有檔案的檔案屬性結合，並忽略作為 dwFlagsAndAttributes 一部分提供的任何檔案屬性。 特殊案例詳述於 建立和開啟檔案中。
| 屬性 | 意義 |
|---|---|
|
檔案應封存。 應用程式會使用這個屬性來標記要備份或移除的檔案。 |
|
檔案或目錄已加密。 對檔案而言，這表示檔案中的所有資料都被加密。 對於目錄，這表示加密是新建立的檔案和子目錄的預設值。 如需詳細資訊，請參閱 檔案加密。
如果同時指定 FILE_ATTRIBUTE_SYSTEM， 此旗標就不會有任何作用。 |
|
檔案被隱藏起來。 請勿將其包含在一般目錄清單中。 |
|
檔案沒有設定其他屬性。 這個屬性只有在單獨使用時才有效。 |
|
檔案的數據無法立即使用。 這個屬性表示檔案數據實際上會移至離線記憶體。 遠端記憶體會使用這個屬性，這是階層式記憶體管理軟體。 應用程式不應該任意變更這個屬性。 |
|
檔案是唯讀的。 應用程式可以讀取檔案，但無法寫入或刪除檔案。 |
|
檔案是操作系統的一部分或獨佔使用。 |
|
檔案正用於暫存記憶體。 檔案系統可避免在有足夠的快取記憶體可用時將數據寫回大量記憶體，因為應用程式會在關閉句柄之後刪除暫存盤。 在此情況下，系統可以完全避免寫入數據。 否則，會在關閉句柄之後寫入數據。 |
| 旗標 | 意義 |
|---|---|
|
正在開啟或建立備份或還原作業的檔案。 當進程具有 SE_BACKUP_NAME 和 SE_RESTORE_NAME 許可權時，系統可確保呼叫進程會覆寫檔案安全性檢查。 如需詳細資訊，請參閱 變更令牌中的許可權。
您必須設定此旗標，才能取得目錄的句柄。 目錄句柄可以傳遞至某些函式，而不是檔案句柄。 如需詳細資訊，請參閱 目錄句柄。 |
|
檔案會在檔案的最後一個交易寫入器句柄關閉之後立即刪除，前提是交易仍在使用中。 如果檔案標示為要刪除，且交易寫入器句柄在交易完成之後仍然開啟，則不會刪除檔案。
如果檔案有現有的開啟句柄，除非呼叫全都以 FILE_SHARE_DELETE共用 模式開啟，否則呼叫會失敗。 除非指定了 FILE_SHARE_DELETE 共用模式，否則檔案的後續開啟要求會失敗。 |
|
檔案正在開啟，且沒有系統快取。 此旗標不會影響硬碟快取或記憶體對應檔案。 與 FILE_FLAG_OVERLAPPED結合時，旗標會提供最大異步效能，因為 I/O 不依賴記憶體管理員的同步作業。
不過，某些 I/O 作業需要更多時間，因為數據不會保留在快取中。 此外，仍可能會快取檔案元數據。 若要將元數據排清到磁碟，請使用 FlushFileBuffers 函式。
使用 以 FILE_FLAG_NO_BUFFERING 開啟的檔案時，應用程式必須符合特定需求：
應用程式可以呼叫 GetDiskFreeSpace 函式來判斷磁碟區扇區大小。 |
|
要求檔案數據，但應該會繼續位於遠端記憶體中。 它不應該傳輸回本機記憶體。 此旗標可供遠端儲存系統使用。 |
|
不會進行一般 重新分析點 處理; CreateFileTransacted 會嘗試開啟重新分析點。 開啟檔案時，會傳回檔案句柄，不論控制重新分析點的篩選是否正常運作。 此旗標不能與 CREATE_ALWAYS 旗標搭配使用。 如果檔案不是重新分析點，則會忽略此旗標。 |
|
開啟或建立這個檔案是為了非同步 I/O。 當作業完成時， 重迭 結構中指定的事件會設定為訊號狀態。 需要大量時間來處理傳回 ERROR_IO_PENDING的作業。
如果指定此旗標，則檔案可用於同時讀取和寫入作業。 系統不會維護檔案指標，因此您必須將檔案位置傳遞至 重疊 結構中的讀取和寫入函式，或更新檔案指標。 如果未指定此旗標，則即使讀取和寫入函式的呼叫指定 重疊 結構，I/O 作業也會串行化。 |
|
系統會根據 POSIX 規則來存取檔案。 這包括針對支援該命名的文件系統，只允許具有名稱的多個檔案，而不同。 使用此選項時請小心，因為針對 MS-DOS 或 16 位 Windows 所撰寫的應用程式可能無法存取以這個旗標建立的檔案。 |
|
要隨機存取檔案。 系統可使用這個做為最佳化檔案快取的提示。 |
|
檔案或裝置正以會話感知開啟。 如果未指定此旗標，則每個會話裝置 (，例如使用 RemoteFX USB 重新導向) 的裝置，無法在會話 0 中執行的進程開啟。
此旗標對不在會話 0 中的呼叫端沒有作用。 只有伺服器版本的 Windows 才支援此旗標。
Windows Server 2008 R2 和 Windows Server 2008： Windows Server 2012 之前不支援此旗標。 |
|
檔案是從頭到尾循序存取。 系統可使用這個做為最佳化檔案快取的提示。 如果應用程式移動檔案指標以進行隨機存取，則可能不會發生最佳快取。 不過，仍保證正確的作業。
指定此旗標可提高使用循序存取讀取大型檔案之應用程式的效能。 對於大部分依序讀取大型檔案的應用程式，效能提升可能更明顯，但偶爾會略過少量的位元組範圍。 如果文件系統不支援快取的 I/O 和 FILE_FLAG_NO_BUFFERING，則此旗標沒有任何作用。 |
|
寫入作業不會通過任何中繼快取，它們會直接移至磁碟。
如果未同時指定 FILE_FLAG_NO_BUFFERING ，讓系統快取生效，則數據會寫入系統快取，但會排清到磁碟，而不會延遲。 如果也指定 了FILE_FLAG_NO_BUFFERING ，因此系統快取不會生效，則數據會立即排清到磁碟，而不會通過系統快取。 操作系統也會要求寫入硬碟快取至永續性媒體。 不過，並非所有硬體都支援此寫入功能。 |
dwFlagsAndAttributes 參數也可以指定安全性服務質量資訊。 如需詳細資訊，請參閱 模擬層級。 當呼叫的應用程式將 SECURITY_SQOS_PRESENT 旗標指定為 dwFlagsAndAttributes 的一部分時，它也可以包含下列一或多個值。
[in, optional] hTemplateFile
具有 GENERIC_READ 訪問許可權之範本檔案的有效句柄。 範本檔案會提供所建立檔案的檔案屬性和擴充屬性。 此參數可以是 Null。
開啟現有的檔案時， CreateFileTransacted 會忽略範本檔案。
開啟新的EFS 加密檔案時，檔案會從其父目錄繼承 DACL。
[in] hTransaction
交易的句柄。 CreateTransaction 函式會傳回這個句柄。
[in, optional] pusMiniVersion
要開啟的miniversion。 如果 hTransaction 中指定的交易不是修改檔案的交易，這個參數應該是 NULL。 否則，此參數可以是 FSCTL_TXFS_CREATE_MINIVERSION 控件程式代碼傳回的miniversion識別碼，或下列其中一個值。
lpExtendedParameter
此參數是保留的，而且必須是 NULL。
傳回值
如果函式成功，則傳回值是指定檔案、裝置、命名管道或郵件位置的開啟句柄。
如果函式失敗，傳回值 會INVALID_HANDLE_VALUE。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
備註
使用 CreateFileTransacted 傳回的句柄時，請使用檔案 I/O 函式的交易版本，而不是適當的標準檔案 I/O 函式。 如需詳細資訊，請參閱 交易式NTFS的程序設計考慮。
開啟交易句柄至目錄時，該句柄必須具有 FILE_WRITE_DATA (FILE_ADD_FILE) 和 (FILE_APPEND_DATAFILE_ADD_SUBDIRECTORY) 許可權 。 這些包含在 FILE_GENERIC_WRITE 許可權中。 如果您只是使用句柄來建立檔案或子目錄，則應該以較少的許可權開啟目錄;否則，可能會發生共享違規。
當該檔案是另一個交易 (的一部分時，您無法開啟具有 FILE_EXECUTE 存取層級的檔案，方法是呼叫 CreateFileTransacted) 來開啟它。 這表示如果指定存取層級FILE_EXECUTE或FILE_ALL_ACCESS，CreateFileTransacted 就會失敗
當非交易的應用程式呼叫 CreateFileTransacted，並針對 lpSecurityAttributes 指定MAXIMUM_ALLOWED時，每次都會以相同的存取層級開啟句柄。 當交易的應用程式呼叫 CreateFileTransacted 並指定給 lpSecurityAttributesMAXIMUM_ALLOWED時，根據交易是否鎖定檔案，會以不同的存取量開啟句柄。 例如，如果呼叫的應用程式具有 檔案的FILE_EXECUTE 存取層級，則只有在正在開啟的檔案不是由交易鎖定，或由交易鎖定，而且應用程式已經是該檔案的交易讀取器時，才會取得此存取權。
如需交易作業的完整描述，請參閱 交易NTFS 。
使用 CloseHandle 函式，在不再需要句柄時，以及認可或回復交易之前，關閉 CreateFileTransacted 傳回的物件句柄。
某些文件系統，例如 NTFS 檔案系統，支援個別檔案和目錄的壓縮或加密。 在針對該類型檔系統格式化的磁碟區上，新檔案會繼承其目錄的壓縮和加密屬性。
您無法使用 CreateFileTransacted 來控制檔案或目錄上的壓縮。 如需詳細資訊，請參閱 檔案壓縮和解壓縮和 檔案加密。
符號連結行為- 如果呼叫此函式會建立新的檔案，則行為不會有任何變更。
如果指定 FILE_FLAG_OPEN_REPARSE_POINT ：
- 如果開啟現有的檔案，而且它是符號連結，則傳回的句柄是符號連結的句柄。
- 如果指定 TRUNCATE_EXISTING 或 FILE_FLAG_DELETE_ON_CLOSE ，受影響的檔案會是符號連結。
- 如果開啟現有的檔案，而且它是符號連結，則傳回的句柄是目標的句柄。
- 如果指定 CREATE_ALWAYS、 TRUNCATE_EXISTING或 FILE_FLAG_DELETE_ON_CLOSE ，受影響的檔案就是目標。
如先前所述，如果 lpSecurityAttributes 參數為 NULL，則應用程式可能建立的任何子進程都無法繼承 CreateFileTransacted 所傳回的句柄。 此參數的下列資訊也適用於：
- 如果 bInheritHandle 不是 FALSE，這是任何非零值，則可以繼承句柄。 因此，如果您不想要繼承句柄，此結構成員必須正確地初始化為 FALSE 。
- 訪問控制清單 (ACL) 檔案或目錄的預設安全性描述項繼承自其父目錄。
- 目標文件系統必須支援檔案和目錄的安全性，lpSecurityDescriptor 才能對它們產生影響，這可以使用 GetVolumeInformation 來判斷
| 技術 | 支援 |
|---|---|
| 伺服器消息塊 (SMB) 3.0 通訊協定 | No |
| SMB 3.0 透明故障轉移 (TFO) | No |
| 具有向外延展檔案共用的SMB 3.0 (SO) | No |
| 叢集共用磁碟區文件系統 (CsvFS) | No |
| 彈性檔案系統 (ReFS) | No |
請注意，SMB 3.0 不支援 TxF。
檔
如果您嘗試在沒有磁碟片的磁碟驅動器或沒有CD的CD-ROM磁碟驅動器上建立檔案，系統會顯示一則訊息，讓使用者插入磁碟或CD。 若要防止系統顯示此訊息，請使用 SEM_FAILCRITICALERRORS呼叫 SetErrorMode 函式。如需詳細資訊，請參閱 建立和開啟檔案。
如果您重新命名或刪除檔案，然後稍後還原它，系統會在快取中搜尋要還原的檔案資訊。 快取的資訊包括其簡短/完整名稱組和建立時間。
如果您在先前呼叫DeleteFile時擱置刪除的檔案上呼叫 CreateFileTransacted，函式會失敗。 操作系統會延遲檔案刪除，直到關閉檔案的所有句柄為止。 GetLastError 會 傳回ERROR_ACCESS_DENIED。
dwDesiredAccess 參數可以是零，允許應用程式在應用程式執行時使用適當的安全性設定來查詢檔案屬性，而不需要存取檔案。 這很適合用來測試檔案是否存在，而不需開啟檔案以進行讀取和/或寫入存取，或取得檔案或目錄的其他統計數據。 請參閱 取得和設定檔案資訊和GetFileInformationByHandle。
當應用程式透過網路建立檔案時，最好使用GENERIC_READ GENERIC_WRITE | ，而不是單獨使用GENERIC_WRITE。 產生的程式代碼較快，因為重新導向器可以使用快取管理員，並傳送較少的SMB與更多數據。 這種組合也可避免在網路上寫入檔案時，偶爾會傳回 ERROR_ACCESS_DENIED的問題。
檔案數據流
在 NTFS 文件系統上，您可以使用 CreateFileTransacted 在檔案內建立個別的數據流。如需詳細資訊，請參閱 檔案數據流。
目錄
應用程式無法使用 CreateFileTransacted 建立目錄，因此此使用案例中，只有 OPEN_EXISTING 值對 dwCreationDisposition 有效。 若要建立目錄，應用程式必須呼叫 CreateDirectoryTransacted、CreateDirectory 或 CreateDirectoryEx。若要使用 CreateFileTransacted 開啟目錄，請將 FILE_FLAG_BACKUP_SEMANTICS 旗標指定為 dwFlagsAndAttributes 的一部分。 當使用此旗標而不 SE_BACKUP_NAME 和 SE_RESTORE_NAME 許可權時，仍適用適當的安全性檢查。
使用 CreateFileTransacted 在 FAT 或 FAT32 檔系統磁碟區的重組期間開啟目錄時，請勿指定 MAXIMUM_ALLOWED 訪問許可權。 如果這樣做，目錄的存取就會遭到拒絕。 請改為指定 GENERIC_READ 訪問許可權。
如需詳細資訊，請參閱 關於目錄管理。
注意
winbase.h 標頭會將 CreateFileTransacted 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows Vista [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | winbase.h (包含 Windows.h) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |
另請參閱
函式
概觀主題
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應