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 的调用返回错误,则驱动程序应释放它为该设备分配的任何资源。
要求
要求 | 值 |
---|---|
目标平台 | 通用 |
标头 | 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) |