Функция PcAddAdapterDevice (portcls.h)

Статья
08/07/2023

Функция 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 — это системная структура типа DRIVER_OBJECT.

[in] PhysicalDeviceObject

Указатель на физический объект устройства (PDO). PortCls передает этот указатель в качестве параметра вызова обработчику AddDevice адаптера. PDO — это системная структура типа DEVICE_OBJECT.

[in] StartDevice

Указатель на функцию, вызываемую операционной системой для запуска устройства. Дополнительные сведения см. в следующем разделе Примечания .

[in] MaxObjects

Указывает максимальное количество вложенных вычислений, регистрируемых вызовами PcRegisterSubdevice. Это число задает верхнюю границу общего числа объектов miniport, которые драйвер адаптера может создать.

[in] DeviceExtensionSize

Указывает размер расширения устройства. Используйте ноль для размера по умолчанию. Сведения о размерах расширений, предоставляемых пользователем, см. в следующем разделе Примечаний .

Возвращаемое значение

PcAddAdapterDevice возвращает STATUS_SUCCESS, если вызов был успешным. В противном случае возвращается соответствующий код ошибки.

Эта функция выполняет большую часть работы, необходимой обработчику AddDevice драйвера аудиоадаптера. PcAddAdapterDevice создает объект устройства, инициализирует контекст устройства и присоединяет объект устройства к стеку устройств.

Драйвер адаптера вызывает PcAddAdapterDevice при получении вызова обработчика AddDevice . Драйвер адаптера обычно устанавливает обработчик AddDevice , вызывая PcInitializeAdapterDriver, хотя драйвер также может установить обработчик другими способами. PcAddAdapterDevice создает объект функционального устройства (FDO) для PDO, переданного обработчику AddDevice .

DeviceExtensionSize обычно имеет нулевое значение. Некоторым драйверам адаптера может потребоваться зарезервировать дополнительное пространство в расширении устройства. В этом случае следует указать DeviceExtensionSize больше PORT_CLASS_DEVICE_EXTENSION_SIZE, который является размером по умолчанию. Любое значение больше нуля и меньше PORT_CLASS_DEVICE_EXTENSION_SIZE является недопустимым. Драйверы адаптера могут использовать любую часть расширения устройства после PORT_CLASS_DEVICE_EXTENSION_SIZE смещения. Они также могут использовать байты в диапазоне смещения от 16 до 31 включительно в системе с 32-разрядной адресацией и байтами в диапазоне смещения от 32 до 63 в системе с 64-разрядной адресацией. Если расширение рассматривается как массив ULONG_PTR, то для использования драйвером адаптера доступны элементы массива с четырех по семь.

Параметр StartDevice указывает на функцию типа PCPFNSTARTDEVICE, которая определяет файл заголовка portcls.h как:

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

Дополнительные сведения о процедурах PcAddAdapterDevice и драйвера адаптера device-startup и 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 с PDO, который принадлежит драйверу шины PCI. Драйвер адаптера не должен изменять данные в PDO, так как это повреждает память, принадлежащей драйверу шины PCI, и может привести к сбою системы.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 2000.
Целевая платформа	Универсальное
Верхняя часть	portcls.h (включая Portcls.h)
Библиотека	Portcls.lib
IRQL	PASSIVE_LEVEL

См. также раздел