функция обратного вызова DRIVER_ADD_DEVICE (wdm.h)

  • Статья

Подпрограмма AddDevice отвечает за создание функциональных объектов устройств (FDO) или фильтрацию объектов устройств (фильтр DO) для устройств, перечисленных диспетчером Plug and Play (PnP).

Синтаксис

DRIVER_ADD_DEVICE DriverAddDevice;

NTSTATUS DriverAddDevice(
  [in] _DRIVER_OBJECT *DriverObject,
  [in] _DEVICE_OBJECT *PhysicalDeviceObject
)
{...}

Параметры

[in] DriverObject

Указатель на структуру DRIVER_OBJECT , предоставленный вызывающим. Это объект драйвера драйвера.

[in] PhysicalDeviceObject

Предоставленный вызывающим объектом указатель на структуру DEVICE_OBJECT , представляющую объект физического устройства (PDO), созданный драйвером более низкого уровня.

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

Если подпрограмма завершается успешно, она должна вернуть STATUS_SUCCESS. В противном случае он должен вернуть одно из значений состояния ошибки, определенных в ntstatus.h.

Комментарии

Все драйверы режима ядра, поддерживающие PnP, должны предоставлять подпрограмму AddDevice .

Подпрограмма AddDevice драйвера должна называться XxxAddDevice, где Xxx — это префикс для конкретного драйвера. Подпрограмма DriverEntry драйвера должна хранить адрес подпрограммы AddDevice в файле DriverObject-DriverExtension-AddDevice>>.

Основные обязанности подпрограммы AddDevice — вызов IoCreateDevice для создания объекта устройства, а затем вызов IoAttachDeviceToDeviceStack для подключения объекта устройства к стеку устройств. Подробные сведения о реализации процедуры AddDevice для драйвера см. в статье Создание процедуры AddDevice.

Подпрограмма AddDevice выполняется в контексте системного потока в IRQL = PASSIVE_LEVEL.

Примеры

Чтобы определить подпрограмму обратного вызова AddDevice , необходимо сначала предоставить объявление функции, определяющее тип определяемой процедуры обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить подпрограмму обратного вызова AddDevice с именем MyAddDevice<, используйте тип DRIVER_ADD_DEVICE, как показано в следующем примере кода:

DRIVER_ADD_DEVICE MyAddDevice;

Затем реализуйте процедуру обратного вызова следующим образом:

_Use_decl_annotations_
NTSTATUS
  MyAddDevice(
    struct _DRIVER_OBJECT  *DriverObject,
    struct _DEVICE_OBJECT  *PhysicalDeviceObject 
    )
  {
      // Function body
  }

Тип функции DRIVER_ADD_DEVICE определяется в файле заголовка Wdm.h. Чтобы более точно определить ошибки при запуске средств анализа кода, не забудьте добавить заметку _Use_decl_annotations_ в определение функции. Заметка _Use_decl_annotations_ гарантирует, что будут использоваться заметки, которые применяются к типу функции DRIVER_ADD_DEVICE в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в статье Объявление функций с помощью типов ролей функций для драйверов WDM. Сведения о _Use_decl_annotations_см. в статье Поведение функции с заметками.

Требования

Требование Значение
Целевая платформа Персональный компьютер
Верхняя часть wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
IRQL Вызывается по адресу PASSIVE_LEVEL (см. раздел "Замечания").