SetFileAttributesTransactedA 函式 (winbase.h)

發行項
03/03/2024

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

將檔案或目錄的屬性設定為交易作業。

語法

BOOL SetFileAttributesTransactedA(
  [in] LPCSTR lpFileName,
  [in] DWORD  dwFileAttributes,
  [in] HANDLE hTransaction
);

參數

[in] lpFileName

要設定其屬性的檔名。

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

提示

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

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

[in] dwFileAttributes

要為檔案設定的檔案屬性。

如需檔案屬性值及其描述的清單，請參閱檔案屬性常數。此參數可以是一或多個值，使用位 OR 運算子結合。不過，所有其他值都會覆寫 FILE_ATTRIBUTE_NORMAL。

此函式不支援所有屬性。如需詳細資訊，請參閱＜備註＞一節。

以下是支持的屬性值清單。

FILE_ATTRIBUTE_ARCHIVE (32 (0x20) )

FILE_ATTRIBUTE_HIDDEN (2 (0x2) )

FILE_ATTRIBUTE_NORMAL (128 (0x80) )

FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (8192 (0x2000) )

FILE_ATTRIBUTE_OFFLINE (4096 (0x1000) )

FILE_ATTRIBUTE_READONLY (1 (0x1) )

FILE_ATTRIBUTE_SYSTEM (4 (0x4) )

FILE_ATTRIBUTE_TEMPORARY (256 (0x100) )

[in] hTransaction

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

傳回值

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

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

下表說明如何設定無法使用 SetFileAttributesTransacted 設定的屬性。請注意，這些不是交易作業。

屬性	如何設定
FILE_ATTRIBUTE_COMPRESSED 0x800	若要設定檔案的壓縮狀態，請使用 DeviceIoControl 函式搭配 FSCTL_SET_COMPRESSION 作業。
FILE_ATTRIBUTE_DEVICE 0x40	保留;請勿使用。
FILE_ATTRIBUTE_DIRECTORY 0x10	檔案無法轉換成目錄。若要建立目錄，請使用 CreateDirectory 或 CreateDirectoryEx 函式。
FILE_ATTRIBUTE_ENCRYPTED 0x4000	若要建立加密的檔案，請使用 CreateFile 函式搭配 FILE_ATTRIBUTE_ENCRYPTED 屬性。若要將現有檔案轉換成加密檔案，請使用 EncryptFile 函式。
FILE_ATTRIBUTE_REPARSE_POINT 0x400	若要將重新分析點與檔案或目錄產生關聯，請使用 DeviceIoControl 函式搭配 FSCTL_SET_REPARSE_POINT 作業。
FILE_ATTRIBUTE_SPARSE_FILE 0x200	若要設定檔案的疏鬆屬性，請使用 DeviceIoControl 函式搭配 FSCTL_SET_SPARSE 作業。

如果檔案在交易中開啟以進行修改，則除非認可交易，否則沒有其他線程可以成功開啟檔案以進行修改。如果交易線程先開啟檔案，任何後續嘗試在認可交易之前開啟檔案以進行修改的線程都會收到共享違規。如果非交易線程會在交易線程執行之前開啟檔案以進行修改，而且交易線程嘗試開啟檔案時仍會開啟，交易將會收到 ERROR_TRANSACTIONAL_CONFLICT 錯誤。

如需交易的詳細資訊，請參閱交易式NTFS。

在 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。

交易作業

如果檔案已開啟以在交易中修改，則除非認可交易，否則沒有其他線程可以開啟檔案以進行修改。因此，如果交易線程先開啟檔案，則任何後續嘗試在認可交易之前修改檔案的線程會收到共享違規。如果非交易線程在交易線程之前修改檔案，而且當交易嘗試開啟檔案時，檔案仍會開啟，交易會收到錯誤 ERROR_TRANSACTIONAL_CONFLICT。

注意

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

規格需求

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