共用方式為

CREATEFILE3_EXTENDED_PARAMETERS結構 （fileapi.h）

包含 CreateFile3 的選擇性擴充參數。

語法

typedef struct _CREATEFILE3_EXTENDED_PARAMETERS {
  DWORD                 dwSize;
  DWORD                 dwFileAttributes;
  DWORD                 dwFileFlags;
  DWORD                 dwSecurityQosFlags;
  LPSECURITY_ATTRIBUTES lpSecurityAttributes;
  HANDLE                hTemplateFile;
} CREATEFILE3_EXTENDED_PARAMETERS, *PCREATEFILE3_EXTENDED_PARAMETERS, *LPCREATEFILE3_EXTENDED_PARAMETERS;

Members

dwSize

包含此結構 sizeof(CREATEFILE3_EXTENDED_PARAMETERS)的大小 。

dwFileAttributes

檔案或裝置屬性和旗標， FILE_ATTRIBUTE_NORMAL 檔案最常見的預設值。

此參數可以包含可用檔案屬性 （FILE_ATTRIBUTE_*） 的任意組合。 所有其他檔案屬性都會覆寫 FILE_ATTRIBUTE_NORMAL。

備註

當 CreateFile3 開啟現有的檔案時，它通常會將檔案旗標與現有檔案的檔案屬性結合，並忽略作為 dwFlagsAndAttributes 一部分提供的任何檔案屬性。 特殊情況詳見 建立和開啟檔案。

下列部分檔案屬性和旗標可能只適用於檔案，而不一定適用於 CreateFile3 可以開啟的所有其他類型的裝置。 如需其他資訊，請參閱 CreateFile3 參考頁面的備註一節，以及建立和開啟檔案。

如需檔案屬性的更進階存取權，請參閱 SetFileAttributes。 如需所有檔案屬性及其值和描述的完整清單，請參閱 檔案屬性常數。

Attribute Meaning
FILE_ATTRIBUTE_ARCHIVE
32 (0x20)		 該文件應該被存檔。 應用程式會使用此屬性來標示要備份或移除的檔案。
FILE_ATTRIBUTE_ENCRYPTED
16384 (0x4000)		 檔案或目錄已加密。 對於檔案，這表示檔案中的所有資料都已加密。 對於目錄，這表示加密是新建立檔案和子目錄的預設值。 如需詳細資訊，請參閱 檔案加密。

如果也指定 FILE_ATTRIBUTE_SYSTEM 則此旗標無效。

Windows 的 Home、Home Premium、Starter 或 ARM 版本不支援此旗標。

從 Windows 市集應用程式呼叫時，不支援此旗標。
FILE_ATTRIBUTE_HIDDEN
2 (0x2)		 檔案已隱藏。 請勿將其包含在一般目錄清單中。
FILE_ATTRIBUTE_INTEGRITY_STREAM
32768 (0x8000)		 配置完整性的檔案或目錄。 對於檔案，檔案中的所有資料串流都具有完整性。 對於目錄，完整性是新建立檔案和子目錄的預設值，除非呼叫端另有指定。

此旗標僅在 ReFS 檔案系統上受支援。
FILE_ATTRIBUTE_NORMAL
128 (0x80)		 檔案未設定其他屬性。 此屬性只有在單獨使用時才有效。
FILE_ATTRIBUTE_OFFLINE
4096 (0x1000)		 檔案的資料無法立即使用。 此屬性指出檔案資料會實際移至離線儲存體。 此屬性由分層儲存管理軟體遠端儲存體使用。 應用程式不應該任意變更此屬性。
FILE_ATTRIBUTE_READONLY
1 (0x1)		 檔案是唯讀的。 應用程式可以讀取檔案，但無法寫入或刪除檔案。
FILE_ATTRIBUTE_SYSTEM
4 (0x4)		 該檔案是作業系統的一部分或僅由作業系統使用。
FILE_ATTRIBUTE_TEMPORARY
256 (0x100)		 檔案正用於暫存儲存。

如需詳細資訊，請參閱本主題的快 取行為 一節。

dwFileFlags

此參數可以包含旗標 （FILE_FLAG_*） 的組合，以控制檔案或裝置快取行為、存取模式及其他特殊用途旗標。

Flag Meaning
FILE_FLAG_DISALLOW_PATH_REDIRECTS
0x00010000		 防止路徑被重新分析點或符號連結重新導向。
FILE_FLAG_BACKUP_SEMANTICS
0x02000000		 正在開啟或建立檔案以進行備份或還原作業。 系統可確保呼叫處理程序在處理程序具有 SE_BACKUP_NAME 和 SE_RESTORE_NAME 專用權時置換檔案安全檢查。 如需詳細資訊，請參閱 變更權杖中的權限。

您必須設定此旗標，才能取得目錄的控制碼。 目錄控制碼可以傳遞至某些函式，而不是檔案控制碼。 如需詳細資訊，請參閱備 註 一節。
FILE_FLAG_DELETE_ON_CLOSE
0x04000000		 檔案會在關閉所有控制碼之後立即刪除，其中包括指定的控制碼和任何其他開啟或重複的控制碼。

如果檔案有現有的開啟控制碼，除非它們都以 FILE_SHARE_DELETE 共用模式開啟，否則呼叫會失敗。

檔案的後續開啟要求會失敗，除非指定 FILE_SHARE_DELETE 共用模式。
FILE_FLAG_IGNORE_IMPERSONATED_DEVICEMAP
0x00020000		 裝置對映是 DOS 裝置名稱與系統中裝置之間的對映，在解析 DOS 名稱時使用。 系統中的每個使用者都有單獨的裝置對應，使用者可以管理自己的裝置對應。 通常在模擬期間，會使用模擬使用者的裝置對應。 不過，設定此旗標時，會改用進程使用者的裝置對應。
FILE_FLAG_NO_BUFFERING
0x20000000		 正在開啟檔案或裝置，但沒有用於資料讀取和寫入的系統快取。 此旗標不會影響硬碟快取或記憶體對應檔案。

使用 FILE_FLAG_NO_BUFFERING 旗標成功處理以 CreateFile3 開啟的檔案有嚴格的需求，如需詳細資訊，請參閱 檔案緩衝。
FILE_FLAG_OPEN_NO_RECALL
0x00100000		 要求檔案資料，但應該繼續位於遠端儲存體中。 不應將其傳輸回本機儲存體。 此旗標供遠端儲存體系統使用。
FILE_FLAG_OPEN_REPARSE_POINT
0x00200000		 不會發生正常的 重新分析點 處理; CreateFile3 會嘗試開啟重新分析點。 開啟檔案時，會傳回檔案控制碼，無論控制重新分析點的篩選條件是否可運作。

此旗標不能與 CREATE_ALWAYS 旗標搭配使用。

如果檔案不是重新分析點，則會忽略此旗標。

如需詳細資訊，請參閱備 註 一節。
FILE_FLAG_OPEN_REQUIRING_OPLOCK
0x00040000		 正在開啟檔案，且會要求檔案上的機會鎖定 （oplock） 作為單一不可部分完成作業。 檔案系統會在執行建立作業之前檢查 oplock，如果結果是中斷現有的 oplock，則會以最後一個錯誤碼 ERROR_CANNOT_BREAK_OPLOCK 的建立失敗。

如果您使用此旗標，且呼叫 CreateFile3 函式成功傳回，您應該在檔案控制碼上執行的第一個作業是呼叫 DeviceIOControl 函式來要求 oplock，然後傳入 FSCTL_REQUEST_OPLOCK 或其他其中一個機會 鎖定作業。 如果您在要求 oplock 之前使用檔案控點執行其他檔案系統作業，則可能會發生死鎖。

便條： 您可以安全地呼叫檔案控制碼上的 CloseHandle 函式，而不需要先要求 oplock。
FILE_FLAG_OVERLAPPED
0x40000000		 正在開啟或建立檔案或裝置以進行非同步 I/O。

在此控制碼上完成後續的 I/O 作業時， OVERLAPPED 結構中指定的事件會設定為訊號狀態。

如果指定此旗標，則檔案可用於同時讀取和寫入作業。

如果未指定此旗標，則會序列化 I/O 作業，即使讀取和寫入函式的呼叫指定 OVERLAPPED 結構也一樣。

如需使用此旗標建立的檔案控制碼時的考量資訊，請參閱本主題的 同步和非同步 I/O 控制碼 一節。
FILE_FLAG_POSIX_SEMANTICS
0x01000000		 訪問將根據 POSIX 規則進行。 這包括允許多個具有名稱的檔案，僅大小寫不同，以支援該命名的檔案系統。 使用此選項時請小心，因為針對 MS-DOS 或 16 位 Windows 撰寫的應用程式可能無法存取使用此旗標建立的檔案。
FILE_FLAG_RANDOM_ACCESS
0x10000000		 訪問是隨機的。 系統可以將其作為優化檔案快取的提示。

如果檔案系統不支援快取的 I/O 和 FILE_FLAG_NO_BUFFERING，則此旗標無效。

如需詳細資訊，請參閱本主題的快 取行為 一節。
FILE_FLAG_SESSION_AWARE
0x00800000		 檔案或裝置正在以會話感知開啟。 如果未指定此旗標，則每個會話裝置 （例如使用 RemoteFX USB 重新導向的裝置） 無法由在會話 0 中執行的進程開啟。 此旗標對不在會話 0 中的呼叫端沒有影響。 此旗標僅在 Windows 的伺服器版本上受支援。
FILE_FLAG_SEQUENTIAL_SCAN
0x08000000		 存取旨在從頭到尾按順序進行。 系統可以將其作為優化檔案快取的提示。

如果要使用後讀 （亦即向後掃描） ，則不應使用此旗標。

如果檔案系統不支援快取的 I/O 和 FILE_FLAG_NO_BUFFERING，則此旗標無效。

如需詳細資訊，請參閱本主題的快 取行為 一節。
FILE_FLAG_WRITE_THROUGH
0x80000000		 寫入操作不會經過任何中間緩存，它們將直接進入磁碟。

如需其他資訊，請參閱本主題的快 取行為 一節。

dwSecurityQosFlags

dwSecurityQosFlags 參數會指定 SQOS 資訊。 如需詳細資訊，請參閱 模擬層級。

安全性旗標 Meaning
SECURITY_ANONYMOUS 在匿名模擬層級模擬用戶端。
SECURITY_CONTEXT_TRACKING 安全追蹤模式是動態的。 如果未指定此旗標，則安全性追蹤模式為靜態。
SECURITY_DELEGATION 在委派模擬層級模擬用戶端。
SECURITY_EFFECTIVE_ONLY 只有用戶端安全前後關聯的已啟用層面可供伺服器使用。 如果您未指定此旗標，則用戶端安全性內容的所有層面都可供使用。

這可讓用戶端限制伺服器在模擬用戶端時可以使用的群組和許可權。
SECURITY_IDENTIFICATION 在識別模擬層級模擬用戶端。
SECURITY_IMPERSONATION 在模擬層級模擬用戶端。 如果未指定其他旗標，這是預設行為。

lpSecurityAttributes

包含兩個個別但相關資料成員的 SECURITY_ATTRIBUTES 結構指標：選擇性安全性描述元，以及判斷子進程是否可以繼承傳回控制碼的布林值。

此參數可以是 NULL。

如果此參數是 NULL，則應用程式可能建立的任何子進程都無法繼承 CreateFile3 所傳回的控制碼，而且與傳回控制碼相關聯的檔案或裝置會取得預設安全性描述元。

結構的 lpSecurityDescriptor 成員會指定檔案或裝置的 SECURITY_DESCRIPTOR 。 如果此成員是 NULL，則會為與傳回控制碼相關聯的檔案或裝置指派預設安全性描述元。

CreateFile3 會在開啟現有的檔案或裝置時忽略 lpSecurityDescriptor 成員，但會繼續使用 bInheritHandle 成員。

結構的 bInheritHandle 成員會指定是否可以繼承傳回的控制碼。

如需詳細資訊，請參閱 CreateFile3 主題的備註一節。

hTemplateFile

具有 GENERIC_READ 存取權限之範本檔案的有效控制碼。 範本檔案會為正在建立的檔案提供檔案屬性及延伸屬性。

此參數可以是 NULL。

開啟現有檔案時， CreateFile3 會忽略此參數。

開啟新的加密檔案時，檔案會從其父目錄繼承任意存取控制清單。 如需其他資訊，請參閱 檔案加密。

備註

若要編譯使用 CREATEFILE3_EXTENDED_PARAMETERS 結構的應用程式，請將 _WIN32_WINNT 巨集定義為 0x0602 或更新版本。 如需詳細資訊，請參閱 使用 Windows 標頭。

快取行為

dwFileFlags 成員的數個可能值可用來控制或影響系統快取與句柄相關聯的數據的方式。 他們是：

  • FILE_FLAG_NO_BUFFERING
  • FILE_FLAG_RANDOM_ACCESS
  • FILE_FLAG_SEQUENTIAL_SCAN
  • FILE_FLAG_WRITE_THROUGH
  • FILE_ATTRIBUTE_TEMPORARY

如果未指定這些旗標，系統會使用預設的一般用途快取配置。 否則，系統快取會依每個旗標指定的行為。

其中一些旗標不應該合併。 例如，將 FILE_FLAG_RANDOM_ACCESS 與 FILE_FLAG_SEQUENTIAL_SCAN 結合起來會弄巧成拙。

指定 FILE_FLAG_SEQUENTIAL_SCAN 旗標可以提高使用循序存取讀取大型檔案的應用程式的效能。 對於大部分按順序讀取大型檔案但偶爾會跳過小範圍位元組的應用程式來說，效能提升可能更加明顯。 如果應用程式移動檔案指標以進行隨機存取，則很可能不會發生最佳快取效能。 但是，仍然可以保證正確操作。

旗標 FILE_FLAG_WRITE_THROUGH 和 FILE_FLAG_NO_BUFFERING 是獨立的，可以組合。

如果使用 FILE_FLAG_WRITE_THROUGH 但未指定 FILE_FLAG_NO_BUFFERING ，因此系統快取生效，則資料會寫入系統快取，但會立即排清至磁碟。

如果同時指定 FILE_FLAG_WRITE_THROUGH 和 FILE_FLAG_NO_BUFFERING ，因此系統快取不會生效，則資料會立即排清至磁碟，而不經過 Windows 系統快取。 作業系統也會要求將硬碟的本機硬體快取寫入至持續性媒體。

備註

並非所有硬碟硬體都支援此直寫功能。

正確使用 FILE_FLAG_NO_BUFFERING 旗標需要特殊的應用程式考量。 如需詳細資訊，請參閱 檔案緩衝。

透過 FILE_FLAG_WRITE_THROUGH 的直寫要求也會導致 NTFS 排清處理要求所產生的任何中繼資料變更，例如時間戳記更新或重新命名作業。 因此， FILE_FLAG_WRITE_THROUGH 旗標通常會與 FILE_FLAG_NO_BUFFERING 旗標搭配使用，以取代每次寫入之後呼叫 FlushFileBuffers 函式，這可能會導致不必要的效能損失。 同時使用這些旗幟可以避免這些處罰。 如需檔案和中繼資料快取的一般資訊，請參閱 檔案快取。

當 FILE_FLAG_NO_BUFFERING 與 FILE_FLAG_OVERLAPPED結合時，旗標會提供最大的非同步效能，因為 I/O 不依賴記憶體管理程式的同步作業。 不過，部分 I/O 作業需要更多時間，因為資料不會保留在快取中。 此外，檔案中繼資料可能仍會快取 （例如，建立空白檔案時）。 若要確保中繼資料排清至磁碟，請使用 FlushFileBuffers 函式。

指定 FILE_ATTRIBUTE_TEMPORARY 屬性會導致檔案系統避免在有足夠的快取記憶體可用時將資料寫回大量儲存體，因為應用程式會在關閉控點之後刪除暫存檔案。 在這種情況下，系統可以完全避免寫入資料。 雖然它不會以與先前提及的旗標相同的方式直接控制資料快取，但 FILE_ATTRIBUTE_TEMPORARY 屬性確實會告訴系統盡可能多地保留在系統快取中，而不寫入，因此某些應用程式可能會引起關注。

同步和非同步 I/O 控制碼

CreateFile3 提供建立同步或非同步的檔案或裝置控制碼。 同步控制碼的行為會讓使用該控制碼的 I/O 函式呼叫遭到封鎖，直到它們完成為止，而非同步檔案控制碼則可讓系統立即從 I/O 函式呼叫傳回，無論它們是否完成 I/O 作業。 如先前所述，此同步與非同步行為是由在 lpCreateExParams 參數中傳遞的 CREATEFILE3_EXTENDED_PARAMETERS 結構的 dwFileFlags 成員內指定 FILE_FLAG_OVERLAPPED 來決定。 使用非同步 I/O 時，有幾個複雜性和潛在的陷阱;如需詳細資訊，請參閱 同步和非同步 I/O。

需求

Requirement 價值觀
最低支援的用戶端 Windows 11 24H2 [桌面應用程式 |UWP 應用程式]
支援的最低伺服器 Windows Server 2025 [傳統型應用程式 |UWP 應用程式]
Header fileapi.h （包括 Windows.h）

另請參閱

建立檔案3

檔案管理結構

  • Last updated on