IoCreateDevice 函数 (wdm.h)

项目
08/08/2023

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

要求

要求	值
目标平台	通用
标头	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)