SetFileAttributesW 函式 (fileapi.h)

發行項
02/26/2024

設定檔案或目錄的屬性。

若要以交易作業的形式執行此作業，請使用 SetFileAttributesTransacted 函式。

語法

BOOL SetFileAttributesW(
  [in] LPCWSTR lpFileName,
  [in] DWORD   dwFileAttributes
);

參數

[in] lpFileName

要設定其屬性的檔名。

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

提示

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

[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)	唯讀的檔案。應用程式可以讀取檔案，但無法寫入或刪除檔案。目錄上不接受這個屬性。如需詳細資訊，請參閱「您無法在 Windows Server 2003、Windows XP 或 Windows Vista 中檢視或變更資料夾的唯讀或系統屬性。
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	操作系統使用的一部分或獨佔使用的檔案或目錄。
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	用於暫存盤的檔案。如果有足夠的快取記憶體可用，檔案系統可避免將數據寫回大量記憶體，因為應用程式通常會在關閉句柄之後刪除臨時檔。在該案例中，系統完全可以避免寫入數據。否則，會在關閉句柄之後寫入數據。

傳回值

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

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

備註

下表描述如何設定無法使用 SetFileAttributes 設定的屬性。如需所有檔案屬性值及其描述的完整清單，請參閱檔案屬性常數。

屬性	如何設定
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。

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

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

範例

如需範例，請參閱擷取和變更檔案屬性。

注意

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

規格需求

需求	值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	fileapi.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll