IoCreateFileEx 函式 (ntddk.h)

IoCreateFileEx 例程會導致建立新的檔案或目錄，或開啟現有的檔案、裝置、目錄或磁碟區，併為呼叫者提供檔案物件的句柄。 檔系統篩選驅動程式 (舊版篩選驅動程式) 呼叫此例程。

語法

NTSTATUS IoCreateFileEx(
  [out]          PHANDLE                   FileHandle,
  [in]           ACCESS_MASK               DesiredAccess,
  [in]           POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]          PIO_STATUS_BLOCK          IoStatusBlock,
  [in, optional] PLARGE_INTEGER            AllocationSize,
  [in]           ULONG                     FileAttributes,
  [in]           ULONG                     ShareAccess,
  [in]           ULONG                     Disposition,
  [in]           ULONG                     CreateOptions,
  [in, optional] PVOID                     EaBuffer,
  [in]           ULONG                     EaLength,
  [in]           CREATE_FILE_TYPE          CreateFileType,
  [in, optional] PVOID                     InternalParameters,
  [in]           ULONG                     Options,
  [in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);

參數

[out] FileHandle

如果呼叫成功，則為接收檔句柄之變數的指標。 驅動程序必須在不再使用句柄時，立即關閉 ZwClose 的句柄。

[in] DesiredAccess

旗標的位掩碼 (請參閱 ACCESS_MASK) ，指定呼叫端對檔案或目錄所需的存取類型。 這組系統定義的 DesiredAccess 旗標會決定檔案物件的下列特定訪問許可權。

或者，對於任何不代表目錄的檔案物件，您可以指定下列一或多個泛型ACCESS_MASK旗標。 STANDARD_RIGHTS_XXX旗標是預先定義的系統值，可用來強制執行系統對象的安全性。 您也可以將這些泛型旗標與上表中的其他旗標結合。

對於 (FILE_DIRECTORY_FILE CreateOptions 旗標設定) 的目錄，您可以指定下列一或多個ACCESS_MASK旗標，也可以與先前所述的任何相容旗標合併。

FILE_READ_DATA、FILE_WRITE_DATA、FILE_EXECUTE和 FILE_APPEND_DATA DesiredAccess 旗標與建立或開啟目錄檔案不相容。

[in] ObjectAttributes

已由 InitializeObjectAttributes 例程初始化之OBJECT_ATTRIBUTES結構的指標。 如果呼叫端正在系統進程內容中執行，這個參數可以是 NULL。 否則，呼叫端必須在 呼叫 InitializeObjectAttributes 中設定OBJ_KERNEL_HANDLE屬性。 檔案物件之這個結構的成員包括下列專案。

[out] IoStatusBlock

IO_STATUS_BLOCK類型的變數指標，該變數會接收最終完成狀態和所要求作業的相關信息。 從 IoCreateFileEx 傳回時，變數 的信息成員包含 下列其中一個值：

• FILE_CREATED

• FILE_OPENED

• FILE_OVERWRITTEN

• FILE_SUPERSEDED

• FILE_EXISTS

• FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

選擇性地指定檔案的初始配置大小，以位元組為單位。 除非正在建立、覆寫或取代檔案，否則非零值沒有任何作用。

[in] FileAttributes

只有在檔案建立、取代或在某些情況下覆寫時，才會套用明確指定的屬性。 根據預設，這個值是FILE_ATTRIBUTE_NORMAL，可由任何其他旗標或透過位OR運算 () 相容旗標的組合覆寫。 可能的 FileAttributes 旗標包括下列專案。

[in] ShareAccess

指定呼叫端想要的檔案共享存取類型，做為零或一，或下列旗標的組合。 若要要求獨佔存取權，請將此參數設定為零。 如果在 Options 參數中指定IO_IGNORE_SHARE_ACCESS_CHECK旗標，I/O 管理員會忽略 ShareAccess 參數。 不過，檔案系統仍可能會執行存取檢查。 因此，即使您使用 IO_IGNORE_SHARE_ACCESS_CHECK 旗標，也請務必指定您想要的共用模式。 若要協助您避免共用違規錯誤，請指定下列所有共用存取旗標。

設備驅動器和中繼驅動程式通常會將 ShareAccess 設定為零，這可讓呼叫端獨佔存取開啟的檔案。

[in] Disposition

值，決定檔案已經存在時應該如何處理檔案。 處置 可以是下列其中一項。

[in] CreateOptions

指定要在建立或開啟檔案時套用的選項，做為下列旗標的兼容組合。

[in, optional] EaBuffer

類型 FILE_FULL_EA_INFORMATION 之呼叫端提供的變數指標，其中包含要套用至檔案之擴充屬性 (EA) 資訊。 對於裝置和中繼驅動程式，此參數必須是 NULL。

[in] EaLength

EaBuffer 的長度，以位元組為單位。 對於設備驅動器和中繼驅動程式，此參數必須為零。

[in] CreateFileType

驅動程式必須將此參數設定為 CreateFileTypeNone。

[in, optional] InternalParameters

驅動程式必須將此參數設定為 NULL。

[in] Options

指定要在建立要求產生期間使用的選項。 您可以使用下列零個或多個位旗標值。

[in, optional] DriverContext

IoInitializeDriverCreateContext 例程先前初始化之IO_DRIVER_CREATE_CONTEXT結構的選擇性指標。 IO_DRIVER_CREATE_CONTEXT 結構可用來將其他參數傳遞至 IoCreateFileEx 和 FltCreateFileEx2 例程。 如需詳細資訊，請參閱下列一節。

傳回值

IoCreateFileEx 會傳回STATUS_SUCCESS或適當的NTSTATUS值，例如下列其中一個。

如果 IoCreateFileEx 例程傳回錯誤狀態，呼叫端可藉由檢查 IoStatusBlock 參數來尋找失敗原因的其他資訊。

IoCreateFileEx 可能會傳回STATUS_FILE_LOCK_CONFLICT做為傳回值，或在IoStatusBlock參數所指向之IO_STATUS_BLOCK結構的 Status 成員中傳回。 只有在NTFS記錄檔已滿，而且 IoCreateFileEx 嘗試處理這種情況時，才會發生此錯誤。

備註

IoCreateFileEx 例程類似於 IoCreateFile 例程和 IoCreateFileSpecifyDeviceObjectHint 例程，但提供額外的功能，包括透過 IoCreateFileEx 例程的 DriverContext 參數存取額外的建立參數 (ECP) 、裝置物件提示和交易資訊。 如需這些結構型參數的詳細資訊，請參閱 IO_DRIVER_CREATE_CONTEXT。

文件系統篩選驅動程式會呼叫 IoCreateFileEx ，只將建立要求傳送至指定的裝置物件、其下方連結的篩選，以及文件系統。 附加在驅動程式堆疊中指定裝置物件上方的篩選條件不會收到建立要求。 不過，如果IO_DRIVER_CREATE_CONTEXT結構的 DeviceObjectHint 成員 (通過 DriverContext 參數) 為 NULL，則要求會移至堆疊頂端，而且會由所有篩選和文件系統接收。

如果 I/O 要求未移至驅動程式堆疊的頂端，也就是如果 DriverContext 參數不是 NULL ，且有效的裝置物件是由 IO_DRIVER_CREATE_CONTEXT 結構的 DeviceObjectHint 成員所指定，則適用下列限制：

• 如果傳遞至 IoCreateFileEx 例程的檔名路徑包含裝入點，裝入點必須解析為檔案或目錄所在的相同磁碟區。

IoCreateFileEx 取得的句柄可供後續呼叫用來操作檔案內的數據，或檔案物件的狀態或屬性。 從 IoCreateFileEx 取得的任何句柄最終都必須藉由呼叫 ZwClose 來釋放。

有兩種替代方式可指定要使用 IoCreateFileEx 建立或開啟的檔名：

• 做為完整路徑名稱，提供於輸入 ObjectAttributes 參數的 ObjectName 成員中。

• 作為路徑名稱，相對於輸入 ObjectAttributes 參數之 RootDirectory 成員中的句柄。 (此句柄可以代表目錄檔案。)

在系統進程以外的進程內容中執行的驅動程式例程，必須為IoCreateFileEx的 ObjectAttributes 參數設定 OBJ_KERNEL_HANDLE 屬性。 這會限制使用 IoCreateFileEx 所傳回的句柄，以核心模式執行的進程。 否則，進程可以在其中執行驅動程序的內容中存取句柄。 驅動程式可以呼叫 InitializeObjectAttributes 來設定OBJ_KERNEL_HANDLE屬性。

某些 DesiredAccess 旗標和旗標的組合具有下列效果：

• 若要讓呼叫端等候傳回的 FileHandle 設定為 Signaled 狀態，以同步處理 I/O 完成，必須設定 SYNCHRONIZE 旗標。 否則，屬於裝置或中繼驅動程式的呼叫端必須使用事件物件來同步處理 I/O 完成。

• 如果只設定FILE_APPEND_DATA和SYNCHRONIZE旗標，則呼叫端只能寫入檔案結尾，而且會忽略對檔案寫入的任何位移資訊。 不過，這類寫入作業會視需要自動擴充檔案。

• 設定檔案的FILE_WRITE_DATA旗標，也允許寫入超過檔案結尾的寫入。 此檔案也會針對這類寫入自動擴充。

• 如果只設定FILE_EXECUTE和 SYNCHRONIZE 旗標，呼叫端就無法使用傳回的 FileHandle 直接讀取或寫入檔案中的任何數據：也就是說，檔案上的所有作業都會透過系統呼叫器進行，以回應指令和資料存取。 裝置和中繼驅動程序不應該在 DesiredAccess 中設定FILE_EXECUTE旗標。

ShareAccess 參數會判斷個別線程是否可以同時存取相同的檔案。 前提是這兩個檔案開啟者具有以指定方式存取檔案的許可權，即可成功開啟和共用檔案。 如果 IoCreateFileEx 的原始呼叫端未指定FILE_SHARE_READ、FILE_SHARE_WRITE或FILE_SHARE_DELETE，則無法對檔案執行其他開啟作業：也就是說，原始呼叫端會獲得檔案的獨佔存取權。

若要成功開啟共用檔案，檔案所要求的 DesiredAccess 值必須與尚未與 ZwClose 一起發行之所有先前開啟要求的 DesiredAccess 和 ShareAccess 規格相容。 也就是說，指定給IoCreateFileEx的 DesiredAccess 值不得與不允許其他檔案開啟者存取的存取衝突。

如果在 Options 參數中指定IO_IGNORE_SHARE_ACCESS_CHECK，I/O 管理員會忽略 ShareAccess 參數。 不過，檔案系統仍可能會執行存取檢查。 因此，請務必指定 ShareAccess 參數想要的共用模式，即使使用 IO_IGNORE_SHARE_ACCESS_CHECK 旗標也一樣。

處置值FILE_SUPERSEDE要求呼叫端具有現有檔案物件的 DELETE 存取權。 如果是的話，在現有檔案上成功呼叫 IoCreateFileEx 並FILE_SUPERSEDE會有效地刪除該檔案，然後重新建立該檔案。 這表示，如果檔案已經由另一個線程開啟，線程會指定 shareAccess 參數並設定FILE_SHARE_DELETE旗標，以開啟檔案。 請注意，這種類型的處置與覆寫檔案的POSIX樣式一致。

處置值FILE_OVERWRITE_IF和FILE_SUPERSEDE類似。 如果使用現有的檔案和其中一個 Disposition 值呼叫 IoCreateFileEx，則會取代檔案。

覆寫檔案的語意相當於取代作業，但下列情況除外：

• 呼叫端必須具有檔案的寫入許可權，而不是刪除存取權。 這表示，如果檔案已經由另一個線程開啟，則會開啟檔案，並在輸入 ShareAccess中設定FILE_SHARE_WRITE旗標。

• 指定的檔案屬性在邏輯上為 ORed，且檔案上已有這些屬性。 這表示如果檔案已經由另一個線程開啟， IoCreateFileEx 的後續呼叫端就無法停用現有的 FileAttributes 旗標，但可以啟用相同檔案的其他旗標。 請注意，此覆寫檔案的樣式與 MS-DOS、Windows 3.1 和 OS/2 一致。

CreateOptions FILE_DIRECTORY_FILE 值會指定要建立或開啟的檔案是目錄檔案。 建立目錄檔案時，文件系統會在磁碟上建立適當的結構，以代表該特定文件系統的磁碟上結構的空白目錄。 如果指定此選項且要開啟的指定檔案不是目錄檔案，或者呼叫端指定了不一致的 CreateOptions 或 Disposition 值， 則 IoCreateFileEx 的呼叫將會失敗。

CreateOptions FILE_NO_INTERMEDIATE_BUFFERING 旗標可防止文件系統代表呼叫端執行任何中繼緩衝。 指定此值會對 Zw 的呼叫端參數設定特定限制 。檔案 例程，包括下列專案：

• 任何傳遞至 ZwReadFile 或 ZwWriteFile 的選擇性 ByteOffset 都必須是扇區大小的整數 (整數) 。

• 傳遞至 ZwReadFile 或 ZwWriteFile 的 Length 必須是扇區大小的整數。 請注意，如果傳輸期間到達檔尾，將讀取作業指定至緩衝區的長度完全是扇區大小，可能會導致傳送到該緩衝區的顯著位元組數目較少。

• 緩衝區必須符合基礎裝置的對齊需求。 呼叫 IoCreateFileEx 以取得代表實體裝置之檔案物件的句柄，然後使用該句柄呼叫 ZwQueryInformationFile 來取得此資訊。 如需系統FILE_XXX_ALIGNMENT值的清單，請參閱 DEVICE_OBJECT。

• 呼叫 ZwSetInformationFile 並將 FileInformationClass 參數設定為 FilePositionInformation 必須指定扇區大小的整數位移。

互斥 的 CreateOptions、FILE_SYNCHRONOUS_IO_ALERT和FILE_SYNCHRONOUS_IO_NONALERT旗標，只要透過傳回 的 FileHandle 所參考的檔案對象發生，就會指定檔案上的所有 I/O 作業都是同步的。 這類檔案上的所有 I/O 都會使用傳回的句柄，跨所有線程串行化。 使用上述任一 CreateOptions 值時，必須設定 DesiredAccess SYNCHRONIZE 旗標，讓 I/O 管理員將使用檔案對象作為同步處理物件。 設定上述任一 CreateOptions 值後，I/O 管理員會維護檔案物件的「檔案位置內容」，也就是內部、目前的檔案位置位移。 此位移可用於呼叫 ZwReadFile 和 ZwWriteFile。 也可以藉由呼叫 ZwQueryInformationFile 來查詢其位置，或藉由呼叫 ZwSetInformationFile 來設定。

如果未指定CreateOptions FILE_OPEN_REPARSE_POINT 旗標，且 IoCreateFileEx 會嘗試開啟具有重新分析點的檔案，則會發生檔案的一般重新分析點處理。 另一方面，如果指定FILE_OPEN_REPARSE_POINT旗標，則 不會 發生一般重新分析處理， 而且 IoCreateFileEx 會嘗試直接開啟重新分析點檔案。 不論是哪一種情況，如果開啟作業成功， IoCreateFileEx 會傳回STATUS_SUCCESS;否則，例程會傳回NTSTATUS錯誤碼。 IoCreateFileEx 永遠不會傳回STATUS_REPARSE。

CreateOptions FILE_OPEN_REQUIRING_OPLOCK 旗標可排除開啟檔案和要求 oplock 之間的時間，這可能會讓第三方開啟檔案並取得共享違規。 應用程式可以在 IoCreateFileEx 上使用 FILE_OPEN_REQUIRING_OPLOCK旗標，然後要求任何oplock。 這可確保 oplock 擁有者會收到任何後續開啟要求而造成共用違規的通知。

在 Windows 7 中，如果應用程式使用 FILE_OPEN_REQUIRING_OPLOCK 旗標時檔案上存在其他句柄，則建立作業將會失敗並STATUS_OPLOCK_NOT_GRANTED。 從 Windows 8 開始，此限制已不存在。

如果此建立作業會中斷檔案上已經存在的 oplock，則設定 FILE_OPEN_REQUIRING_OPLOCK 旗標會導致建立作業失敗並STATUS_CANNOT_BREAK_OPLOCK。 此建立作業不會中斷現有的 oplock。

使用此旗標的應用程式必須在此呼叫成功之後要求 oplock，或所有稍後嘗試開啟檔案的嘗試都會遭到封鎖，而不需要一般 oplock 處理的好處。 同樣地，如果此呼叫成功，但稍後的 oplock 要求失敗，則使用此旗標的應用程式必須在偵測到 oplock 要求失敗之後關閉其句柄。

windows 7、Windows Server 2008 R2 及更新版本的 Windows 操作系統中提供FILE_OPEN_REQUIRING_OPLOCK旗標。 實作此旗標的 Microsoft 檔系統為 NTFS、FAT 和 exFAT。

CreateOptions 旗標FILE_RESERVE_OPFILTER可讓應用程式要求層級 1、批次或篩選 oplock，以防止其他應用程式收到共享違規。 不過，FILE_RESERVE_OPFILTER只適用於篩選 oplock。 若要使用它，您必須遵循下列步驟：

1. 使用FILE_RESERVE_OPFILTER 的 CreateOptions 、完全FILE_READ_ATTRIBUTES的 DesiredAccess 和完全FILE_SHARE_READ的 ShareAccess 發出建立要求 |FILE_SHARE_WRITE |FILE_SHARE_DELETE。

   • 如果已經有開啟的句柄，則建立要求會因為STATUS_OPLOCK_NOT_GRANTED而失敗，而下一個要求的 oplock 也會失敗。

   • 如果您開啟的存取權較多或較少共用，也會導致STATUS_OPLOCK_NOT_GRANTED失敗。

2. 如果建立要求成功，請要求 oplock。

3. 開啟檔案的另一個句柄以執行 I/O。

步驟 3 僅能針對篩選 oplock 進行這項操作。 步驟 3 中開啟的句柄可以有包含最多FILE_READ_ATTRIBUTES的 DesiredAccess |FILE_WRITE_ATTRIBUTES |FILE_READ_DATA |FILE_READ_EA |FILE_EXECUTE |SYNCHRONIZE |READ_CONTROL，但仍不會中斷篩選 oplock。 不過，任何大於 FILE_READ_ATTRIBUTES 的 DesiredAccess |FILE_WRITE_ATTRIBUTES |SYNCHRONIZE 會中斷層級 1 或批次 oplock，並使FILE_RESERVE_OPFILTER旗標不適用於這些 oplock 類型。

針對源自使用者模式的建立要求，如果驅動程式在IoCreateFileEx的Options參數中設定IO_FORCE_ACCESS_CHECK，則也應該在ObjectAttributes 參數中設定OBJ_FORCE_ACCESS_CHECK。 如需此旗標的資訊，請參閱OBJECT_ATTRIBUTES的屬性成員。

NTFS 是唯一實作FILE_RESERVE_OPFILTER的 Microsoft 文件系統。

IoCreateFileEx 可用來取得磁碟區的句柄。

規格需求

另請參閱

ACCESS_MASK

ACL

DEVICE_OBJECT

FILE_FULL_EA_INFORMATION

FltAcknowledgeEcp

FltAllocateExtraCreateParameter

FltAllocateExtraCreateParameterList

FltClose

FltCreateFileEx2

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoCreateFile

IoCreateFileSpecifyDeviceObjectHint

UNICODE_STRING

ZwClose

ZwCreateFile

ZwQueryInformationFile

ZwReadFile

ZwSetInformationFile

ZwWriteFile