CreateFile2 函式 （fileapi.h）
建立或開啟檔案或 I/O 裝置。 最常使用的 I/O 裝置如下：檔案、檔案數據流、目錄、實體磁碟、磁碟區、控制台緩衝區、磁帶機、通訊資源、mailslot 和管道。 函式會傳回句柄，根據檔案或裝置以及指定的旗標和屬性，可用來存取各種 I/O 類型的檔案或裝置。
從 Windows 市集應用程式呼叫時，CreateFile2 簡化。 您只能在 ApplicationData.LocalFolder或 package.InstalledLocation 目錄中開啟檔案或目錄。 您無法開啟命名管道或郵件集，或建立加密的檔案 （FILE_ATTRIBUTE_ENCRYPTED）。
語法
HANDLE CreateFile2(
[in] LPCWSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in] DWORD dwCreationDisposition,
[in, optional] LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
);
參數
[in] lpFileName
要建立或開啟的檔案或裝置名稱。
如需特殊裝置名稱的相關信息，請參閱 定義 MS-DOS 裝置名稱。
若要建立檔案數據流，請指定檔名、冒號，然後指定數據流的名稱。 如需詳細資訊，請參閱 檔案資料流。
[in] dwDesiredAccess
要求的檔案或裝置存取權，可摘要為讀取、寫入或兩者皆非零）。
最常使用的值是 GENERIC_READ、GENERIC_WRITE或兩者（GENERIC_READ | GENERIC_WRITE）。 如需詳細資訊，請參閱 一般訪問許可權、檔案安全性和訪問許可權、檔案訪問許可權常數和 ACCESS_MASK。
如果此參數為零，應用程式可以查詢某些元數據，例如檔案、目錄或裝置屬性，而不需要存取該檔案或裝置，即使 GENERIC_READ 存取也遭到拒絕。
您無法要求與已開啟句柄之開啟要求中 dwShareMode 參數所指定的共用模式衝突的存取模式。
如需詳細資訊，請參閱本主題的一節，並 建立和開啟檔案。
[in] dwShareMode
檔案或裝置的要求共用模式，可以是讀取、寫入、刪除、所有這些或無（請參閱下表）。 存取屬性或擴充屬性的要求不會受到這個旗標的影響。
如果此參數為零且 CreateFile2 成功，則檔案或裝置無法共用，而且在關閉檔案或裝置的句柄之前，無法再次開啟。 如需詳細資訊，請參閱一節。
您無法要求與現有要求中具有開啟句柄之存取模式衝突的共用模式。
若要讓進程在開啟檔案或裝置時共用檔案或裝置，請使用下列一或多個值的相容組合。 如需此參數與 dwDesiredAccess 參數之有效組合的詳細資訊，請參閱 建立和開啟檔案。
[in] dwCreationDisposition
針對存在或不存在的檔案或裝置採取動作。
對於檔案以外的裝置，此參數通常會設定為 OPEN_EXISTING。
如需詳細資訊，請參閱一節。
此參數必須是下列其中一個值，無法合併：
[in, optional] pCreateExParams
選擇性 CREATEFILE2_EXTENDED_PARAMETERS 結構的指標。
傳回值
如果函式成功，傳回值就是指定檔案、裝置、命名管道或郵件位置的開啟句柄。
如果函式失敗，傳回值會 INVALID_HANDLE_VALUE。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
言論
若要編譯使用 CreateFile2 函式的應用程式，請將 _WIN32_WINNT 宏定義為0x0602或更新版本。 如需詳細資訊，請參閱使用 Windows 標頭
CreateFile2 支援檔案互動，以及 Windows 開發人員可用的大多數其他類型的 I/O 裝置和機制。 本節會嘗試涵蓋開發人員在不同內容和不同 I/O 類型中使用 CreateFile2 時可能會遇到的各種問題。 只有在特別參考儲存在文件系統上實際檔案中的數據時，文字才會嘗試使用 檔案一詞。 不過，某些使用 檔案 可能會更普遍地參考支援類似檔案機制的 I/O 物件。 由於先前提及的歷史原因，這種自由使用 檔案 一詞在常數名稱和參數名稱中特別普遍。
當應用程式使用 createFile2 傳回的物件句柄完成時，請使用 CloseHandle 函式來關閉句柄。 這不僅釋放了系統資源，而且可以更廣泛地影響共用檔案或裝置，並將數據認可至磁碟等專案。 本主題中會適當地指出細節。
某些文件系統，例如 NTFS 檔案系統，支援個別檔案和目錄的壓縮或加密。 在具有此支援之掛接文件系統的磁碟區上，新的檔案會繼承其目錄的壓縮和加密屬性。
您無法使用 CreateFile2 來控制檔案或目錄上的壓縮、解壓縮或解密。 如需詳細資訊，請參閱 建立和開啟檔案、檔案壓縮和解壓縮，以及 檔案加密。
如果傳遞 pCreateExParams 參數中傳遞之 CREATEFILE2_EXTENDED_PARAMETERS 結構的 lpSecurityAttributes 成員是 NULL，則 CreateFile2 所傳回的句柄無法由應用程式建立的任何子進程繼承。 此成員的下列資訊也適用於：
- 如果 bInheritHandle 成員變數未 FALSE，這是任何非零值，則可以繼承句柄。 因此，如果您不想要繼承句柄，請務必正確初始化此結構成員，以 FALSE。
- 檔案或目錄的預設安全性描述元中的訪問控制清單 （ACL） 會繼承自其父目錄。
- 目標文件系統必須支援 lpSecurityDescriptor 成員對檔案和目錄的安全性，才能對其產生影響，這可以使用 GetVolumeInformation來決定。
| 科技 | 支援 |
|---|---|
| 伺服器消息塊 （SMB） 3.0 通訊協定 | 是的 |
| SMB 3.0 透明故障轉移 （TFO） | 不 |
| 具有向外延展檔案共用的SMB 3.0（SO） | 不 |
| 叢集共用磁碟區檔案系統 （CsvFS） | 是的 |
| 復原檔案系統 （ReFS） | 是的 |
符號連結行為
如果呼叫此函式會建立檔案，則行為不會有任何變更。 此外，請考慮下列-
如果指定 FILE_FLAG_OPEN_REPARSE_POINT：
- 如果已開啟現有的檔案，而且它是符號連結，傳回的句柄就是符號連結的句柄。
- 如果指定 TRUNCATE_EXISTING 或 FILE_FLAG_DELETE_ON_CLOSE，受影響的檔案就是符號連結。
-
如果未指定 FILE_FLAG_OPEN_REPARSE_POINT：
- 如果已開啟現有的檔案，而且它是符號連結，則傳回的句柄是目標的句柄。
- 如果指定 CREATE_ALWAYS、TRUNCATE_EXISTING或 FILE_FLAG_DELETE_ON_CLOSE，受影響的檔案就是目標。
檔案
如果您重新命名或刪除檔案，然後在不久之後加以還原，系統會搜尋快取以取得要還原的檔案資訊。 快取的資訊包含其簡短/長名稱組和建立時間。如果您在擱置刪除的檔案上呼叫 CreateFile2，因為先前呼叫 deleteFile，函式會失敗。 操作系統會延遲刪除檔案，直到檔案的所有句柄都關閉為止。 GetLastError 會傳回 ERROR_ACCESS_DENIED。
dwDesiredAccess 參數可以是零，可讓應用程式在沒有存取檔案的情況下查詢檔案屬性，如果應用程式執行時具有足夠的安全性設定。 這適用於測試檔案是否存在，而不需開啟檔案以進行讀取和/或寫入存取，或取得檔案或目錄的其他統計數據。 請參閱 取得和設定檔案資訊 和 GetFileInformationByHandle。
當應用程式跨網路建立檔案時，最好將 GENERIC_READ | GENERIC_WRITE 用於 dwDesiredAccess，而不是單獨使用 GENERIC_WRITE。 產生的程式代碼較快，因為重新導向器可以使用快取管理員，並傳送較少具有更多數據的SMB。
這種組合也避免了跨網路寫入檔案可能會偶爾傳回 ERROR_ACCESS_DENIED的問題。
如需詳細資訊，請參閱 建立和開啟檔案。
檔案數據流
在 NTFS 文件系統上，您可以使用 CreateFile2 在檔案中建立個別的數據流。 如需詳細資訊，請參閱 檔案資料流。目錄
應用程式無法使用 createFile2若要使用 CreateFile2開啟目錄，請將 FILE_FLAG_BACKUP_SEMANTICS 旗標指定為 dwFileFlagspCreateExParams 參數中所傳遞之 CREATEFILE2_EXTENDED_PARAMETERS 結構成員的一部分。 在不使用 SE_BACKUP_NAME 和 SE_RESTORE_NAME 許可權的情況下使用此旗標時，仍適用適當的安全性檢查。
使用 CreateFile2 在 FAT 或 FAT32 檔系統磁碟區重組期間開啟目錄時，請勿指定 MAXIMUM_ALLOWED 訪問許可權。 如果這樣做，就會拒絕存取目錄。 請改為指定 GENERIC_READ 存取權。
如需詳細資訊，請參閱 關於目錄管理。
實體磁碟和磁碟區
直接存取磁碟或磁碟區會受到限制。您可以使用 CreateFile2 函式來開啟實體磁碟驅動器或磁碟區，這會傳回直接存取存儲設備 （DASD） 句柄，可與 DeviceIoControl 函式搭配使用。 這可讓您直接存取磁碟或磁碟區，例如磁碟分區數據表之類的磁碟元數據。 不過，這種存取也會讓磁碟驅動器或磁碟區暴露出潛在的數據遺失，因為使用此機制對磁碟的寫入不正確，使得其內容無法存取操作系統。 為了確保數據完整性，請務必熟悉 deviceIoControl ，以及其他 API 與直接存取句柄的行為不同，而不是文件系統句柄。
必須符合下列需求，才能讓這類呼叫成功：
- 呼叫端必須具有系統管理許可權。 如需詳細資訊，請參閱 以特殊許可權執行。
- dwCreationDisposition 參數必須具有 OPEN_EXISTING 旗標。
- 開啟磁碟區或磁碟驅動器時，dwShareMode 參數必須具有 FILE_SHARE_WRITE 旗標。
| 字串 | 意義 |
|---|---|
| “\\.\PhysicalDrive0” | 開啟第一個實體磁碟驅動器。 |
| “\\.\PhysicalDrive2” | 開啟第三個實體磁碟驅動器。 |
若要取得磁碟區的實體磁碟驅動器標識碼，請開啟磁碟區的句柄，並使用 IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS呼叫 DeviceIoControl 函式。 此控制程式代碼會傳回每個磁碟區一或多個範圍的磁碟編號和位移;磁碟區可以跨越多個實體磁碟。
如需開啟實體磁碟驅動器的範例，請參閱 呼叫 DeviceIoControl。
開啟磁碟區或卸除式媒體磁碟驅動器時（例如磁碟驅動器或快快閃記憶體指紋磁碟驅動器），lpFileName 字串的格式應該是：“\\.\X：”。 請勿使用尾端反斜杠 （\），指出磁碟驅動器的根目錄。 下表顯示磁碟驅動器字串的一些範例。
| 字串 | 意義 |
|---|---|
| “\\.\A：” | 開啟磁碟驅動器 A。 |
| “\\.\C：” | 開啟 C： 磁碟區。 |
| “\\.\C：\” | 開啟 C： 磁碟區的檔案系統。 |
您也可以參考磁碟區名稱來開啟磁碟區。 如需詳細資訊，請參閱 為磁碟區命名。
磁碟區包含一或多個掛接的文件系統。 即使 createFile2
即使數據未快取，文件系統也可能不需要緩衝區對齊。 不過，如果在開啟磁碟區時指定了非快取選項，則不論磁碟區上的檔系統為何，都會強制執行緩衝區對齊。 建議您在所有文件系統上以非快取方式開啟磁碟區句柄，並遵循非快取的 I/O 限制。
變更器裝置
磁帶機
您可以使用下列格式的檔名來開啟磁帶機：「\.\TAPEx」。，其中 x 是數位，表示要開啟的磁碟驅動器，從磁帶機零開始。 若要在以 C 或 C++ 寫入的應用程式中開啟磁帶機零，請使用下列檔名：「\\\\\.\TAPE0」。。如需詳細資訊，請參閱 備份。
通訊資源
CreateFile2 函式可以建立通訊資源的句柄，例如序列埠 COM1。 針對通訊資源，dwCreationDisposition 參數必須 OPEN_EXISTING、dwShareMode 參數必須是零（獨佔存取），而且 hTemplateFile 參數必須 NULL。 您可以指定讀取、寫入或讀取/寫入存取權，而且可以針對重疊的 I/O 開啟句柄。若要指定大於 9 的 COM 埠號碼，請使用下列語法：“\.\COM10”。 此語法適用於允許指定 COM 埠號碼的所有埠號碼和硬體。
如需通訊的詳細資訊，請參閱 Communications。
主控台
CreateFile2 函式可以建立控制台輸入的句柄（CONIN$）。 如果進程因為繼承或重複而有開啟的句柄，它也可以建立使用中畫面緩衝區的句柄（CONOUT$）。 呼叫進程必須附加至繼承的控制台，或由allocConsole 函式| 參數 | 價值 |
|---|---|
| lpFileName |
使用 CONIN$ 值來指定主控台輸入。
使用 CONOUT$ 值來指定主控台輸出。 CONIN$ 會取得主控台輸入緩衝區的句柄，即使 SetStdHandle 函式會重新導向標準輸入句柄。 若要取得標準輸入句柄，請使用 GetStdHandle 函式。 CONOUT$ 會取得使用中畫面緩衝區的句柄，即使 SetStdHandle 重新導向標準輸出句柄也一樣。 若要取得標準輸出句柄，請使用 GetStdHandle。 |
| dwDesiredAccess |
GENERIC_READ | GENERIC_WRITE 是慣用的，但其中一個都可以限制存取。
|
| dwShareMode |
開啟 CONIN$時，請指定 FILE_SHARE_READ。 開啟 CONOUT$時，請指定 FILE_SHARE_WRITE。
如果呼叫行程繼承主控台，或子行程應該能夠存取主控台，此參數必須 |
| dwCreationDisposition | 使用 createFile2 開啟主控台時，您應該指定 OPEN_EXISTING。 |
設定傳入 pCreateExParams 參數 CREATEFILE2_EXTENDED_PARAMETERS 結構的成員，如下所示。
| 成員 | 價值 |
|---|---|
| lpSecurityAttributes | 如果您要繼承主控台，SECURITY_ATTRIBUTES 結構的 bInheritHandle 成員必須 TRUE。 |
|
dwFileAttributes
dwFileFlags dwSecurityQosFlags hTemplateFile |
忽視。 |
下表顯示 dwDesiredAccess 和 lpFileName的各種設定。
| lpFileName | dwDesiredAccess | 結果 |
|---|---|---|
| “CON” | GENERIC_READ | 開啟主控台以進行輸入。 |
| “CON” | GENERIC_WRITE | 開啟主控台以進行輸出。 |
| “CON” | GENERIC_READ | GENERIC_WRITE |
導致 createFile2 失敗;GetLastError 會傳回 ERROR_FILE_NOT_FOUND。 |
Mailslots
如果如需詳細資訊，請參閱 Mailslots。
管道
如果 CreateFile2 開啟命名管道的用戶端端，函式會使用處於接聽狀態之命名管道的任何實例。 開啟進程可以視需要多次複製句柄，但在開啟它之後，另一個用戶端就無法開啟命名管道實例。 開啟管道時所指定的存取必須與 createNamedPipe如果在這項作業之前未在伺服器上成功呼叫 CreateNamedPipe 函式，則管線將不會存在，而且 CreateFile2 會失敗，ERROR_FILE_NOT_FOUND。
如果至少有一個使用中管道實例，但伺服器上沒有可用的接聽程式管道，這表示所有管線實例目前都已連線，CreateFile2 會失敗並 ERROR_PIPE_BUSY。
如需詳細資訊，請參閱 Pipes。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows 8 [傳統型應用程式 |UWP 應用程式] |
| 支援的最低伺服器 | Windows Server 2012 [傳統型應用程式 |UWP 應用程式] |
| 目標平臺 | 窗戶 |
| 標頭 | fileapi.h （包括 Windows.h） |
| 連結庫 | Kernel32.lib |
| DLL | Kernel32.dll |
另請參閱
關於磁碟區管理 的
函式
概觀主題