CREATEFILE2_EXTENDED_PARAMETERS 結構 （fileapi.h）
包含 CreateFile2的選擇性擴充參數。
語法
typedef struct _CREATEFILE2_EXTENDED_PARAMETERS {
DWORD dwSize;
DWORD dwFileAttributes;
DWORD dwFileFlags;
DWORD dwSecurityQosFlags;
LPSECURITY_ATTRIBUTES lpSecurityAttributes;
HANDLE hTemplateFile;
} CREATEFILE2_EXTENDED_PARAMETERS, *PCREATEFILE2_EXTENDED_PARAMETERS, *LPCREATEFILE2_EXTENDED_PARAMETERS;
成員
dwSize
包含這個結構的大小，sizeof(CREATEFILE2_EXTENDED_PARAMETERS)。
dwFileAttributes
檔案或裝置屬性和旗標，FILE_ATTRIBUTE_NORMAL 是檔案最常見的預設值。
此參數可以包含可用檔案屬性的任何組合（FILE_ATTRIBUTE_*）。 所有其他檔案屬性都會覆寫 FILE_ATTRIBUTE_NORMAL。
注意
CreateFile2 開啟現有的檔案時，通常會將檔案旗標與現有檔案的檔案屬性合併，並忽略 dwFlagsAndAttributes中提供的任何檔案屬性。 建立和開啟檔案中詳述特殊案例。
下列某些檔案屬性和旗標只能套用至檔案，而且不一定適用於所有其他類型的裝置，CreateFile2 可以開啟。 如需詳細資訊，請參閱
如需檔案屬性的進階存取，請參閱 SetFileAttributes。 如需具有其值和描述之所有檔案屬性的完整清單，請參閱 File Attribute Constants。
| 屬性 | 意義 |
|---|---|
|
檔案應該封存。 應用程式會使用此屬性來標記檔案以進行備份或移除。 |
|
檔案或目錄已加密。 對於檔案，這表示檔案中的所有數據都會加密。 對於目錄，這表示加密是新建立檔案和子目錄的預設值。 如需詳細資訊，請參閱 檔案加密。
如果同時指定 FILE_ATTRIBUTE_SYSTEM，這個旗標就不會有任何作用。 家用版、家用版、入門版或ARM版本的Windows不支援此旗標。 從 Windows 市集應用程式呼叫時，不支援此旗標。 |
|
檔案已隱藏。 請勿將其包含在一般目錄清單中。 |
|
以完整性設定的檔案或目錄。 對於檔案，檔案中的所有數據流都有完整性。 如果是目錄，除非呼叫端另有指定，否則新建立的檔案和子目錄的完整性是預設值。
只有在 ReFS 檔案系統上才支援此旗標。 |
|
檔案沒有設定其他屬性。 此屬性只有在單獨使用時才有效。 |
|
檔案的數據無法立即取得。 這個屬性表示檔案數據會實際移至離線記憶體。 遠端記憶體是階層式記憶體管理軟體，使用這個屬性。 應用程式不應該任意變更此屬性。 |
|
檔案是唯讀的。 應用程式可以讀取檔案，但無法寫入或刪除檔案。 |
|
檔案是作系統獨佔或獨佔使用的一部分。 |
|
檔案正用於暫存記憶體。
如需詳細資訊，請參閱本主題的 快取行為 一節。 |
dwFileFlags
此參數可以包含旗標的組合（FILE_FLAG_*），以控制檔案或裝置快取行為、存取模式和其他特殊用途旗標。
| 旗 | 意義 |
|---|---|
|
檔案正在開啟或建立以進行備份或還原作業。 當進程具有 SE_BACKUP_NAME 和 SE_RESTORE_NAME 許可權時，系統可確保呼叫進程會覆寫檔案安全性檢查。 如需詳細資訊，請參閱在令牌 中變更許可權。
您必須設定此旗標，才能取得目錄的句柄。 目錄句柄可以傳遞至某些函式，而不是檔案句柄。 如需詳細資訊，請參閱一節。 |
|
檔案會在關閉所有句柄之後立即刪除，其中包括指定的句柄，以及任何其他開啟或重複的句柄。
如果檔案有現有的開啟句柄，除非呼叫全都以 FILE_SHARE_DELETE 共用模式開啟，否則呼叫會失敗。 除非指定 FILE_SHARE_DELETE 共用模式，否則檔案的後續開啟要求會失敗。 |
|
裝置對應是系統中 DOS 裝置名稱和裝置之間的對應，並在解析 DOS 名稱時使用。 系統中每個使用者都有個別的裝置對應，使用者可以管理自己的裝置對應。 在模擬期間，通常會使用模擬用戶的裝置對應。 不過，設定此旗標時，會改用進程使用者的裝置對應。 |
|
檔案或裝置正在開啟，且沒有數據讀取和寫入的系統快取。 此旗標不會影響硬碟快取或記憶體對應檔案。
使用 FILE_FLAG_NO_BUFFERING 旗標成功使用 CreateFile2 開啟的檔案有嚴格的需求，如需詳細資訊，請參閱 檔案緩衝處理。 |
|
要求檔案數據，但應該會繼續位於遠端記憶體中。 它不應該傳輸回本機記憶體。 此旗標可供遠端儲存系統使用。 |
|
一般 重新分析點 處理不會發生;CreateFile2 會嘗試開啟重新分析點。 開啟檔案時，會傳回檔句柄，不論控制重新分析點的篩選是否正常運作。
此旗標不能與 CREATE_ALWAYS 旗標搭配使用。 如果檔案不是重新分析點，則會忽略此旗標。 如需詳細資訊，請參閱一節。 |
|
檔案正在開啟，而檔案上的機會鎖定 （oplock） 會要求為單一不可部分完成的作業。 文件系統在執行建立作業之前會檢查 oplock，如果結果會中斷現有的 oplock，則建立將會失敗，且最後一個錯誤碼為 ERROR_CANNOT_BREAK_OPLOCK。
如果您使用這個旗標，且呼叫 CreateFile2 函式會成功傳回，您應該在新的檔案句 FSCTL_REQUEST_OPLOCK 柄上呼叫 DeviceIoControl，或使用 另一個機會鎖定作業來要求檔案上的 oplock。 如果您在要求 oplock 之前對檔案執行其他文件系統作業，可能會發生死結。 如果您呼叫採用檔案名稱而非句柄的檔系統 API，例如 GetFileAttributes，則特別有可能發生死結。 注意： 您可以在檔案句柄上安全地呼叫 CloseHandle 函式，而不需先要求 oplock。 |
|
檔案或裝置正在針對異步 I/O 開啟或建立。
在此句柄上完成後續的 I/O 作業時，重疊 結構中指定的事件將會設定為訊號狀態。 如果指定此旗標，則檔案可用於同時讀取和寫入作業。 如果未指定此旗標，則即使讀取和寫入函式的呼叫指定 了重疊 結構，I/O 作業也會串行化。 如需使用此旗標建立之檔句柄時考慮的資訊，請參閱本主題的 同步和異步 I/O 句柄 一節。 |
|
存取會根據 POSIX 規則進行。 這包括允許多個具有名稱的檔案，只有在支援該命名的文件系統時才有所不同。 使用此選項時請小心，因為針對 MS-DOS 或16位 Windows 所撰寫的應用程式可能無法存取以這個旗標建立的檔案。 |
|
存取權是隨機的。 系統可以使用此功能作為優化檔案快取的提示。
如果文件系統不支援快取的 I/O，且 FILE_FLAG_NO_BUFFERING，這個旗標就沒有作用。 如需詳細資訊，請參閱本主題的 快取行為 一節。 |
|
檔案或裝置正以會話感知開啟。 如果未指定此旗標，則會話 0 中執行的處理程式無法開啟個別會話裝置（例如使用 RemoteFX USB 重新導向的裝置）。 此旗標對不在會話 0 中的呼叫端沒有任何作用。 只有伺服器版本的 Windows 才支援此旗標。
Windows Server 2008 R2 和 Windows Server 2008： Windows Server 2012 之前不支援此旗標。 |
|
存取的目的是要從頭到尾循序。 系統可以使用此功能作為優化檔案快取的提示。
如果使用讀取後置（也就是回溯掃描），則不應該使用此旗標。 如果文件系統不支援快取的 I/O，且 FILE_FLAG_NO_BUFFERING，這個旗標就沒有作用。 如需詳細資訊，請參閱本主題的 快取行為 一節。 |
|
寫入作業不會經歷任何中繼快取，它們會直接移至磁碟。
如需詳細資訊，請參閱本主題的 快取行為 一節。 |
dwSecurityQosFlags
dwSecurityQosFlags 參數會指定 SQOS 資訊。 如需詳細資訊，請參閱 模擬層級。
lpSecurityAttributes
包含兩個不同但相關數據成員之 SECURITY_ATTRIBUTES 結構的指標：選擇性的安全性描述元，以及一個布爾值，決定傳回的句柄是否可以由子進程繼承。
此參數可以是 NULL 。
如果此參數 NULL，則應用程式可建立的任何子進程無法繼承 CreateFile2 所傳回 的句柄，且與傳回句柄相關聯的檔案或裝置會取得預設的安全性描述元。
lpSecurityDescriptor 結構的成員會指定檔案或裝置的 SECURITY_DESCRIPTOR。 如果這個成員 NULL，則與傳回句柄相關聯的檔案或裝置會指派預設的安全性描述元。
CreateFile2 會忽略開啟現有檔案或裝置時 lpSecurityDescriptor 成員，但會繼續使用 bInheritHandle 成員。
bInheritHandle 結構的成員會指定是否可以繼承傳回的句柄。
如需詳細資訊，請參閱 CreateFile2 主題的一節。
hTemplateFile
具有 GENERIC_READ 訪問許可權之範本檔案的有效句柄。 範本檔案會提供所建立檔案的檔案屬性和擴充屬性。
此參數可以是 NULL 。
開啟現有的檔案時，CreateFile2 會忽略此參數。
開啟新的加密檔案時，檔案會從其父目錄繼承任意訪問控制清單。 如需詳細資訊，請參閱 檔案加密。
言論
若要編譯使用 CREATEFILE2_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 句柄
CreateFile2 提供建立同步或異步的檔案或裝置句柄。 同步句柄的行為會讓使用該句柄的 I/O 函式呼叫遭到封鎖，直到它們完成為止，而異步檔句柄可讓系統立即從 I/O 函式呼叫傳回，無論它們是否完成 I/O 作業。 如先前所述，這個同步與異步行為是由在 dwFileFlags 中指定 FILE_FLAG_OVERLAPPED， 傳入 pCreateExParams 參數之 CREATEFILE2_EXTENDED_PARAMETERS 結構的成員來決定。 使用異步 I/O 時，有數個複雜度和潛在陷阱;如需詳細資訊，請參閱 同步和異步 I/O。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows 8 [傳統型應用程式 |UWP 應用程式] |
| 支援的最低伺服器 | Windows Server 2012 [傳統型應用程式 |UWP 應用程式] |
| 標頭 | fileapi.h （包括 Windows.h） |