共用方式為


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 篩選和函式驅動程式不會命名其裝置物件。 如需詳細資訊,請參閱 具名裝置物件

如果未提供裝置名稱 (即 DeviceNameNULL) ,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 來建立具名裝置物件。 如需詳細資訊,請參閱 建立裝置物件。 呼叫端負責設定傳回之裝置物件的特定成員。 如需詳細資訊,請參閱 初始化裝置物件 和裝置類型的特定檔。

請小心指定正確參數中的 DeviceTypeDeviceCharacteristics 值。 這兩個參數都會使用系統定義的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)

另請參閱

DEVICE_OBJECT

FsRtlRegisterUncProvider

IoAttachDevice

IoAttachDeviceToDeviceStack

IoCreateDeviceSecure

IoCreateSymbolicLink

IoDeleteDevice