通过

pcAddAdapterDevice 函数 (portcls.h)

  • 项目

PcAddAdapterDevice 函数将适配器设备添加到 WDM 设备堆栈。

语法

PORTCLASSAPI NTSTATUS PcAddAdapterDevice(
  [in] PDRIVER_OBJECT   DriverObject,
  [in] PDEVICE_OBJECT   PhysicalDeviceObject,
  [in] PCPFNSTARTDEVICE StartDevice,
  [in] ULONG            MaxObjects,
  [in] ULONG            DeviceExtensionSize
);

参数

[in] DriverObject

指向驱动程序对象的指针。 此指针作为参数传递给适配器的 AddDevice 处理程序。 驱动程序对象是 DRIVER_OBJECT 类型的系统结构。

[in] PhysicalDeviceObject

指向设备 的物理设备对象的指针 (PDO) 。 PortCls 将此指针作为调用参数传递给适配器的 AddDevice 处理程序。 PDO 是 DEVICE_OBJECT 类型的系统结构。

[in] StartDevice

指向操作系统为启动设备而调用的函数的指针。 有关详细信息，请参阅以下 “备注” 部分。

[in] MaxObjects

指定要通过调用 PcRegisterSubdevice 注册的最大子设备数。 此计数将上限设置为适配器驱动程序可以实例化的微型端口对象总数。

[in] DeviceExtensionSize

指定设备扩展大小。 使用零表示默认大小。 有关用户提供的扩展大小，请参阅以下 “备注 ”部分。

返回值

如果调用成功，PcAddAdapterDevice 将返回STATUS_SUCCESS。 否则，它将返回相应的错误代码。

注解

此函数执行音频适配器驱动程序的 AddDevice 处理程序需要执行的大部分工作。 PcAddAdapterDevice 创建设备对象，初始化设备上下文，并将设备对象附加到设备堆栈。

适配器驱动程序在收到对其 AddDevice 处理程序的调用时调用 PcAddAdapterDevice。 适配器驱动程序通常通过调用 PcInitializeAdapterDriver 来安装 AddDevice 处理程序，但驱动程序也可以通过其他方式安装该处理程序。 PcAddAdapterDevice 为传递给 AddDevice 处理程序的 PDO 创建功能设备对象 (FDO) 。

DeviceExtensionSize 通常为零。 某些适配器驱动程序可能需要在设备扩展中保留额外的空间，在这种情况下，它们应指定大于 PORT_CLASS_DEVICE_EXTENSION_SIZE 的 DeviceExtensionSize ，这是默认大小。 任何大于零且小于 PORT_CLASS_DEVICE_EXTENSION_SIZE 的值都是非法的。 适配器驱动程序在偏移PORT_CLASS_DEVICE_EXTENSION_SIZE后可以免费使用设备扩展的任何部分。 在具有 32 位寻址的系统中，还可以免费使用偏移量范围为 16 到 31（含 36 到 31）的字节，在具有 64 位寻址的系统中使用偏移量范围为 32 到 63 的字节。 如果扩展被视为ULONG_PTR数组，则适配器驱动程序可以使用数组元素 4 到 7。

StartDevice 参数指向 PCPFNSTARTDEVICE 类型的函数，该函数头文件 portcls.h 定义为：

  NTSTATUS
    (*PCPFNSTARTDEVICE)(
      IN PDEVICE_OBJECT  DeviceObject,
      IN PIRP  Irp,
      IN PRESOURCELIST  ResourceList
      );

有关 PcAddAdapterDevice 以及适配器驱动程序的设备启动和 AddDevice 例程的详细信息，请参阅 启动序列。

以下示例代码演示适配器驱动程序如何使用 DeviceExtensionSize 参数将 64 字节特定于设备的扩展数据追加到 PortCls 为设备上下文分配的存储块的末尾：

  #define MY_EXTENSION_SIZE  64
  NTSTATUS  ntstatus = PcAddAdapterDevice(DriverObject, PhysicalDeviceObject,
                                          MyStartDevice, MAX_MINIPORTS,
                                          MY_EXTENSION_SIZE + PORT_CLASS_DEVICE_EXTENSION_SIZE);

上面的 PcAddAdapterDevice 调用类似于 启动序列中的示例，只不过传递给 PcAddAdapterDevice 的最后一个参数不为零。

然后，适配器驱动程序可以访问特定于设备的扩展数据，如以下代码片段所示：

  PVOID  pMyExtensionData = (PVOID)((PCHAR)FunctionalDeviceObject->DeviceExtension +
                                              PORT_CLASS_DEVICE_EXTENSION_SIZE);

Variable FunctionalDeviceObject 是指向音频适配器 FDO 的指针， pMyExtensionData 是指向扩展数据的临时指针。 避免将 FDO 与属于 PCI 总线驱动程序的 PDO 混淆。 适配器驱动程序不得修改 PDO 中的数据，因为这样做会损坏 PCI 总线驱动程序拥有的内存，并可能导致系统崩溃。

要求

要求 值
最低受支持的客户端 从 Windows 2000 开始可用。
目标平台 通用
标头 portcls.h (包括 Portcls.h)
Library Portcls.lib
IRQL PASSIVE_LEVEL

另请参阅

AddDevice

DEVICE_OBJECT

DRIVER_OBJECT

PcRegisterSubdevice