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