Функция IoRegisterPlugPlayNotification (wdm.h)

Подпрограмма ioRegisterPlugPlayNotification регистрирует подпрограмму обратного вызова уведомлений Plug and Play (PnP), вызываемую при возникновении события PnP указанной категории.

Синтаксис

NTSTATUS IoRegisterPlugPlayNotification(
  [in]           IO_NOTIFICATION_EVENT_CATEGORY        EventCategory,
  [in]           ULONG                                 EventCategoryFlags,
  [in, optional] PVOID                                 EventCategoryData,
  [in]           PDRIVER_OBJECT                        DriverObject,
  [in]           PDRIVER_NOTIFICATION_CALLBACK_ROUTINE CallbackRoutine,
  [in, optional] __drv_aliasesMem PVOID                Context,
  [out]          PVOID                                 *NotificationEntry
);

Параметры

[in] EventCategory

Указывает значение перечисления из IO_NOTIFICATION_EVENT_CATEGORY, указывающее категорию события PnP, для которого регистрируется подпрограмма обратного вызова.

[in] EventCategoryFlags

Пометка битов, изменяющих операцию регистрации. Возможные значения:

PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES

Допустимо только с EventCategoryEventCategoryDeviceInterfaceChange. Если задано, диспетчер PnP вызывает подпрограмму обратного вызова драйвера для каждого экземпляра интерфейса устройства, зарегистрированного и активного, и регистрирует подпрограмму обратного вызова для будущих поступлений или удаления экземпляров интерфейса устройства.

[in, optional] EventCategoryData

Указатель на дополнительные сведения о событиях, для которых регистрируется CallbackRoutine. Сведения зависят от различных значений EventCategory:

• Если EventCategoryEventCategoryDeviceInterfaceChange, EventCategoryData должен указывать на GUID, указывающий класс интерфейса устройства. callbackRoutine будет вызываться при включении или удалении интерфейса этого класса.

• Если EventCategoryEventCategoryHardwareProfileChange, EventCategoryData должны быть NULL.

• Если EventCategoryEventCategoryTargetDeviceChange, EventCategoryData должен указывать на объект файла, для которого запрашивается уведомление PnP.

[in] DriverObject

Указатель на объект драйвера вызывающего объекта.

Чтобы убедиться, что драйвер остается загруженным во время регистрации для уведомления PnP, этот вызов увеличивает число ссылок на DriverObject. Диспетчер PnP уменьшает количество ссылок при удалении этой регистрации.

Для EventCategoryTargetDeviceChange, DriverObject не должен быть объектом драйвера целевого устройства; скорее, это должен быть объект драйвера драйвера, реализующего CallbackRoutine.

[in] CallbackRoutine

Указатель на подпрограмму обратного вызова уведомлений PnP, которую необходимо вызвать при возникновении указанного события PnP.

Прототип функции для этой подпрограммы обратного вызова определяется следующим образом:

typedef NTSTATUS
  DRIVER_NOTIFICATION_CALLBACK_ROUTINE(
    _In_ PVOID NotificationStructure,
    _Inout_opt_ PVOID Context
    );

notificationStructure подпрограммы обратного вызова зависит от значения EventCategory, как показано в следующей таблице.

Параметр контекста контекста подпрограммы обратного вызова содержит данные контекста, предоставленные драйвером во время регистрации.

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

Диспетчер PnP вызывает процедуры обратного вызова драйвера в IRQL = PASSIVE_LEVEL.

[in, optional] Context

Указатель на выделенный вызывающим буфером, содержащий контекст, который диспетчер PnP передает в подпрограмму обратного вызова.

[out] NotificationEntry

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

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

IoRegisterPlugPlayNotification возвращает STATUS_SUCCESS или соответствующее состояние ошибки.

Замечания

Драйвер регистрируется для категории событий. Каждая категория включает один или несколько типов событий PnP.

Драйвер может зарегистрировать различные подпрограммы обратного вызова для различных категорий событий или зарегистрировать одну подпрограмму обратного вызова. Одна подпрограмма обратного вызова может привести NotificationStructure к PLUGPLAY_NOTIFICATION_HEADER и использовать поле Event для определения точного типа структуры уведомлений.

Если вызывающий объект указывает PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES, операционная система может дважды вызывать подпрограмму обратного вызова уведомлений PnP для одного события EventCategoryDeviceInterfaceChange для существующего интерфейса. Вы можете безопасно игнорировать второй вызов обратного вызова. Операционная система не будет вызывать обратный вызов более чем в два раза для одного события.

Подпрограммы обратного вызова уведомлений PnP должны выполнять свои задачи как можно быстрее и возвращать управление диспетчеру PnP, чтобы предотвратить задержки в уведомлении других драйверов и приложений, зарегистрированных для события.

Диспетчер PnP не извлекает ссылку на файловый объект, когда драйвер регистрирует уведомление о событии EventCategoryTargetDeviceChange. Если подпрограмма обратного вызова уведомлений PnP драйвера требует доступа к объекту файла, драйвер должен извлечь дополнительную ссылку на объект файла перед вызовом IoRegisterPlugPlayNotification.

Как правило, драйверы Kernel-Mode Driver Framework (KMDF) должны вызывать ioRegisterPlugPlayNotification из функции обратного вызова EvtDeviceSelfManagedIoInit и вызывать IoUnregisterPlugPlayNotification из функции обратного вызова EvtDeviceSelfManagedIoCleanup обратного вызова. Эти драйверы должны не вызывать ioRegisterPlugPlayNotification из функции обратного вызова EvtDriverDeviceAdd; В противном случае подпрограмма обратного вызова уведомлений PnP может вызываться до запуска стека драйверов с помощью PnP, в этом случае драйвер не будет готов обрабатывать уведомление.

Дополнительные сведения см. в с помощьюуведомления PnP.

Примеры

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

Например, чтобы определить подпрограмму обратного вызова уведомлений PnP с именем MyCallbackRoutine, используйте тип DRIVER_NOTIFICATION_CALLBACK_ROUTINE, как показано в этом примере кода:

DRIVER_NOTIFICATION_CALLBACK_ROUTINE MyCallbackRoutine;

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

_Use_decl_annotations_
NTSTATUS
  MyCallbackRoutine(
    PVOID NotificationStructure,
    PVOID Context
    )
  {
      // Function body
  }

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

Требования

См. также

использование уведомлений PnP

DEVICE_INTERFACE_CHANGE_NOTIFICATION

EvtDeviceSelfManagedIoCleanup

EvtDeviceSelfManagedIoInit

EvtDriverDeviceAdd

HWPROFILE_CHANGE_NOTIFICATION

IoUnregisterPlugPlayNotification

IoUnregisterPlugPlayNotificationEx

PLUGPLAY_NOTIFICATION_HEADER

TARGET_DEVICE_CUSTOM_NOTIFICATION

TARGET_DEVICE_REMOVAL_NOTIFICATION