WdmlibIoCreateDeviceSecure 函数 (wdmsec.h)

WdmlibIoCreateDeviceSecure 函数 (或 IoCreateDeviceSecure) 创建命名设备对象并应用指定的安全设置。

语法

NTSTATUS WdmlibIoCreateDeviceSecure(
  [in]           PDRIVER_OBJECT   DriverObject,
  [in]           ULONG            DeviceExtensionSize,
  [in, optional] PUNICODE_STRING  DeviceName,
  [in]           DEVICE_TYPE      DeviceType,
  [in]           ULONG            DeviceCharacteristics,
  [in]           BOOLEAN          Exclusive,
  [in]           PCUNICODE_STRING DefaultSDDLString,
  [in, optional] LPCGUID          DeviceClassGuid,
                 PDEVICE_OBJECT   *DeviceObject
);

参数

[in] DriverObject

指向调用方驱动程序对象的指针。 每个驱动程序在参数中接收指向其 DriverEntry 例程的驱动程序对象的指针。 WDM 函数和筛选器驱动程序还会在其 AddDevice 例程中接收驱动程序对象指针。

[in] DeviceExtensionSize

指定要为 设备对象的设备扩展 分配的驱动程序确定的字节数。 设备扩展的内部结构是驱动程序定义的。

[in, optional] DeviceName

(可选)指向包含命名设备对象的空终止 Unicode 字符串的缓冲区。 字符串必须是完整路径名称。 如果未提供名称,FILE_AUTOGENERATED_DEVICE_NAME标志必须存在于 DeviceCharacteristics 参数中。 (若要创建未命名的设备对象,请使用 IoCreateDevice 例程.)

[in] DeviceType

指定系统定义的FILE_DEVICE_XXX 常量之一,该常量指示设备 (的类型,例如FILE_DEVICE_DISK、FILE_DEVICE_KEYBOARD等) ,或新类型的设备的供应商定义值。 有关详细信息,请参阅 指定设备类型。 (由于总线驱动程序可能没有有关设备类型的信息,因此可以在 INF AddReg 指令中指定 PDO 的设备类型值。)

[in] DeviceCharacteristics

指定一个或多个系统定义的常量(ORed)一起提供驱动程序设备的其他信息。 有关可能的设备特征的列表,请参阅 DEVICE_OBJECT。 有关如何指定设备特征的详细信息,请参阅 指定设备特征。 大多数驱动程序都为此参数指定FILE_DEVICE_SECURE_OPEN。

[in] Exclusive

指定设备对象是否表示 独占设备。 大多数驱动程序将此值设置为 FALSE。 有关详细信息,请参阅 指定对设备对象的独占访问

[in] DefaultSDDLString

指定设备对象的默认安全设置的字符串表示形式。 应用于设备对象的安全性派生自此字符串,除非系统管理员在 DeviceClassGuid 参数标识的注册表部分中放置替代。

安全设置是在安全描述符定义语言 (SDDL) 子集中指定的。 还提供了一组预定义常量, (SDDL_DEVOBJ_XXX) 。 有关详细信息,请参阅 保护设备对象

[in, optional] DeviceClassGuid

指向 GUID 的指针,该 GUID 标识注册表的一部分,其中包含 DefaultSDDLStringDeviceTypeDeviceCharacteristics独占 参数的可能替代。

注意 应始终指定自定义类 GUID。 不应指定现有类 GUID。 如果指定现有类 GUID,则尝试指定现有类 GUID 的其他驱动程序可能无法安装,或者可能会安装不正确的安全设置。
 

DeviceObject

指向接收指向新创建的 DEVICE_OBJECT 结构的指针的变量的指针。 DEVICE_OBJECT结构是从非分页池分配的。

返回值

WdmlibIoCreateDeviceSecure 在成功时返回STATUS_SUCCESS,或者在失败时返回相应的 NTSTATUS 错误代码。 此函数可能返回的故障代码的部分列表包括:

注解

WdmlibIoCreateDeviceSecure 创建命名设备对象,应用指定的安全设置,并返回指向该对象的指针。 调用方负责在调用 IoDeleteDevice 不再需要对象时删除该对象。

此例程不是操作系统的一部分。 驱动程序可以通过链接到 Microsoft Windows 2000 及更高版本的 Windows 上的 Wdmsec.lib 来使用例程。 (Wdmsec.lib 库首先随附了 Microsoft Windows XP Service Pack 1 [SP1] 和 Windows Server 2003 版本的驱动程序开发工具包 [DDK],还随附 Windows 驱动程序工具包 [WDK].)

创建命名设备对象的任何驱动程序都必须使用 WdmlibIoCreateDeviceSecure,该对象不保证其安全描述符由 INF 文件设置。 有关详细信息,请参阅 创建设备对象。 调用方负责设置返回的设备对象的某些成员。 有关详细信息,请参阅 初始化设备对象 和设备类型特定的文档。

请务必在正确的参数中指定 DeviceTypeDeviceCharacteristics 值。 这两个参数都使用系统定义的FILE_XXX 常量,某些驱动程序编写器错误地指定错误参数中的值。

调用方负责在返回的设备对象(如 “标志 ”字段)中设置某些字段,以及使用任何驱动程序定义的信息初始化设备扩展。 有关新设备对象上所需的其他操作,请参阅 初始化设备对象 和设备类型特定的文档。

DeviceClassGuid 参数指定的 GUID 确定设备对象的设备设置类。 (有关设备设置类的详细信息,请参阅 设备安装类。) 调用方必须提供一个值,以便系统管理员可以更改设备 (的安全设置,以拒绝访问某些用户) 。 有关详细信息,请参阅 安装后设置设备对象注册表属性

非 WDM 驱动程序指定新的 GUID,现有设备安装类尚未使用。 使用Microsoft Windows SDK中包含的GuidGen.exe工具生成新的 GUID。

处理支持原始模式设备的 WDM 总线驱动程序可以指定设备的设备设置类,但前提是该类已保证已创建。 否则,请创建新的 GUID。

为磁盘、磁带、CD-ROM 和 RAM 磁盘提供卷参数块 (VPB) ,该块已初始化,以指示从未在设备上装载卷。

如果驱动程序对 WdmlibIoCreateDeviceSecure 的调用返回错误,驱动程序应释放为该设备分配的任何资源。

要求

   
最低受支持的客户端 请参阅“备注”部分。
目标平台 桌面
Header wdmsec.h (包括 Wdmsec.h)
Library Wdmsec.lib
IRQL PASSIVE_LEVEL
DDI 符合性规则 AddDevice (wdm) HwStorPortProhibitedDIS (storport) IrqlIoPassive1 (wdm) 、MiniportOnlyWdmDevice

另请参阅

DEVICE_OBJECT

IoAttachDevice

IoAttachDeviceToDeviceStack

IoCreateDevice

IoCreateSymbolicLink

IoDeleteDevice