SerCx2InitializeDeviceInit 函数 (sercx.h)

项目
02/29/2024

SerCx2InitializeDeviceInit 方法允许串行框架扩展的版本 2 (SerCx2) 在为串行控制器创建框架设备对象期间向驱动程序框架注册特定于扩展的属性。

语法

NTSTATUS SerCx2InitializeDeviceInit(
  [in, out] PWDFDEVICE_INIT DeviceInit
);

参数

[in, out] DeviceInit

指向 WDFDEVICE_INIT 结构的指针，它是一个不透明的结构，用于存储内核模式驱动程序框架 (KMDF) 用于创建框架设备对象的信息。串行控制器驱动程序接收指向此结构的指针，作为驱动程序的 EvtDriverDeviceAdd 回调函数的输入参数。

返回值

如果调用成功，SerCx2InitializeDeviceInit 将返回STATUS_SUCCESS。可能的错误返回值包括以下状态代码。

返回代码	说明
STATUS_INVALID_DEVICE_REQUEST	方法是在错误的 IRQL 下调用的，或者 DeviceInit 参数为 NULL。
STATUS_INSUFFICIENT_RESOURCES	资源不足，无法执行请求的操作。

注解

串行控制器驱动程序必须先从其 EvtDriverDeviceAdd 回调函数调用此方法，然后才能为串行控制器创建 WDFDEVICE 对象。

SerCx2InitializeDeviceInit 将特定于扩展的信息附加到驱动程序的 WDFDEVICE_INIT 结构。此信息使 SerCx2 能够代表串行控制器驱动程序执行某些操作。例如，SerCx2 接收客户端发送到串行控制器的 I/O 请求。

在创建框架设备对象以表示串行控制器之前，串行控制器驱动程序必须调用 SerCx2InitializeDeviceInit ，在调用 SerCx2InitializeDevice 方法以完成设备对象的初始化之前。驱动程序调用 WdfDeviceCreate 等方法来创建设备对象。

SerCx2InitializeDeviceInit 设置默认的安全描述符，允许内核模式驱动程序和用户模式驱动程序将 I/O 请求发送到 SerCx2。仅当应用程序使用管理员权限运行时，描述符才允许应用程序发送这些请求。为了指定此描述符，SerCx2 使用以下 SDDL 字符串：

"D:P(A;;GA;;;SY)(A;;GA;;;BA)(A;;GA;;;UD)" 如有必要，串行控制器驱动程序可以通过使用所需安全描述符调用 WdfDeviceInitAssignSDDLString 方法来替代默认设置。驱动程序必须在调用 SerCx2InitializeDeviceInit 之后但在调用 WdfDeviceCreate 之前调用 WdfDeviceInitAssignSDDLString。有关 SDDL 字符串的详细信息，请参阅设备对象的 SDDL。