SetFileAttributesW 函式（fileapi.h）

發行項
11/20/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 通訊協定	是的
SMB 3.0 透明故障轉移（TFO）	是的
具有向外延展檔案共用的SMB 3.0（SO）	是的
叢集共用磁碟區檔案系統（CsvFS）	是的
復原檔案系統（ReFS）	是的

例子

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

注意

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

要求

要求	價值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
支援的最低伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平臺	窗戶
標頭	fileapi.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll