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 的调用返回错误,则驱动程序应释放它为该设备分配的任何资源。

要求

要求
目标平台 通用
标头 wdm.h(包括 Wdm.h、Ntddk.h、Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL IRQL <= APC_LEVEL
DDI 符合性规则 AddDevice (wdm) CheckDeviceObjectFlags (wdm) HwStorPortProhibitedDDI (storport) IrqlIoPassive1 (wdm) MiniportOnlyWdmDevice (kmdf)

另请参阅

DEVICE_OBJECT

FsRtlRegisterUncProvider

IoAttachDevice

IoAttachDeviceToDeviceStack

IoCreateDeviceSecure

IoCreateSymbolicLink

IoDeleteDevice