ioCreateDevice 函式 (wdm.h)
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) |