ioCreateDevice 函式 (wdm.h)

發行項
02/27/2024

IoCreateDevice 例程會建立裝置物件以供驅動程式使用。

語法

NTSTATUS IoCreateDevice(
  [in]           PDRIVER_OBJECT  DriverObject,
  [in]           ULONG           DeviceExtensionSize,
  [in, optional] PUNICODE_STRING DeviceName,
  [in]           DEVICE_TYPE     DeviceType,
  [in]           ULONG           DeviceCharacteristics,
  [in]           BOOLEAN         Exclusive,
  [out]          PDEVICE_OBJECT  *DeviceObject
);

參數

[in] DriverObject

呼叫端之驅動程序物件的指標。每個驅動程式都會在其 DriverEntry 例程的參數中接收其驅動程式物件的指標。 WDM 函式和篩選驅動程式也會在其 AddDevice 例程中接收驅動程式對象指標。

[in] DeviceExtensionSize

指定要為裝置物件的裝置延伸模組配置驅動程式決定的位元元組數目。裝置擴充功能的內部結構是驅動程式定義的。

[in, optional] DeviceName

選擇性地指向緩衝區，其中包含命名裝置物件的 Null 終止 Unicode 字串。字串必須是完整路徑名稱。 WDM 篩選和函式驅動程式不會命名其裝置物件。如需詳細資訊，請參閱具名裝置物件。

如果未提供裝置名稱 (即 DeviceName 為 NULL) ，IoCreateDevice 所建立的裝置物件將不會 (，而且無法) 有任意訪問控制清單， (DACL) 相關聯。如需詳細資訊，請參閱安全性描述元。

[in] DeviceType

指定其中一個系統定義的FILE_DEVICE_XXX 常數，指出裝置類型 (，例如FILE_DEVICE_DISK或FILE_DEVICE_KEYBOARD) ，或新類型裝置的廠商定義值。如需詳細資訊，請參閱指定裝置類型。

[in] DeviceCharacteristics

指定一或多個系統定義的常數 ORed，以提供驅動程式裝置的其他資訊。如需可能裝置特性的清單，請參閱 DEVICE_OBJECT。如需如何指定裝置特性的詳細資訊，請參閱指定裝置特性。大部分驅動程式都會為此參數指定FILE_DEVICE_SECURE_OPEN。

[in] Exclusive

指定裝置物件是否代表獨佔裝置。大部分驅動程式都會將此值設定為 FALSE。如需獨佔存取的詳細資訊，請參閱指定裝置對象的獨佔存取權。

[out] DeviceObject

接收新建立 DEVICE_OBJECT 結構指標之變數的指標。 DEVICE_OBJECT 結構是從非分頁集區配置。裝置物件的裝置延伸模組為零。

傳回值

IoCreateDevice 會在成功時傳回STATUS_SUCCESS，或在失敗時傳回適當的 NTSTATUS 錯誤碼。這個函式傳回之失敗碼的部分清單包括：

STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_COLLISION

備註

IoCreateDevice 會建立裝置物件，並傳回物件的指標。呼叫端負責在呼叫 IoDeleteDevice不再需要物件時刪除物件。

IoCreateDevice 只能用來建立未命名的裝置物件，或由 INF 檔案設定安全性描述元的具名裝置物件。否則，驅動程式必須使用 IoCreateDeviceSecure 來建立具名裝置物件。如需詳細資訊，請參閱建立裝置物件。呼叫端負責設定傳回之裝置物件的特定成員。如需詳細資訊，請參閱初始化裝置物件和裝置類型的特定檔。

請小心指定正確參數中的 DeviceType 和 DeviceCharacteristics 值。這兩個參數都會使用系統定義的FILE_XXX 常數，而某些驅動程式寫入器會錯誤地指定錯誤參數中的值。

為網路重新導向器建立具名裝置對象的遠端文件系統，並使用 FsRtlRegisterUncProvider 註冊，必須將 FILE_REMOTE_DEVICE 指定為 IoCreateDevice 的 DeviceCharacteristics 參數中的其中一個選項。

磁碟、磁帶、CD-ROM 和 RAM 磁碟的裝置物件會獲得磁碟區參數區塊 (VPB) 初始化，以指出磁碟區從未掛接在裝置上。

如果驅動程式呼叫IoCreateDevice傳回錯誤，驅動程式應該釋放它為該裝置配置的任何資源。

規格需求

需求	值
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
DDI 合規性規則	AddDevice (wdm) 、 CheckDeviceObjectFlags (wdm) 、 HwStorPortProhibitedDDIs (storport) 、 IrqlIoPassive1 (wdm) 、 MiniportOnlyWdmDevice (kmdf)