Функция 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

Указатель на объект driver. Этот указатель передается в качестве параметра обработчику AddDevice адаптера. Объект driver — это системная структура типа DRIVER_OBJECT.

[in] PhysicalDeviceObject

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

[in] StartDevice

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

[in] MaxObjects

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

[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 и программах запуска устройства и 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);

Переменная FunctionalDeviceObject — это указатель на FDO звукового адаптера, а pMyExtensionData — временный указатель на данные расширения. Избегайте путаницы FDO с PDO, который принадлежит драйверу шины PCI. Драйвер адаптера не должен изменять данные в PDO, так как это приводит к повреждению памяти, принадлежащей драйверу шины PCI, и может привести к сбою системы.

Требования

См. также

AddDevice

DEVICE_OBJECT

DRIVER_OBJECT

PcRegisterSubdevice